CI/CD Standards

GitHub Actions / Workflows

• Shell script code should NOT be inline in Actions/Workflow YAML files
• Extract scripts to dedicated

  .sh

  or

  .py

  files in a

  scripts/

  directory
• Reference these scripts from the workflow
• ALWAYS pin actions to full commit SHAs, NOT version tags

Action Pinning

# WRONG - version tag (can be moved, vulnerable to supply chain attacks)
- uses: actions/checkout@v4
- uses: actions/setup-python@v5

# CORRECT - pinned to SHA (immutable, secure)
- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
- uses: actions/setup-python@0a5c61591373683505ea898e09a3ea4f39ef2b9c # v5.0.0

Finding SHAs

1. Go to the action's releases page
2. Click on the version tag
3. Copy the full commit SHA
4. Add version as comment for readability

Why

• Easier to test scripts locally
• Better syntax highlighting and linting
• Reusable across workflows
• Cleaner workflow files
• Proper version control diffs

Examples

# WRONG - inline script in workflow
jobs:
  build:
    steps:
      - name: Build and deploy
        run: |
          echo "Building..."
          npm install
          npm run build
          if [ -f dist/index.js ]; then
            aws s3 sync dist/ s3://bucket/
          fi

# CORRECT - reference external script
jobs:
  build:
    steps:
      - name: Build and deploy
        run: ./scripts/ci/build-and-deploy.sh

Script Organization

scripts/
└── ci/
    ├── build.sh
    ├── deploy.sh
    ├── test.sh
    └── utils/
        └── helpers.py

Script Requirements

• Scripts must be executable (

  chmod +x

  )
• Include shebang line (

  #!/usr/bin/env bash

  or

  #!/usr/bin/env python3

  )
• Follow shell script best practices (set -euo pipefail for bash)

No Hand-Maintained Mirrors of Canonical Sources

• Replace

  verify-X-sync.py

  scripts with

  generate-X.py

  ; CI runs the generator with

  --check

  (exit 1 + unified diff on drift) instead of parsing both files and comparing.
• The same generator runs locally for the writer flow and in CI for the gate flow — a single code path, no parser duplication.
• Generators consumed by automation (e.g. Renovate

  postUpgradeTasks

  ) should be stdlib-only so they run in any minimal container without dep installation.
• Treat automation hooks as convenience, not correctness. The

  --check

  gate is the truth-keeper; if the hook silently fails, CI still catches the drift.

# WRONG — verify two files agree
- run: python3 scripts/ci/verify-manifest-sync.py
- run: python3 scripts/ci/verify-tool-version-sync.py

# CORRECT — single generator, single check
- run: python3 scripts/ci/generate-tool-versions.py --check