Deploy from GitHub Actions

The Suta action plans your suta.yaml on each pull request and comments the plan, so reviewers see which devices change before anyone merges. After the merge, it deploys exactly what was reviewed and waits for the rollout to finish.

Before you begin

• Commit suta.yaml and the suta.lock that suta plan writes beside it.
• Create an API token with the Operator role or another role that can deploy.
• In your repository, go to Settings > Secrets and variables > Actions and add the token as a secret named SUTA_TOKEN.

Add the workflow

1. Create .github/workflows/suta.yml:

   name: Suta
   on:
     pull_request:
       paths: [suta.yaml, suta.lock]
     push:
       branches: [main]
       paths: [suta.yaml, suta.lock]
   concurrency:
     group: suta-${{ github.ref }}
   jobs:
     plan:
       if: github.event_name == 'pull_request'
       runs-on: ubuntu-latest
       permissions:
         contents: read
         pull-requests: write
       steps:
         - uses: actions/checkout@v4
         - uses: suta-dev/suta/action@main
           with:
             command: plan
             token: ${{ secrets.SUTA_TOKEN }}
     deploy:
       if: github.event_name == 'push'
       runs-on: ubuntu-latest
       permissions:
         contents: read
       steps:
         - uses: actions/checkout@v4
         - uses: suta-dev/suta/action@main
           with:
             command: deploy
             token: ${{ secrets.SUTA_TOKEN }}
             message: ${{ github.event.head_commit.message }}

2. Open a pull request that changes suta.yaml. The plan job comments the plan on the pull request and updates the same comment on every push.

3. Merge the pull request. The deploy job plans again from the committed suta.lock, starts the rollout and waits. It fails if the rollout pauses, is cancelled or any device fails, so the failed run shows on the commit.

Both jobs fail when suta.lock is missing or out of date, because the deploy would then pin images or versions nobody reviewed. Run suta plan locally and commit suta.lock to fix it. To move to newer images, run suta plan --update and commit the new lock in the pull request.

Caution

GitHub doesn’t give secrets to pull requests from forks, so the plan job can’t plan them. Don’t switch to pull_request_target to work around this: it would let untrusted changes use your token.

Inputs

Input	Default	Description
command	required	plan comments the plan on the pull request. deploy plans and rolls out, then waits.
token	required	The Suta API token.
file	suta.yaml	The suta.yaml to plan. Its suta.lock sits beside it.
tags	all	Only devices with these tags, one per line.
sites	all	Only devices in these sites, one per line.
devices	all	Only these device names or IDs, one per line.
message	none	What the deploy is for. It names the plan and its rollout. Only the first line is used, so a commit message works.
canary	suits the fleet	Devices to update first, from 0 to 20.
batch	suits the fleet	Devices to update at a time after the canary, from 1 to 500.
max-failures	0	Failures to allow before the rollout pauses, from 0 to 100.
github-token	github.token	Posts the plan comment. It needs pull-requests: write.

The action sets the plan-id output to the plan it commented or deployed. Follow a rollout with suta rollout list or in the dashboard under Deployments.

To deploy several projects from one repository, run the action once per suta.yaml with file. Each file gets its own comment.