Deploy from GitHub Actions

You don't have to deploy from your laptop. A short workflow builds and ships your app on every push to main — the same allocus deploy you'd run by hand, on a CI runner.

The workflow

Add .github/workflows/allocus-deploy.yml:

name: Deploy to Allocus
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3
      - name: Install the allocus CLI
        # Pin a released tag — never deploy off a moving branch.
        run: pipx install git+https://github.com/allocusdev/cli@v0.4.0
      - name: Deploy
        run: |
          allocus login --key "${{ secrets.ALLOCUS_API_KEY }}" --url https://allocus.dev
          allocus deploy --wait

--wait matters more in CI than locally

Without it, allocus deploy returns as soon as the deploy is queued, so a green build tells you the image was pushed and nothing more — an app that won't start looks like a successful workflow run. --wait blocks until your box reports the app healthy and names the service that failed otherwise, which is what makes the job's status mean something.

The runner checks out your repo, builds the image (for linux/amd64), pushes it to your registry namespace, and tells your box to roll it out — no different from a local deploy. Stacks work too: if your allocus.yaml declares services:, every service is built and shipped.

Add your API key as a secret

The workflow authenticates with your Allocus API key, stored as a GitHub repository secret:

1. Copy your API key from your dashboard.
2. In your repo: Settings → Secrets and variables → Actions → New repository secret.
3. Name it ALLOCUS_API_KEY, paste the key, save.

That's the only setup — the CLI fetches its own registry credentials, so there's nothing else to configure.

Deploy only on certain paths

Scope the trigger if a push shouldn't always redeploy:

on:
  push:
    branches: [main]
    paths: ["src/**", "Dockerfile", "allocus.yaml"]

A note on the API key

The key acts as you, so treat it like a password — keep it in the repo secret, never in the workflow file or your code. Note that it isn't scoped to one app: anyone holding it can deploy to your box, so a workflow in a repo other people can push to is a workflow that can deploy anything to your box. If it leaks, revoke it from the dashboard and generate a new one.

A keyless option (GitHub OIDC, no stored secret) is on our roadmap; until it lands, the repository secret is the supported way to deploy from CI.

When a CI deploy fails

The failure message comes from your box, not from the runner, so it's about your app. The troubleshooting page decodes the common ones. Note that allocus logs works from anywhere you're logged in, including your laptop, so you don't need to debug through the CI log.