Workflows

Last updated on September 15, 2026

Overview

Workflows are YAML files with typed inputs, ordered steps, and explicit step dependencies. A value produced by one step passes to the next by reference. You can run a workflow in dry-run mode to see every call and its inputs before any change is applied.

Built-in workflows

The AGS CLI includes five built-in workflows for common tasks:

Workflow ID	Name in ags workflow list	What it does
competitive-multiplayer	Set up competitive multiplayer	Sets up skill-based matchmaking on dedicated servers hosted by AccelByte Multiplayer Servers (AMS), pairing players by a rating stat.
player-overview	Investigate a player	Collects a read-only overview of one player across AGS services.
in-game-store	Create an in-game store	Creates an in-game store priced in a virtual currency, then publishes it.
season-pass	Create a season pass	Builds a season pass with free and premium tracks, item rewards, and tiers in an existing draft store, then publishes it.
docker-login	Docker registry login	Fetches container registry credentials for an Extend app and signs the local Docker CLI in to that registry.

Author a workflow

Generate a starter template

ags workflow template

This prints a starter YAML file you can edit. The file already declares workflow_protocol_version, which ags workflow add requires.

Validate before adding

ags workflow add <file> --validate-only

This checks the file for schema errors and missing inputs without adding it.

Add a validated workflow

ags workflow add <file>

Run in dry-run mode

ags workflow run <id> --dry-run

No changes are applied. The CLI prints every step, its command, and its resolved inputs so you can confirm the plan before committing.

Remove a workflow

ags workflow remove <id>

This removes a workflow you added with ags workflow add. Built-in workflows cannot be removed.

Example: seasonal leaderboard

This example sets up a seasonal leaderboard using three ordered admin calls across two services.

1. Create a stat cycle. This defines the reset schedule. AGS returns a cycle ID that steps 2 and 3 both use.
2. Create a stat. This is the value the leaderboard ranks players by. It uses the cycle ID from step 1 to tie the stat to the reset schedule.
3. Create a leaderboard. This ranks players by the stat from step 2 and is scoped to the same cycle. It uses the cycle ID from step 1 and the stat from step 2 as inputs.

The complete workflow file

id: seasonal-leaderboard
name: Set up a seasonal leaderboard
workflow_protocol_version: "1.0.0"
intent: leaderboard stat cycle seasonal reset ranking social
description: >-
  Set up a leaderboard that resets every season: a stat cycle, a stat
  tied to that cycle, and a leaderboard scoped to the same cycle.

briefing:
  overview: >-
    This workflow sets up a seasonal leaderboard, such as "Most Matches Won
    This Season", instead of an all-time ranking.


    Doing this manually takes three ordered admin API calls across two
    services, Stats and Leaderboard. The id returned by the first call has
    to be passed into the other two. This workflow creates all three
    resources and passes that id along.
  prerequisites:
    - >-
      **A namespace** already created. Everything this workflow creates
      lives inside that namespace.
    - >-
      **Admin credentials** with permission to create resources in
      `social` and `leaderboard`. The workflow uses your current `ags`
      login session.
  creates:
    - "**A seasonal stat cycle.** Defines the reset schedule used below."
    - "**A stat.** The value the leaderboard ranks players by, tied to that cycle."
    - "**A leaderboard.** Ranked by that stat and scoped to the same cycle."

is_reviewed_by_default: true

inputs:
  - name: namespace
    description: >-
      Your game's AccelByte namespace. This is the same value used by the
      global --namespace flag.
    required: true
    schema: {type: string}

  - name: leaderboardCode
    description: >-
      Unique code for the leaderboard, lowercase and up to 48 characters.
      Also used as its display name.
    required: true
    schema: {type: string}

  - name: statCode
    description: >-
      Unique code for the stat the leaderboard ranks players by, for
      example matches won this season. Also used as its display name.
    required: true
    schema: {type: string}

steps:
  - id: create-stat-cycle
    description: >-
      Creates the seasonal reset schedule. The stat and leaderboard below
      both use the id returned by this step.
    operation: {service: social, operation: social/admin/stat-cycles/v1/create}
    inputs:
      - {field: namespace, source: {from: "workflow/namespace"}}
      - {field: cycleType, source: {const: "SEASONAL"}, show_in_review: true}
      - {field: name, source: {const: "Seasonal Reset"}, show_in_review: true}
      - {field: resetTime, source: {const: "00:00"}, show_in_review: true}
      - {field: start, source: {const: "2025-01-01T00:00:00Z"}, show_in_review: true}
      - {field: seasonPeriod, source: {const: 90}, show_in_review: true, description: "Season length in days"}
    outputs:
      - {name: cycleId, source: responseBody, path: "$.id"}

  - id: create-stat
    description: >-
      Creates the stat the leaderboard ranks players by, tied to the
      seasonal cycle above so it resets at the same time.
    dependencies: [create-stat-cycle]
    operation: {service: social, operation: social/admin/stat-definitions/v1/create}
    inputs:
      - {field: namespace, source: {from: "workflow/namespace"}}
      - {field: statCode, source: {from: "workflow/statCode"}}
      - {field: name, source: {from: "workflow/statCode"}, show_in_review: true}
      - {field: defaultValue, source: {const: 0}, show_in_review: true}
      - {field: setBy, source: {const: "SERVER"}}
      - {field: "cycleIds[0]", source: {from: "step/create-stat-cycle", output: cycleId}}

  - id: create-leaderboard
    description: >-
      Creates the leaderboard, ranked by the stat above and scoped to the
      same seasonal cycle.
    dependencies: [create-stat-cycle, create-stat]
    operation: {service: leaderboard, operation: leaderboard/admin/leaderboards/v3/create}
    inputs:
      - {field: namespace, source: {from: "workflow/namespace"}}
      - {field: leaderboardCode, source: {from: "workflow/leaderboardCode"}}
      - {field: name, source: {from: "workflow/leaderboardCode"}, show_in_review: true}
      - {field: statCode, source: {from: "workflow/statCode"}}
      - {field: descending, source: {const: true}, show_in_review: true}
      - {field: allTime, source: {const: false}, show_in_review: true}
      - {field: "cycleIds[0]", source: {from: "step/create-stat-cycle", output: cycleId}}

completion:
  created:
    - {label: "Stat cycle", value: "Seasonal Reset"}
    - {label: "Stat", value: "{statCode}"}
    - {label: "Leaderboard", value: "{leaderboardCode}"}
  next_steps:
    - {description: "Inspect the leaderboard", command: "ags leaderboard leaderboards get --namespace {namespace} --leaderboard-code {leaderboardCode}"}
    - {description: "Review the stat", command: "ags social stat-definitions get --namespace {namespace} --stat-code {statCode}"}
    - {description: "List your stat cycles", command: "ags social stat-cycles list --namespace {namespace}"}

Run it with the inputs shown in the file, for example ags workflow run seasonal-leaderboard --namespace <your-namespace> --leaderboard-code weekly-wins --stat-code matches-won-season.