ci-cd-pipeline-authoring

CI/CD Pipeline Authoring

Overview

TaskTrooper does not run your build — it reads your GitHub Actions workflows and maps their jobs and files onto its own pipeline. A task entering code_review waits for your validate/build/test jobs on its pull request (get_pipeline_status shows them); once a component's delivery profile is dispatch, the release engineer dispatches your production deploy workflow at the release tag after the merge. If your workflows are not named the way the detector expects, the pipeline silently skips them and the task stalls at that gate.

Core principle: The workflow you author is the contract with the platform. Name jobs and files with the keywords the detector matches, or the stage does not exist as far as TaskTrooper is concerned.

Two kinds of pipeline slot

Status slots (mapped to a job name in any workflow) — read for pass/fail on the PR at code_review:

Slot	Job name must contain (by repo kind)
validate	lint, vet, staticcheck (backend/worker) · lint, tsc, typecheck (frontend) · lint, swiftlint, analyze (mobile)
build	build, compile, docker (backend/worker/frontend) · build, xcodebuild, archive, fastlane (mobile)
test	test, vitest, jest

A mobile build job must not contain docker (excluded). Give each job a clear name: — the detector matches the job's display name.

Deploy slots (mapped to a workflow file) — dispatched, one workflow file per slot:

Slot	Workflow name: / file must contain
stage_deploy	stage, staging, preview
preprod_deploy	preprod, pre-prod, pre-production
prod_deploy	prod, production, release (must NOT contain preprod)

Rules

• CI lives in one workflow <id>-ci.yml with jobs named validate/lint, build, test. Deploy lives in separate files, one per environment: <id>-deploy-stage.yml, <id>-deploy-preprod.yml, <id>-deploy-prod.yml.
• A dispatch delivery profile's deploy workflow declares on: workflow_dispatch with no required inputs. The platform dispatches with the branch ref only — it passes no inputs, so a workflow that requires one can never be released this way. Bake the environment into the file; read config from repo/environment vars, not inputs.
• An on_merge delivery profile deploys on push to the default branch, on purpose. push: { branches: [main] } on the stage (or the component's only) deploy is correct there — the merge itself deploying is the whole point of that mode, and the release engineer watches, verifies and rolls back rather than dispatching. Preprod/prod still default to dispatch-only (workflow_dispatch) so a human/QA gate controls them, unless the component is explicitly on_merge end to end.
• Authenticate with GitHub OIDC, never long-lived cloud keys. GCP → Workload Identity Federation; AWS → an IAM role via aws-actions/configure-aws-credentials. The job needs permissions: { id-token: write, contents: read }.
• Config in vars, secrets only for true secrets. Project id, region, service name, image repo → repo/environment vars. With OIDC there are usually no cloud secrets at all. Never commit a service-account JSON or access key.
• Deploy job ends with a health-check / smoke step that fails the job on a bad deploy. This is a build-time gate, not the release verdict: the release engineer's post-deploy verification is what actually decides released vs a rollback.
• Pin third-party actions to their current major (or a commit SHA) — check gh api repos/<owner>/<action>/releases/latest rather than trusting a cached version number; actions/checkout@v7 is current as of this writing, not @v5.
• Don't author deploy YAML from scratch: search_boilerplate_catalog for deploy <cloud> <type> (e.g. deploy gcp backend), copy that folder's workflow templates, and rename them to <id>-deploy-<env>.yml.