github-actions

## Setup On first activation, read `setup.md` to align auto-activation rules, repo shape, and mutation boundaries before editing workflows or triggering runs. ## When to Use User needs GitHub Actions workflow design, debugging, hardening, release orchestration, runner strategy, matrix tuning, cache fixes, or reusable workflow architecture. Use this skill when the result depends on GitHub Actions semantics and GitHub delivery controls, not generic CI advice. ## Architecture Optional repository-specific notes live in `.agents/skill-state/github-actions/`. Do not create them unless they will preserve useful, stable project context. See `memory-template.md` for the baseline structure. ```text .agents/skill-state/github-actions/ |-- memory.md # Persistent repo context and activation boundaries |-- repo-map.md # Repos, branches, package managers, and deploy targets |-- workflow-defaults.md # Stable defaults for triggers, permissions, caches, and runners |-- incidents.md # Failure signatures, root causes, and fixes `-- release-rules.md # Promotion gates, approvals, and rollback notes ``` ## Quick Reference Load only the file needed for the current workflow problem. | Topic | File | |-------|------| | Setup and activation behavior | `setup.md` | | Memory schema and status model | `memory-template.md` | | Authoring patterns and reusable workflow shapes | `workflow-patterns.md` | | Permissions, secrets, OIDC, and fork safety | `security-model.md` | | Run failure triage and log-first debugging | `debugging-playbook.md` | | Tag, release, and deployment orchestration | `release-patterns.md` | | Caching, matrices, path filters, and runner efficiency | `performance-tuning.md` | ## Requirements - Optional but high leverage tools: `gh`, `jq`, `act` - GitHub repository access if the user wants live run inspection or workflow changes - Deployment credentials only through GitHub-managed secrets, environments, or OIDC Never ask the user to paste personal access tokens, cloud keys, or private signing material into chat. ## CI/CD Examples YAML snippets in this skill are examples for repository workflow files. References like `${{ github.* }}`, `${{ inputs.* }}`, `${{ vars.* }}`, and `${{ secrets.* }}` belong to GitHub Actions runtime, not to the agent runtime. The agent should design around those placeholders but should not expect to read their values directly. ## Operating Coverage This skill covers GitHub Actions as an operating system for delivery: - workflow authoring across `push`, `pull_request`, `workflow_dispatch`, `schedule`, and `workflow_call` - job design across permissions, concurrency, matrices, artifacts, caches, services, and environments - release and deployment pipelines with protected branches, approvals, tags, and rollback checkpoints - incident response for flaky runs, missing artifacts, cache corruption, and environment drift ## Data Storage Repository-local notes in `.agents/skill-state/github-actions/` may include: - repo topology, protected branches, and environment names - known-good workflow defaults and reusable workflow contracts - recurring incident signatures with fixes and prevention notes - release gates, promotion steps, and rollback constraints ## Core Rules ### 1. Start from Trigger, Target, and Artifact Contract Before editing YAML, define: - the event that should start the workflow - the branch, tag, or environment it may affect - the artifact or status each job must produce Without that contract, workflows turn into step collections with unclear release behavior. ### 2. Default to Explicit Permissions and Narrow Blast Radius Declare `permissions:` at workflow or job level and grant only what that job needs. Treat `contents: write`, `packages: write`, and `id-token: write` as exceptions that need a clear reason. ### 3. Separate Validation, Build, Release, and Deploy Concerns Keep pull request validation, artifact creation, release publishing, and production deployment as distinct responsibilities. Use `workflow_call` or small reusable jobs instead of one oversized workflow that does everything. ### 4. Bound Every Run with Concurrency, Timeouts, and Filters Use `concurrency` for branch or environment scoped cancellation, add `timeout-minutes`, and filter noisy events with branch or path rules. Minutes disappear quickly when redundant runs are left unbounded. ### 5. Optimize Deterministic Work, Not Random Side Effects Cache package manager state, toolchains, and stable build outputs keyed by lockfiles or explicit versions. Use artifacts for job handoffs. Do not cache paths that depend on secrets, timestamps, or mutable deploy state. ### 6. Debug from Logs and Reproduction Evidence Classify failures before rewriting workflows: - trigger and condition mismatch - missing dependency or toolchain drift - credential or permission denial - artifact or path contract break - flaky external dependency Fix the failure mode that exists, not the one that feels familiar. ### 7. Prefer Short-Lived Credentials and Protected Deploy Surfaces Use GitHub environments, reviewer gates, and OIDC federation where possible. Avoid long-lived cloud secrets, unreviewed `workflow_dispatch` deploys, and production writes from untrusted events. ## GitHub Actions Traps - Mixing pull request validation and production deployment in one unguarded workflow -> accidental releases from the wrong event. - Granting broad permissions to every job -> larger blast radius when one action or step is compromised. - Using caches without lockfile or version keys -> stale dependencies and confusing non-reproducible failures. - Letting matrices expand without cost controls -> excessive minutes and noisy failures that hide the real signal. - Depending on `ubuntu-latest` quirks without version pinning -> sudden toolchain drift after runner image updates. - Rebuilding instead of promoting the tested artifact -> release mismatch between validated code and shipped code. - Treating reruns as the fix -> root cause remains and the incident repeats. ## External Endpoints | Endpoint | Data Sent | Purpose | |----------|-----------|---------| | https://github.com | repository metadata, git refs, workflow files, run pages, and artifact access | GitHub repository and Actions UI workflows | | https://api.github.com | workflow, run, check, release, and repository API payloads | API-driven Actions inspection and control | | Cloud or deployment endpoints explicitly configured by the workflow | deployment payloads, build artifacts, and short-lived auth tokens | Release and deploy steps after user approval | No other data should be sent externally unless the workflow itself is configured to call additional services. ## Security & Privacy Data that leaves your machine: - GitHub repository and Actions traffic when the user requests live inspection or workflow changes - deployment traffic only to user-approved targets configured in the workflow Data that stays local: - repository operating notes under `.agents/skill-state/github-actions/` - workflow drafts, incident analysis, and release policies prepared locally This skill does NOT: - ask for raw personal access tokens or cloud secrets in chat - recommend bypassing branch protection or approval gates - hide undeclared outbound integrations - modify its own `SKILL.md` ## Trust This skill depends on GitHub and any deployment systems the user explicitly connects to their workflows. Only install and run it if you trust those systems with your repository and release data. ## Scope This skill ONLY: - designs, reviews, and improves GitHub Actions workflows - debugs workflow runs with log-driven reasoning and stable reproduction steps - structures safe release and deployment automation This skill NEVER: - assume write access to repositories or environments without confirmation - suggest secret exfiltration, masking bypasses, or hidden credential handling - normalize production deployment from untrusted pull request contexts ## Related Skills Install with `clawhub install <slug>` if user confirms: - `ci-cd` - Choose CI and deployment strategy before locking into one platform. - `git` - Tighten branch, tag, and history handling around workflow events. - `workflow` - Design multi-step execution systems with clearer ownership and gating. - `devops` - Connect delivery pipelines to infrastructure and operational guardrails. - `docker` - Improve container build, cache, and registry steps inside Actions workflows. ## Feedback - If useful: `clawhub star github-actions` - Stay updated: `clawhub sync`