GitHub Action

The SutramX GitHub Action runs the SutramX CLI against the sutramx.yml in your repository. Use it to post the plan on every pull request that changes your monitors, and to apply the file when the change is merged.

The action lives in the SutramX/cli repository and is used as sutramx/cli/action@v1.

What the action does#

The action is a composite action. Each run:

1. Sets up Node.js 22.
2. Runs the published @sutramx/cli package with npx (the version you choose with cli-version).
3. Runs plan, diff or apply against your file. Plan and diff run with --detailed-exitcode; apply runs with --auto-approve.
4. Writes the output (including any error messages) to the job summary and to the plan output, and sets has-changes.

Colour is turned off so the output reads cleanly in logs and comments. Your API key is passed to the CLI through the environment, never written into the script, and is masked in the logs.

Inputs#

Outputs#

For plan and diff, "there are changes" is not a failure: the step succeeds and has-changes is true. The step fails when the CLI reports an error, for example an invalid file, a missing environment variable, an API error or a failed change during apply.

Set up the API key#

Every API key has one of three access levels, fixed when the key is created. Choose the level for what the job does:

1. In SutramX, open Account settings → API keys → Create API key.
2. Choose the Access level from the table above. The dashboard selects Read-only by default, which can plan but not apply.
3. Copy the key; it is shown only once.
4. In GitHub, add it as a secret named SUTRAMX_API_KEY (Settings → Secrets and variables → Actions).

You can use one Standard or Automation key for every job, or give the plan job its own read-only key (in a separate secret) so pull request runs never hold a key that can make changes. Whether you can create API keys, and how many, depends on your plan: see Plans & limits.

Plan on pull requests, apply on merge#

Save this as .github/workflows/sutramx.yml. Pull requests that touch sutramx.yml get the plan as a comment (updated in place on each push), and merging to main applies it.

name: SutramX monitors

on:
  pull_request:
    paths: [sutramx.yml]
  push:
    branches: [main]
    paths: [sutramx.yml]

permissions:
  contents: read
  pull-requests: write

concurrency:
  group: sutramx-${{ github.ref }}
  cancel-in-progress: false

jobs:
  plan:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - id: plan
        uses: sutramx/cli/action@v1
        with:
          command: diff
          api-key: ${{ secrets.SUTRAMX_API_KEY }}
      - name: Comment the plan on the pull request
        uses: actions/github-script@v7
        env:
          PLAN: ${{ steps.plan.outputs.plan }}
          HAS_CHANGES: ${{ steps.plan.outputs.has-changes }}
        with:
          script: |
            const marker = '<!-- sutramx-plan -->';
            const body = `${marker}\n### SutramX plan${process.env.HAS_CHANGES === 'true' ? '' : ' (no changes)'}\n\`\`\`\n${process.env.PLAN}\n\`\`\``;
            const { data: comments } = await github.rest.issues.listComments({ ...context.repo, issue_number: context.issue.number });
            const existing = comments.find((comment) => comment.body?.startsWith(marker));
            if (existing) await github.rest.issues.updateComment({ ...context.repo, comment_id: existing.id, body });
            else await github.rest.issues.createComment({ ...context.repo, issue_number: context.issue.number, body });

  apply:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4
      - uses: sutramx/cli/action@v1
        with:
          command: apply
          api-key: ${{ secrets.SUTRAMX_API_KEY }}

A few details worth knowing:

• command: diff puts every changed field (old -> new) in the comment. Use plan for a shorter list of field names.
• concurrency with cancel-in-progress: false stops two applies from running at once.
• environment: production lets you add required reviewers or restrict the secret to the main branch with GitHub environment protection rules. Remove it if you don't use environments.
• Pull requests from forks don't get repository secrets, so the plan job can't run for them.

Pass secrets used in the file#

If sutramx.yml reads environment variables, for example ${SLACK_WEBHOOK_URL} for an integration, set them on the step. The CLI fails with a clear message if one is missing.

      - uses: sutramx/cli/action@v1
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
        with:
          command: apply
          api-key: ${{ secrets.SUTRAMX_API_KEY }}

Prune on apply#

To delete keyed monitors that were removed from the file, pass prune: 'true' to the action. Setting settings.prune: true in sutramx.yml isn't enough; it only prints a warning:

      - uses: sutramx/cli/action@v1
        with:
          command: apply
          prune: 'true'
          api-key: ${{ secrets.SUTRAMX_API_KEY }}

Pruning deletes the monitors' check history. As a safety catch, an apply that would prune every managed monitor because the file declares none is refused. Read Pruning before turning it on, especially if other tools create keyed monitors in the same workspace.

Fail a check when there are changes#

To make a scheduled job flag drift (someone changed a managed monitor in the dashboard), use the has-changes output:

on:
  schedule:
    - cron: '0 6 * * *'

jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - id: plan
        uses: sutramx/cli/action@v1
        with:
          command: plan
          api-key: ${{ secrets.SUTRAMX_API_KEY }}
      - if: steps.plan.outputs.has-changes == 'true'
        run: |
          echo "SutramX differs from sutramx.yml" >&2
          exit 1

Recording deploys#

The action only plans and applies sutramx.yml; it doesn't record deployments. To see deploys next to incidents and response times, see Deployment correlation.

Troubleshooting#