Workflow configuration

Define multi-step automation workflows in .asc/workflow.json

Workflows allow you to define multi-step automation sequences in a .asc/workflow.json file. This is useful for complex release processes that involve multiple commands.

Workflow file structure

Create a .asc/workflow.json file in your project root:

{
  "env": {
    "APP_ID": "123456789",
    "VERSION": "1.2.0"
  },
  "before_all": "echo 'Starting workflow'",
  "after_all": "echo 'Workflow complete'",
  "error": "echo 'Workflow failed' && exit 1",
  "workflows": {
    "testflight": {
      "description": "Upload build to TestFlight",
      "steps": [
        "asc builds upload --app $APP_ID --ipa MyApp.ipa",
        "asc builds list --app $APP_ID --limit 1",
        "asc builds info --app $APP_ID --latest --output json"
      ]
    },
    "release": {
      "description": "Publish build to the App Store",
      "steps": [
        "asc publish appstore --app $APP_ID --ipa ./build/MyApp.ipa --version $VERSION --submit --confirm"
      ]
    }
  }
}

Running workflows

Execute a workflow by name:

asc workflow run --file .asc/workflow.json testflight

Or use the short form:

asc workflow run testflight

When --file is omitted, the CLI looks for .asc/workflow.json in the current directory.

Workflow schema

Top-level fields

object

Global environment variables available to all workflows

"env": {
  "APP_ID": "123456789",
  "API_KEY": "secret-value"
}

string

Command to run before any workflow executesUseful for validation or setup tasks.

string

Command to run after a workflow completes successfullyUseful for cleanup or notifications.

string

Command to run if a workflow failsUseful for error notifications or rollback.

object

required

Map of workflow names to workflow definitions

Workflow fields

string

Human-readable description of the workflow

boolean

Hide this workflow from asc workflow listDefault: false

object

Workflow-specific environment variablesThese override global env variables.

array

required

List of steps to execute (see step format below)

Step formats

Steps can be defined in two formats: Short form (string):

"steps": [
  "asc apps list",
  "asc builds list --app 123456789"
]

Long form (object):

"steps": [
  {
    "name": "Upload build",
    "run": "asc builds upload --app $APP_ID --ipa MyApp.ipa"
  },
  {
    "name": "Verify upload",
    "run": "asc builds list --app $APP_ID --limit 1",
    "if": "$VERIFY == true"
  },
  {
    "name": "Run sub-workflow",
    "workflow": "notify",
    "with": {
      "MESSAGE": "Build uploaded"
    }
  }
]

Step fields

string

Step name (displayed during execution)

string

Shell command to execute

string

Name of another workflow to run (sub-workflow)Mutually exclusive with run.

string

Condition expression (evaluated as shell command)Step runs only if the command exits with code 0.

object

Environment variables passed to the stepOnly applies to workflow steps.

Environment variable precedence

Environment variables are resolved in this order (highest to lowest):

Runtime parameters (KEY:VALUE arguments to asc workflow run)
Step with field (for sub-workflows)
Workflow env field
Global env field
System environment variables

Example:

asc workflow run testflight APP_ID:987654321

This overrides the APP_ID defined in the workflow file.

Conditional steps

Use the if field to conditionally execute steps:

{
  "steps": [
    {
      "name": "Upload build",
      "run": "asc builds upload --app $APP_ID --ipa MyApp.ipa"
    },
    {
      "name": "Publish to the App Store",
      "run": "asc publish appstore --app $APP_ID --ipa ./build/MyApp.ipa --version $VERSION --submit --confirm",
      "if": "test \"$AUTO_SUBMIT\" = \"true\""
    }
  ]
}

The if condition is evaluated as a shell command. The step runs only if the command exits with code 0.

Sub-workflows

Call other workflows from within a workflow:

{
  "workflows": {
    "notify": {
      "description": "Send notification",
      "steps": [
        "asc notify slack --message \"$MESSAGE\""
      ]
    },
    "release": {
      "description": "Full release process",
      "steps": [
        "asc builds upload --app $APP_ID --ipa MyApp.ipa",
        {
          "workflow": "notify",
          "with": {
            "MESSAGE": "Build uploaded to TestFlight"
          }
        },
        "asc publish appstore --app $APP_ID --ipa MyApp.ipa --version $VERSION --submit --confirm",
        {
          "workflow": "notify",
          "with": {
            "MESSAGE": "Published App Store submission started"
          }
        }
      ]
    }
  }
}

Lifecycle hooks

Workflow hooks run at specific points during execution:

before_all: Runs before any workflow starts
after_all: Runs after a workflow completes successfully
error: Runs if any step fails

Example with Slack notifications:

{
  "before_all": "asc notify slack --message 'Starting release workflow'",
  "after_all": "asc notify slack --message 'Release complete'",
  "error": "asc notify slack --message 'Release failed' && exit 1",
  "workflows": {
    "release": {
      "steps": [
        "asc builds upload --app $APP_ID --ipa MyApp.ipa",
        "asc publish appstore --app $APP_ID --ipa MyApp.ipa --version $VERSION --submit --confirm"
      ]
    }
  }
}

