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.

Batch release workflows (a batch delivery profile: desktop, mobile, and anything else a human cuts by hand)

A batch component never dispatches a workflow — cutting the release creates a tag (or, for a local executor, runs a command on the release machine). Author the deploy side of a batch component's pipeline around that:

• github_actions executor — the release/publish workflow triggers on the tag push itself, not on a branch push or workflow_dispatch: on: { push: { tags: ['v*'] } } (match the component's delivery profile tag_pattern, v* for the default v{version}). Read the version being released from GITHUB_REF_NAME (the tag TaskTrooper just pushed) — never from a version file or a bump commit, because cutting a batch release never touches one. The workflow must not create its own tag or version (no semantic-release, changesets, release-please step): TaskTrooper pushes the tag that triggers this workflow, and a tool that tries to push a pre-existing tag of its own fails the release.
• local executor — there is no workflow to author; the command configured on the delivery profile runs directly on this machine in a detached worktree of the cut commit. It receives RELEASE_VERSION, RELEASE_TAG, and RELEASE_COMMIT in its environment — read the version from there, the same way a tag-triggered workflow reads GITHUB_REF_NAME.
• store executor — see the mobile developer's app-store-deploy skill; there is no workflow either, the store build is started directly.

Worked Example

on: block a dispatch deploy workflow needs so the platform can dispatch it:

name: myapi-deploy-prod          # "prod" → prod_deploy slot
on:
  workflow_dispatch: {}          # platform dispatches with ref only, no inputs
permissions:
  id-token: write                # OIDC
  contents: read
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production       # env-scoped vars/secrets + protection rules
    steps:
      - uses: actions/checkout@v7
      # auth via OIDC (WIF / configure-aws-credentials), then deploy the image,
      # then a smoke step that curls the health endpoint and fails on non-200.

Because the file name and name: contain prod, the detector maps this workflow to the component's prod_deploy check — the file name a dispatch delivery profile names as its workflow. The release engineer dispatches it at the release tag (release/<sha12>) after the merge, then verifies the deploy (health, smoke checks, runtime errors) before finishing or rolling back.

Common Mistakes

• A dispatch-profile deploy workflow with on: push only and no workflow_dispatch → it can never be dispatched; either switch the component to on_merge, or add workflow_dispatch.
• A workflow_dispatch with a required: true input → dispatch fails (platform sends no inputs).
• One deploy.yml for all envs → the detector can only map one workflow per slot; you lose stage/preprod separation. Split per env.
• A prod workflow named deploy-preprod-and-prod → preprod substring rules it out of the prod slot.
• A batch release workflow that bumps its own version or pushes its own tag → collides with the tag TaskTrooper already pushed.
• Committing cloud keys instead of using OIDC.

Red Flags

• Job names like job1/step that contain none of the detector keywords → the slot stays empty and the pipeline gate never sees it.
• Deploy that reports success even when the health check failed.
• Secrets that could be vars sitting in secrets:.