github-actions

GitHub Actions CI/CD AI Skill Guide (Claude)

Overview & Engine Architecture

GitHub Actions runs workflows (YAML under .github/workflows/) on events (push, pull_request, workflow_dispatch, …). Jobs execute on runners; steps use run: or actions from the marketplace. Security is the product: explicit permissions, OIDC federation instead of long-lived cloud keys, pinned action SHAs for high assurance, and fork PR rules that block secrets and OIDC by design.

┌─────────────────────────────────────────────────────────────┐
│                 GitHub Actions trust model                  │
│                                                             │
│  Event → workflow → job(s) → steps                          │
│  ├── GITHUB_TOKEN (scoped by permissions: block)            │
│  ├── Repository / environment secrets                       │
│  └── OIDC JWT (id-token: write) → cloud IAM role            │
│                                                             │
│  Reusable workflow: caller permissions CAP callee           │
│  Fork pull_request: read-only token; NO OIDC injection      │
└─────────────────────────────────────────────────────────────┘

---

When to use / when not to

Use when

• Adding CI (lint/test/build) on PRs and release/deploy on protected branches.
• Wiring AWS/GCP/Azure login via OIDC; caching dependencies; matrix builds.
• Debugging failed checks, cache misses, permission errors, or reusable workflow auth.

Do not use when

• pull_request_target is suggested to “fix” fork OIDC while checking out untrusted PR code—refuse; use maintainer-triggered workflows or skip cloud steps on forks.
• Long-lived cloud access keys in repo secrets when OIDC is available.
• Running unreviewed third-party actions with write permissions.

---

Operational Capabilities & Agent Directives

1. Set permissions: explicitly at workflow or job level; listing scopes replaces repo defaults—include everything needed (contents: read, pull-requests: write, etc.).
2. OIDC jobs require id-token: write on the caller when using reusable workflows; callee cannot exceed caller caps.
3. Fork PRs: assume no secrets, no OIDC; gate cloud deploy steps with if: github.event.pull_request.head.repo.full_name == github.repository or manual workflow_dispatch.
4. Pin actions to full commit SHA for deploy workflows; at minimum pin major tags you trust for inner loops.
5. Never echo secrets; use mask patterns; rotate if leaked in logs.
6. Cache keys must hash lockfiles (package-lock.json, poetry.lock, go.sum).
7. Separate PR CI from production deploy workflows; use environments with required reviewers for prod.
8. Supply chain: audit what marketplace actions execute; prefer composite actions you own.