CLI in CI/CD

FlatRun deploys from CI by running the CLI on your runner. On GitHub Actions, the official setup-flatrun action installs a pinned CLI release and puts it on PATH; from there every FlatRun command is one run: step away.

Credentials

Pass the server URL and an API token as environment variables, sourced from repository or environment secrets. Never commit a token.

env:
  FLATRUN_URL: ${{ vars.FLATRUN_URL }}
  FLATRUN_TOKEN: ${{ secrets.FLATRUN_TOKEN }}

Deploy on Push

A minimal workflow that rolls out a new image on every push to main:

name: Deploy to FlatRun

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: flatrun/actions/setup-flatrun@v1
        with:
          version: 0.1.0

      - name: Roll out the new image
        run: flatrun deployment deploy api --pull
        env:
          FLATRUN_URL: ${{ vars.FLATRUN_URL }}
          FLATRUN_TOKEN: ${{ secrets.FLATRUN_TOKEN }}

      - name: Verify health
        run: flatrun health
        env:
          FLATRUN_URL: ${{ vars.FLATRUN_URL }}
          FLATRUN_TOKEN: ${{ secrets.FLATRUN_TOKEN }}

Pin a Service to a Built Image

When CI builds and pushes an immutable image (a commit SHA tag), point a compose service at it, then pull and run an operation in one command:

flatrun deployment image set api app ghcr.io/acme/api:sha-${{ github.sha }} \
  --deploy --operation rebuild --json

Use --operation restart when a plain restart suffices, or rebuild when containers must be recreated from the updated compose. --json gives machine-readable output for later steps.

The setup-flatrun Action

It outputs the installed version and the absolute path to the binary.

Pinning

Reference the action by Git ref, strictest first:

• Commit SHA — setup-flatrun@<sha> (immutable, auditable)
• Release tag — [email protected]
• Major tag — setup-flatrun@v1 (tracks the latest 1.x)

Use SHA pinning in security-sensitive workflows.

Other Runners

The action is a thin installer, so the CLI works anywhere. On non-GitHub or self-hosted runners, install the binary (or build it) and set FLATRUN_URL and FLATRUN_TOKEN; the same commands apply.