Use Superflag in CI/CD

Store a user-scoped cli_ token or app-scoped admin_ key in your CI secret manager. Inject it as SUPERFLAG_TOKEN; do not generate a credentials JSON file or print the value.

Validate every proposed config

name: Validate Superflag configuration

on:
  pull_request:

jobs:
  superflag:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: https://registry.npmjs.org
      - run: npm install --global @superflag-sh/cli@0.7.0
      - run: superflag --version
      - run: superflag contract --json
      - run: superflag skill check
      - run: superflag validate --file config/prod.superflag.json --json

Pin the CLI version so the workflow’s machine contract changes only in an intentional dependency update. Commit .agents/skills/superflag/ and its .superflag-skill.json provenance manifest. When the CLI pin changes, run superflag skill update, review the instruction diff, and commit the package and skill changes together.

Dry-run before an environment mutation

- name: Diagnose Superflag access
  env:
    SUPERFLAG_TOKEN: ${{ secrets.SUPERFLAG_TOKEN }}
  run: superflag doctor --json

- name: Create plan
  env:
    SUPERFLAG_TOKEN: ${{ secrets.SUPERFLAG_TOKEN }}
  run: >-
    superflag plan
    --file config/staging.superflag.json
    --app my-app
    --env staging
    --out superflag-plan.json

- name: Verify plan without mutation
  env:
    SUPERFLAG_TOKEN: ${{ secrets.SUPERFLAG_TOKEN }}
  run: superflag apply --plan superflag-plan.json --dry-run --json

Apply the same plan only from a protected job or environment approval. Keep the plan artifact so an ambiguous response can use the corresponding recovery workflow.

Promote explicitly

superflag promote \
  --app my-app \
  --from staging \
  --to prod \
  --dry-run \
  --json

Do not treat a successful config validation as production proof. A deployment workflow should record the CLI version, target app/environment, plan identity, expected config version, apply response, and post-apply read or journal entry.

Process status matters

JSON is not a replacement for exit status. A completed doctor --json can return a full diagnostic envelope and exit 1 when unhealthy. Conflicts and stale preconditions exit 6 and should trigger re-export/re-plan, not blind retry.