CI Workflow Authoring

CI Workflow Authoring Skill

Check docs/monorepo-docs/ci.md first.

Required Workflow Conventions

• Include metadata comments (description, test location, type, owner).
• Set default shell to bash.
• Start with permissions: {} and add only required scopes.
• Add timeout-minutes per job.
• Pin all external actions to commit SHAs.
• Ensure each job ends with observe-build-status step.
• Fail fast: validate cheap preconditions (required secrets, Vault reachability, input/tag contracts) in a preflight step or job before expensive build/test steps.

Recommendation: restrict on: push to main/stable branches

Use push only for workflows on main/stable/*, where every commit needs a full build for confidence. Use pull_request everywhere else, so a branch doesn't get two trigger sources to deduplicate.

Recommendation: concurrency groups for PR, push, and scheduled workflows

Add a concurrency: group to cancel superseded runs, reduce race conditions, and avoid wasted runner cost. Copy the pattern from ci.yml rather than inventing a new one:

concurrency:
  cancel-in-progress: true
  group: ${{ format('{0}-{1}-{2}', github.workflow, github.event_name, (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/heads/stable/')) && github.sha || github.ref) }}

github.event_name keeps different trigger sources on the same ref from colliding, especially scheduled cache-refresh runs and push builds on main/stable/*. The github.sha fallback for main/stable/* is intentional: those branches need complete builds for every pushed commit, and a cancelled push run can mean a missed alert or skipped artifact push.

Unified CI Criteria

• Runtime <= 30 minutes
• Stable and observable
• Vault-based secret handling
• Uses approved cache strategy

Caching Strategy

• Maven: .github/actions/setup-maven-cache
• npm is the default for Node.js workflows in this monorepo
• Yarn (legacy workflows only): camunda/infra-global-github-actions/setup-yarn-cache
• Do not cache Docker layers via GHA cache
• Write caches only from main and stable*

Templates

• Workflow template: references/workflow-template.md
• Composite action template: references/composite-action-template.md