CI/CD integrations

Status. These tools were written by work package WP-55 on the branch wp/WP-55-ci-integrations (integrations/ci/, plus rl doctor in tools/cli). When this page was written that branch was not yet merged into the integration branch, so paths may change. Nothing was run on real GitHub, GitLab, Bitbucket, Netlify or Vercel, and nothing is published (no Marketplace, npm, Netlify or Vercel listing). The platform syntax in these pages was not checked against the vendors' documentation and is marked verify. The domain in examples (api.example.com) is a placeholder.

The tools are zero-dependency Node 18.17+ scripts that reuse the rl command line, the JavaScript SDK and the build-time prerender package. Until those are published, copy them next to integrations/ci; paths are relative.

All flavours go through one entry point, bin/rl-ci.mjs <auto|sync|preview|prerender>; the YAML files are thin wrappers.

Security rules (apply to every page)#

• The secret key (rl_sec_...) is read only from the environment (RL_API_KEY, stored as a CI secret). Never a flag, never a file, never an output. Every log line, annotation, pull-request comment and output is redacted, and the GitHub Action also masks the value. Tests assert that the key never appears.
• Use two keys: a read-only key (sites:read, translations:read, optionally usage:read) for pull-request previews and a write key (strings:write, translations:write, bundles:publish) only for the default branch. Restrict both to one site (rl keys create --site). See API keys.
• Pull requests from forks get no secrets, so the preview then reports an offline count and says so. Use the pull_request trigger and never pull_request_target with a checkout of the pull request's code.
• The prerender step uses only public values (site key, delivery origin, manifest public key); a rl_sec_ value there is refused.

Failure messages#

The exit codes of rl are turned into titled messages that say what to do: 401 and 403 (wrong, revoked or insufficient key, or a suspended account), 402 (a plan or allowance limit, "not a permission problem", never downgraded to a warning) and 503 (service unavailable, and published translations keep being served). on-unavailable: warn can downgrade 503, 429 and network errors for scheduled syncs. The table is in Troubleshooting CI runs; the exit codes are in CLI and SDKs.

Tests#

cd integrations/ci && npm test (37 tests, offline; 6 need the prerender package built and skip with a message otherwise) and cd tools/cli && npm test (45, including 8 for doctor), per the package's progress file. They use the SDK's mock control plane and local loopback origins with freshly signed bundles. Those results are WP-55's, not re-run here.

Unverified (verify before relying on these pages)#

• GitHub: how the composite action behaves when referenced as owner/repo/subdir@sha (the whole repository is checked out into the action path), GITHUB_STEP_SUMMARY, workflow-command escaping and fork-token rules.
• GitLab: changes: on merge request pipelines, the notes API and the collapsible-section syntax.
• Netlify: the plugin manifest input syntax and utils.cache / utils.status.
• Vercel: build-command behaviour.
• Docker node:22 image tags.

Vendor documentation to check: GitHub Actions at docs.github.com, GitLab CI and its API notes at docs.gitlab.com, Netlify build plugins at docs.netlify.com, Vercel project configuration at vercel.com/docs, Bitbucket Pipelines at support.atlassian.com. None was fetched by the author of these tools or by this docs site.