| 1 | --- |
| 2 | name: ci-maintenance |
| 3 | description: GitHub Actions maintenance. Use when authoring or reviewing workflows or composite actions, especially event, permission, action-reference, artifact, setup, or concurrency changes. |
| 4 | --- |
| 5 | |
| 6 | Audit the trust boundary before editing. This skill owns Actions event |
| 7 | semantics, workflow security, permissions, action pinning, setup reuse, |
| 8 | untrusted inputs, timeouts, concurrency, and artifact trust boundaries. |
| 9 | |
| 10 | ## Workflow |
| 11 | |
| 12 | 1. Decide whether this is a review or an implementation. Reviews produce |
| 13 | evidence-backed findings without editing; implementations continue through |
| 14 | the smallest boundary-preserving change. |
| 15 | 2. Inspect every affected workflow, composite action, and caller. List all |
| 16 | affected jobs and actions before proceeding. |
| 17 | 3. For each job, record the trigger, actor/fork status, workflow revision, |
| 18 | checked-out revision, permissions, credentials, and every external input and |
| 19 | consumer. Include artifacts, caches, outputs, PR fields, refs, dispatch |
| 20 | inputs, generated files, and called actions. |
| 21 | 4. Consult current GitHub documentation for every platform-sensitive decision. |
| 22 | Repository examples establish local convention, not platform semantics. |
| 23 | 5. Apply every applicable rule: |
| 24 | - Default workflow permissions to empty and grant minimal job permissions. |
| 25 | - Reuse the repository's shared setup action unless the environment must differ. |
| 26 | - Give executable jobs intentional matrices and realistic timeouts. |
| 27 | - Pin external actions and reusable workflows to full commit SHAs with |
| 28 | readable release comments; verify each SHA belongs to that upstream release. |
| 29 | - Analyze event choice, checkout revision, and credential persistence |
| 30 | together. |
| 31 | - Pass untrusted expressions through environment variables; validate and |
| 32 | quote them before use. |
| 33 | - Derive concurrency from interruption safety. |
| 34 | 6. For forks, privileged credentials, publication, or cross-run data, read |
| 35 | [privileged-workflows.md](privileged-workflows.md). |
| 36 | 7. Run the narrowest syntax and repository checks, inspect the complete diff, |
| 37 | and identify behavior testable only on GitHub-hosted runners. |
| 38 | |
| 39 | For local patterns, inspect the current shared setup action and the nearest |
| 40 | workflow with the same trust boundary. Use ordinary check workflows for routine |
| 41 | precedent and privileged publication workflows only for equivalent trust |
| 42 | boundaries. |
| 43 | |
| 44 | The task is complete when every affected job and caller has a recorded trust |
| 45 | boundary, every applicable rule has evidence or a compensating control, local |
| 46 | checks pass, and GitHub-only verification is identified. Reviews report every |
| 47 | failure with evidence; implementations resolve every failure and contain only |
| 48 | intended behavior. |