How to Deploy a Step Functions State Machine With GitHub Actions

Push the Amazon States Language definition to an existing state machine with aws stepfunctions update-state-machine.

Keep the ASL definition in the repo and apply it with aws stepfunctions update-state-machine --definition file://.... For provisioning a new machine, prefer SAM or CloudFormation; this updates one that exists.

Steps

• Store the state machine definition as JSON in the repo.
• Authenticate to AWS over OIDC.
• Run aws stepfunctions update-state-machine --state-machine-arn ... --definition file://....
• Optionally pass --role-arn to update the execution role.

Workflow

permissions:
  id-token: write
  contents: read
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/gha-sfn-deploy
          aws-region: us-east-1
      - run: |
          aws stepfunctions update-state-machine \
            --state-machine-arn arn:aws:states:us-east-1:123456789012:stateMachine:orders \
            --definition file://statemachine/orders.asl.json

Gotchas

• An invalid ASL definition fails with InvalidDefinition; lint it before deploying.
• Updates are eventually consistent; new executions may briefly use the prior definition.

Related guides