GitLab | Stoaken Integrations

What it does

Pull in CI: a .gitlab-ci.yml job runs stoaken export --check on merge requests.
Push on publish: a standard Stoaken webhook calls GitLab's pipeline trigger URL. GitLab accepts any JSON body there (docs). The stoaken-update job exports the tokens and pushes stoaken/tokens with push options that open a merge request.

Before you start

A Stoaken API key and a stoaken.config.json with exports (see /docs/cli).
Brand Admin in Stoaken, on the Team plan.
In GitLab: a pipeline trigger token (Settings > CI/CD > Pipeline trigger tokens) and a project access token with write_repository, so the job can push.

Setup

Under Settings > CI/CD > Variables, add STOAKEN_TOKEN (masked) and GITLAB_PUSH_TOKEN (masked).
Add the jobs to .gitlab-ci.yml (template: gitlabCi() in src/lib/integrations/pipelines.ts):

stoaken-check:
  image: node:22
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  script:
    - npx --yes stoaken@latest export --check

stoaken-update:
  image: node:22
  rules:
    - if: $CI_PIPELINE_SOURCE == "trigger"
    - if: $CI_PIPELINE_SOURCE == "web"
  script:
    - |
      npx --yes stoaken@latest export
      # … commit to stoaken/tokens, then:
      git push --force "https://oauth2:${GITLAB_PUSH_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git" HEAD:stoaken/tokens -o merge_request.create -o merge_request.target=main

In Stoaken, go to Settings > Webhooks, choose Add a webhook, set Send as to Stoaken event and paste this as the address: https://gitlab.com/api/v4/projects/PROJECT_ID/ref/main/trigger/pipeline?token=TRIGGER_TOKEN Pick Release published.

Configuration

The ref in the path picks the branch whose .gitlab-ci.yml runs. URL-encode it if it contains /.
Stoaken's event body arrives as the file variable TRIGGER_PAYLOAD. The template reads data.version from it for the commit message.
Pipelines started this way have CI_PIPELINE_SOURCE == "trigger".
Self-managed GitLab works too, as long as it's reachable on the public internet over https. Stoaken never calls private addresses.

Try it

Send test on the webhook should get 201 from GitLab and start a pipeline. It also exports, so you may get a merge request.
Run the pipeline by hand (Build > Pipelines > Run pipeline) to check the push token.

Troubleshooting

404 from GitLab: the project ID or ref is wrong, or the trigger token was revoked.
No jobs in the pipeline: the rules didn't match. Check stoaken-update lists trigger.
Push refused: GITLAB_PUSH_TOKEN lacks write_repository, or the branch is protected.
The trigger token sits in the webhook address, and Brand Admins can see that address. Rotate it in GitLab if it leaks.

Limits

Stoaken's signature isn't checked by GitLab: the trigger token is what authorises the call.
Merge request push options need GitLab 11.10 or later.