Complete example

Here’s a comprehensive workflow for a full release process:

{
  "env": {
    "APP_ID": "123456789",
    "VERSION": "1.2.0",
    "BUILD_DIR": "build",
    "SLACK_WEBHOOK": "https://hooks.slack.com/services/..."
  },
  "before_all": "echo 'Starting release for v$VERSION'",
  "after_all": "echo 'Release complete for v$VERSION'",
  "error": "curl -X POST $SLACK_WEBHOOK -d '{\"text\":\"Release failed for v$VERSION\"}'  && exit 1",
  "workflows": {
    "beta": {
      "description": "Upload build to TestFlight",
      "steps": [
        {
          "name": "Validate build",
          "run": "test -f $BUILD_DIR/MyApp.ipa"
        },
        {
          "name": "Upload to TestFlight",
          "run": "asc builds upload --app $APP_ID --ipa $BUILD_DIR/MyApp.ipa"
        },
        {
          "name": "Wait for processing",
          "run": "sleep 60"
        },
        {
          "name": "Verify build available",
          "run": "asc builds list --app $APP_ID --limit 1 --output json | jq -e '.data[0]'"
        },
        {
          "name": "Notify team",
          "workflow": "notify",
          "with": {
            "MESSAGE": "New TestFlight build available: v$VERSION"
          }
        }
      ]
    },
    "release": {
      "description": "Publish to the App Store",
      "steps": [
        {
          "name": "Validate version",
          "run": "asc validate --app $APP_ID --version $VERSION"
        },
        {
          "name": "Run App Store publish command",
          "run": "asc publish appstore --app $APP_ID --ipa $BUILD_DIR/MyApp.ipa --version $VERSION --submit --confirm"
        },
        {
          "name": "Notify team",
          "workflow": "notify",
          "with": {
            "MESSAGE": "v$VERSION submitted to App Store review"
          }
        }
      ]
    },
    "notify": {
      "description": "Send Slack notification",
      "private": true,
      "steps": [
        "curl -X POST $SLACK_WEBHOOK -d '{\"text\":\"$MESSAGE\"}'"
      ]
    }
  }
}

CI/CD integration

GitHub Actions

name: Release
on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v3
      - uses: rudrankriyam/setup-asc@v1
        with:
          key-id: ${{ secrets.ASC_KEY_ID }}
          issuer-id: ${{ secrets.ASC_ISSUER_ID }}
          private-key: ${{ secrets.ASC_PRIVATE_KEY }}
      
      - name: Build app
        run: xcodebuild -scheme MyApp -archivePath build/MyApp.xcarchive archive
      
      - name: Run release workflow
        run: asc workflow run release VERSION:${{ github.ref_name }}

GitLab CI

release:
  stage: deploy
  script:
    - asc workflow run release VERSION:$CI_COMMIT_TAG
  only:
    - tags
  variables:
    ASC_KEY_ID: $ASC_KEY_ID
    ASC_ISSUER_ID: $ASC_ISSUER_ID
    ASC_PRIVATE_KEY_B64: $ASC_PRIVATE_KEY_B64

Security considerations

Workflow files execute arbitrary shell commands. Ensure:

.asc/workflow.json is added to .gitignore if it contains secrets
Use environment variables for sensitive values
Review workflow files before execution
Run workflows in trusted environments only

Troubleshooting

Workflow not found

asc workflow list  # List all available workflows
asc workflow run --file .asc/workflow.json testflight  # Specify file explicitly

Environment variable not expanded

Ensure variables are defined in the workflow file or passed as KEY:VALUE arguments:

asc workflow run testflight APP_ID:123456789

Step fails silently

Check exit codes and stderr:

asc --debug workflow run testflight

Workflow command

Workflow command reference

Automation guide

Workflow automation patterns

Getting Started

Core Concepts

Guides

CI/CD Integration

Configuration

Workflows

Workflow configuration

Workflow file structure

Running workflows

Workflow schema

Top-level fields

Workflow fields

Step formats

Step fields

Environment variable precedence

Conditional steps

Sub-workflows

Lifecycle hooks

Complete example

CI/CD integration

GitHub Actions

GitLab CI

Security considerations

Troubleshooting

Workflow not found

Environment variable not expanded

Step fails silently

Workflow command

Automation guide

​Workflow configuration

​Workflow file structure

​Running workflows

​Workflow schema

​Top-level fields

​Workflow fields

​Step formats

​Step fields

​Environment variable precedence

​Conditional steps

​Sub-workflows

​Lifecycle hooks

​Complete example

​CI/CD integration

​GitHub Actions

​GitLab CI

​Security considerations

​Troubleshooting

​Workflow not found

​Environment variable not expanded

​Step fails silently

​Related

Workflow command

Automation guide

Workflow configuration

Workflow file structure

Running workflows

Workflow schema

Top-level fields

Workflow fields

Step formats

Step fields

Environment variable precedence

Conditional steps

Sub-workflows

Lifecycle hooks

Complete example

CI/CD integration

GitHub Actions

GitLab CI

Security considerations

Troubleshooting

Workflow not found

Environment variable not expanded

Step fails silently

Related