Skip to main content

​
workflow

Run multi-step automation workflows with workflow.json
Define named, multi-step automation sequences in .asc/workflow.json. Each workflow composes existing asc commands and shell commands, keeps stdout machine-parseable JSON, and supports reusable sub-workflows.

​
Quick start

asc workflow list
asc workflow validate
asc workflow run beta

​
Workflow file format

Workflows are defined in .asc/workflow.json: 
{
  "env": {
    "APP_ID": "123456789",
    "VERSION": "1.0.0",
    "IPA_PATH": "./build/MyApp.ipa"
  },
  "before_all": "asc auth status",
  "after_all": "echo workflow_done",
  "error": "echo workflow_failed",
  "workflows": {
    "beta": {
      "description": "Distribute a build to a TestFlight group",
      "env": {
        "GROUP_ID": ""
      },
      "steps": [
        {
          "name": "resolve_build",
          "run": "asc builds info --app $APP_ID --latest --platform IOS --output json",
          "outputs": {
            "BUILD_ID": "$.data.id"
          }
        },
        {
          "name": "add_build_to_group",
          "run": "asc builds add-groups --build-id ${steps.resolve_build.BUILD_ID} --group $GROUP_ID"
        }
      ]
    },
    "release": {
      "description": "Run the full App Store release pipeline",
      "steps": [
        {
          "workflow": "preflight",
          "with": {
            "NOTE": "running private sub-workflow"
          }
        },
        {
          "name": "release",
          "run": "asc publish appstore --app $APP_ID --ipa $IPA_PATH --version $VERSION --submit --confirm"
        }
      ]
    },
    "preflight": {
      "private": true,
      "description": "Private helper workflow",
      "steps": [
        {
          "name": "preflight",
          "run": "echo \"$NOTE\""
        }
      ]
    }
  }
}

​
Commands

​
workflow list

List public workflows from workflow.json: 
asc workflow list
asc workflow list --all
asc workflow list --file ./custom-workflows.json

​
workflow validate

Validate structure, references, cycles, and output declarations: 
asc workflow validate
asc workflow validate --file ./.asc/workflow.json

​
workflow run

Run a workflow by name and pass runtime parameters as KEY:VALUE arguments: 
asc workflow run beta
asc workflow run beta BUILD_ID:123456789 GROUP_ID:abcdef
asc workflow run release VERSION:2.1.0
asc workflow run --dry-run beta
asc workflow run --resume beta-20260312T120000Z-deadbeef release

​
Features

​
Hooks

Use before_all, after_all, and error hooks for common setup, cleanup, or failure handling.

​
Sub-workflows

Steps can reference another workflow with a workflow key and pass scoped variables through with.

​
Persistent outputs

If a step emits JSON and declares outputs, later steps can reference values like ${steps.resolve_build.BUILD_ID}.

​
Repo-local run state

Workflow runs persist state next to the workflow file so you can resume interrupted runs with --resume.

​
Output

All workflow commands emit JSON to stdout. Step and hook output streams to stderr so stdout stays machine-parseable.

​
Security notes

Workflows intentionally execute arbitrary shell commands. Only run workflow files you trust, especially when using --file.
  • Treat .asc/workflow.json like code and review it before running
  • asc workflow validate checks structure and wiring, not shell-command safety
  • Steps inherit your process environment, so be careful with secrets
  • Declared outputs are persisted in run-state files; avoid mapping secrets into outputs

Workflow configuration

Learn the workflow file structure and patterns

Automation guide

See release automation examples and production patterns