AGENTS.md — workflows

Overview

GitHub Actions workflows and CI/CD automation

Key Files

Workflow files

• Workflows: 2 workflow file(s)

Directory structure

.github/
  workflows/
    ci.yml              → Main CI workflow (lint, test, build)
    release.yml         → Release/deploy workflow
    dependabot.yml      → Dependency updates
  actions/
    <action-name>/      → Composite actions (reusable)
      action.yml
  CODEOWNERS            → Code ownership rules
  pull_request_template.md

Workflow conventions

• Pin action versions with full SHA, not tags (uses: actions/checkout@abc123...)
• Minimal permissions: Use permissions: block, never use permissions: write-all
• Reusable workflows: Extract common patterns to .github/workflows/reusable-*.yml
• Job dependencies: Use needs: to express dependencies
• Caching: Use actions/cache for dependencies (npm, composer, go)

Naming conventions

Common patterns

Basic CI workflow

name: CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
      - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm test

Matrix builds

jobs:
  test:
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest]
        node: ['18', '20', '22']
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
        with:
          node-version: ${{ matrix.node }}

Reusable workflow

# .github/workflows/reusable-test.yml
on:
  workflow_call:
    inputs:
      node-version:
        type: string
        default: '20'

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}

Conditional deployment

jobs:
  deploy:
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    needs: [test, build]
    environment: production
    steps:
      - name: Deploy
        run: ./deploy.sh

Security & safety

• NEVER expose secrets in logs: use ::add-mask:: for dynamic secrets
• Pin actions to full commit SHA, not mutable tags
• Minimal permissions: Start with contents: read, add only what's needed
• Environment protection: Use environments with required reviewers for deploys
• Secret scanning: Enable in repository settings
• Dependency review: Use actions/dependency-review-action for PRs
• OIDC: Prefer OIDC over long-lived secrets for cloud providers

PR/commit checklist

• Actions pinned to full SHA (not tags)
• Permissions block uses minimal required permissions
• Secrets are not exposed in logs
• Workflow syntax valid: actionlint or GitHub UI validation
• Matrix strategy covers required versions/platforms
• Caching configured for dependencies

Patterns to Follow

Prefer looking at real code in this repo over generic examples. See Golden Samples section above for files that demonstrate correct patterns.

When stuck

• GitHub Actions docs: https://docs.github.com/en/actions
• Workflow syntax: https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions
• Action marketplace: https://github.com/marketplace?type=actions
• Use act for local testing: https://github.com/nektos/act
• Check existing workflows in this repo for patterns