Deploy from CI

In CI, set FALAK_URL and FALAK_TOKEN and call falak deploy --wait. The job streams the deployment output and fails when the deployment fails (exit code 3).

Create a CI token

Create a token under Settings → API tokens with only what CI needs:

Ability	Why
deployments.create	Trigger deployments
deployments.view	Poll status and output
sites.view	Resolve the site

Store it as a secret in your CI (FALAK_TOKEN). Set an expiry if your policy requires rotation.

Examples

GitHub Actions

.github/workflows/deploy.yml

name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    needs: []            # e.g. [test]
    steps:
      - name: Install falak
        run: |
          curl -fsSL -o /usr/local/bin/falak \
            https://github.com/OthmanHaba/falak/releases/latest/download/falak-linux-amd64
          chmod +x /usr/local/bin/falak
      - name: Deploy
        env:
          FALAK_URL: https://falak.example.com
          FALAK_TOKEN: ${{ secrets.FALAK_TOKEN }}
        run: falak deploy shop --branch "${GITHUB_REF_NAME}" --wait

GitLab CI

.gitlab-ci.yml

deploy:
  stage: deploy
  image: alpine:3.20
  only: [main]
  variables:
    FALAK_URL: https://falak.example.com
  script:
    - apk add --no-cache curl
    - curl -fsSL -o /usr/local/bin/falak https://github.com/OthmanHaba/falak/releases/latest/download/falak-linux-amd64
    - chmod +x /usr/local/bin/falak
    - falak deploy shop --branch "$CI_COMMIT_REF_NAME" --wait

Store FALAK_TOKEN as a masked CI/CD variable.

Any shell

export FALAK_URL=https://falak.example.com FALAK_TOKEN=…
falak deploy shop --wait || { echo "deploy failed"; exit 1; }

Note

falak deploy deploys the head of the branch, resolved by the git provider. To deploy the exact commit CI tested, use a deploy hook with falak_deploy_commit=$GITHUB_SHA, or POST /api/v1/sites/{site}/deployments with {"commit": "<sha>"}.

Machine-readable output

falak --json deploy shop --wait > deployment.json   # output lines on stderr
jq -r '.status' deployment.json                      # succeeded

Push-to-deploy or CI?

Turn push-to-deploy off for sites you deploy from CI, or every push triggers two deployments. Pick one trigger per site.

Next steps

Deployments APIDeploy an exact commit and poll.

Deploy hooksFire-and-forget deploys.