Bitbucket

What it does

• Pull in CI: a pull-requests pipeline runs stoaken export --check.
• Push on publish: a Stoaken webhook sent as a Bitbucket Pipelines run calls Bitbucket's run-a-pipeline API. That starts the custom pipeline stoaken-release, which exports the tokens, pushes stoaken/tokens, and can open a pull 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.
• A Bitbucket repository access token with pipeline:write (Repository settings > Access tokens). Access tokens are sent as Authorization: Bearer (docs).
• Pipelines enabled on the repository.

Setup

1. Add the secured repository variable STOAKEN_TOKEN. Optionally add BB_PR_TOKEN, an access token with pullrequest:write, so the pipeline also opens the pull request.
2. Commit bitbucket-pipelines.yml (template: bitbucketPipelines() in src/lib/integrations/pipelines.ts). The custom pipeline must exist on the branch you name in step 3:

image: node:22
pipelines:
  pull-requests:
    '**':
      - step:
          script:
            - npx --yes stoaken@latest export --check
  custom:
    stoaken-release:
      - variables:
          - name: STOAKEN_EVENT
          - name: STOAKEN_RELEASE_ID
          - name: STOAKEN_VERSION
      - step:
          script:
            - npx --yes stoaken@latest export
            # … commit + push stoaken/tokens, optional PR via the API

3. In Stoaken, go to Settings > Webhooks and choose Add a webhook:
   • Send as: Bitbucket Pipelines run
   • Address: https://api.bitbucket.org/2.0/repositories/WORKSPACE/REPO/pipelines/
   • Access token: the pipeline:write token. It's stored encrypted and never shown again.
   • Branch: for example main
   • Events: Release published.

Configuration

• Body sent: {"target": {"type": "pipeline_ref_target", "ref_type": "branch", "ref_name": "<branch>", "selector": {"type": "custom", "pattern": "stoaken-release"}}, "variables": [...]}.
• Variables: STOAKEN_EVENT (release.published, or ping for Send test, which the template skips), STOAKEN_RELEASE_ID and STOAKEN_VERSION.
• The token is only ever sent to https://api.bitbucket.org/2.0/repositories/…/pipelines/, and the database enforces this.

Try it

1. Send test should get 201 from Bitbucket and a short stoaken-release run that stops at the ping check.
2. Send a sample with Release published runs the full update.

Troubleshooting

• 401/403: the token has expired or lacks pipeline:write.
• 404: the workspace or repository slug in the address is wrong.
• 400 "bitbucket-pipelines.yml not found" or no such pipeline: the branch you named has no custom: stoaken-release.
• Push refused: the branch is restricted. Allow the pipeline to push to stoaken/tokens.

Limits

• Bitbucket Cloud only. Data Center has a different API and isn't supported.
• Pipelines minutes count against your Bitbucket plan.