# Deploy from CI

> Deploy to Falak from GitHub Actions, GitLab CI or any pipeline with the falak CLI and a scoped token, and fail the job when the deployment fails.

Source: https://falak.sh/docs/cli/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

  
    ```yaml title=".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
    ```
  
  
    ```yaml title=".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.
  
  
    ```bash
    export FALAK_URL=https://falak.example.com FALAK_TOKEN=…
    falak deploy shop --wait || { echo "deploy failed"; exit 1; }
    ```
  

`falak deploy` deploys the **head** of the branch, resolved by the git provider. To deploy the exact commit CI tested, use a [deploy hook](/docs/guides/push-to-deploy/#deploy-hooks) with `falak_deploy_commit=$GITHUB_SHA`, or `POST /api/v1/sites/{site}/deployments` with `{"commit": "<sha>"}`.

## Machine-readable output

```bash
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