config-public/docs/triggering-deploys.md

Triggering a deploy from another repository

The case: an application repository builds a new image, pushes it, and then asks this repository to redeploy the stack that runs it.

application repo                      config repo
──────────────────────                ──────────────────────────
build → push :latest ─── trigger ───► deploy
                         stack=webapp   └─ ansible-playbook
                         pull=always       playbooks/webapp.yml
                                           -e pull=always

pull=always is not optional here. The image tag has not changed — only its contents have — and Compose is perfectly happy with the image it already has. A trigger that forgets it produces a deploy that does nothing and reports success.

GitHub Actions

deploy.yml accepts a repository_dispatch event of type deploy.

Caller

      - name: Redeploy the stack
        env:
          GH_TOKEN: ${{ secrets.CONFIG_REPO_TOKEN }}
        run: |
          gh api repos/OWNER/config/dispatches \
            --field event_type=deploy \
            --field 'client_payload[stack]=webapp' \
            --field 'client_payload[pull]=always'

CONFIG_REPO_TOKEN is a fine-grained personal access token, or a GitHub App installation token, with Contents: read and write on the config repository. The default GITHUB_TOKEN cannot dispatch to another repository.

What happens downstream

deploy.yml validates the payload before doing anything:

1. rejects stack unless it matches [a-z0-9_-]+, and pull unless it is one of policy, always, missing, never,
2. fails if ansible/playbooks/<stack>.yml does not exist,
3. materialises the SSH key with scripts/load-ssh-key.sh,
4. runs the playbook.

The values arrive from another repository and end up on a command line, so they are treated as hostile. See "Why untrusted input is validated" in ci-github-actions.md.

The caller cannot wait

A repository_dispatch returns as soon as GitHub accepts the event. The response contains no run id, so the caller cannot poll for a result either. If the build pipeline must go red when the deploy fails, you have two options:

• Put the deploy in the same repository as the build and use workflow_call, which does propagate failure.
• Poll. After dispatching, list workflow runs for deploy.yml created after your dispatch timestamp and wait on the newest. This is fiddly and racy; only do it if you genuinely need the coupling.

Most of the time you do not. A deploy that fails is visible in the config repository's Actions tab and can notify on failure there.

GitLab CI

deploy:triggered exists only in pipelines that were triggered from outside, so it can never fire on a push here.

Multi-project trigger (preferred)

In the upstream project:

deploy-config:
  stage: deploy
  trigger:
    project: your-group/config
    branch: main            # must be a protected branch — see below
    strategy: depend        # upstream waits and mirrors the result
  variables:
    STACK: webapp
    PULL: always

strategy: depend is what makes the build pipeline report the deployment's result. Drop it and the trigger job goes green the moment the request is accepted, whether or not the deploy worked.

This authenticates with CI_JOB_TOKEN, so the config project must allowlist the upstream project under Settings → CI/CD → Job token permissions. Recent GitLab versions deny cross-project job-token access by default, and the failure is a 404 rather than a permissions error — which is the most common cause of "the trigger does nothing".

Trigger token

For callers that are not GitLab CI — a webhook, a cron box, a person with curl. Create the token under Settings → CI/CD → Pipeline trigger tokens.

curl --request POST \
  --form token="$DEPLOY_TRIGGER_TOKEN" \
  --form ref=main \
  --form "variables[STACK]=webapp" \
  --form "variables[PULL]=always" \
  "https://gitlab.example.com/api/v4/projects/your-group%2Fconfig/trigger/pipeline"

The project path must be URL-encoded (%2F for the slash), or use the numeric project ID. The response is the created pipeline as JSON; .web_url takes you straight to it.

One-time setup

1. Allowlist the caller under Job token permissions, or the trigger 404s.
2. Protect the target branch, and mark the deploy variables Protected. Protected variables only exist on protected refs; trigger a feature branch and the key comes back empty.
3. Give the upstream project Developer access, or the job token is refused regardless of the allowlist.

Gitea Actions

Gitea has no repository_dispatch. The way in is the workflow dispatch API, which fills in the same form a person would use under Actions → deploy → Run workflow. It needs Gitea 1.24 or newer.

Caller

curl -X POST \
  -H "Authorization: token $CONFIG_REPO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "ref": "main",
        "inputs": {"stack": "webapp", "mode": "deploy", "pull": "always"}
      }' \
  https://gitea.example.com/api/v1/repos/OWNER/config/actions/workflows/deploy.yml/dispatches

Three things are easy to get wrong here:

• ref is required, and it is the ref the playbooks are read from as well as the one the run is attributed to. Point it at your default branch.
• mode falls back to check. Omit it and the trigger runs --check --diff, reports what it would have done, and goes green having deployed nothing. This is the Gitea equivalent of forgetting pull=always, and it fails just as quietly. (The workflow applies that fallback itself: an input's declared default: belongs to the dispatch form, not to the API.)
• The job's own GITEA_TOKEN cannot do this. It is scoped to the repository the job runs in. CONFIG_REPO_TOKEN is an access token belonging to a user with write access to the config repository — Settings → Applications → Access tokens, with the write:repository scope — stored as a secret in the calling repository.

The workflow name in the path is the file name, deploy.yml.

The caller can wait, if it wants to

Add ?return_run_details=true and the response carries the run's id and URL, so a caller can poll /api/v1/repos/OWNER/config/actions/runs/<id> until it finishes and fail its own pipeline on the result. That is more than GitHub's repository_dispatch offers, and more than most callers need: a deploy that fails is visible in the config repository's Actions tab and can notify from there.

What happens downstream

Exactly what happens on GitHub — the same validation is in .gitea/workflows/deploy.yml, and it matters more here. A type: choice input constrains the form and not the API, so a dispatch call may put any string in stack.

Before you enable this

A trigger is a deploy. Anyone holding the token, and any repository on the allowlist, can deploy any stack in this repository. The validation guard stops them running arbitrary commands; it does not stop them deploying a stack they had no business touching. Scope the allowlist deliberately, and rotate the token when someone leaves.

Confirm the playbook exists first. The downstream job fails the pipeline by design when it does not, which is correct but makes for a confusing first experience if you enable the trigger before converting the stack.

Checking it worked

The Ansible recap at the end of the job log is the real answer. changed=0 means the images had not moved — which, for a trigger that fired after a successful build, almost always means pull=always was not passed.