Agent Skills: GitHub Actions Knowledge Patch

GitHub Actions Knowledge Patch

Use this skill when writing, reviewing, securing, or operating GitHub Actions workflows and self-hosted runner fleets. Start with the execution event, ref, permissions, code provenance, environment protections, and runner version; several safeguards depend on those boundaries rather than on YAML alone.

Reference index

| Reference | Topics | | --- | --- | | security-trust-and-policy.md | Approval holds, privileged pull-request refs, environment rules, cache trust, fork checkout protection, execution policy, action allowlists, and OIDC identity | | self-hosted-runners.md | Registration and release-age gates, enforcement and brownouts, fleet discovery, autoscaling, and runner interfaces | | workflow-semantics-and-limits.md | Same-repository references, concurrent steps, cancellation, reusable-workflow limits, and manual inputs | | hosted-runner-images.md | Windows Server 2025 with Visual Studio 2026, macOS 26 Intel, and M2 labels |

Review the trust boundary first

Before changing a workflow, identify:

• the triggering event and who can trigger it;
• the execution ref and SHA;
• whether any checked-out or fetched code is pull-request-controlled;
• the effective GITHUB_TOKEN, OIDC, secret, and environment permissions;
• the cache scope and whether the run may save to it; and
• the runner ownership, isolation, and installed version.

Treat pull_request_target and pull-request-derived workflow_run jobs as privileged. Never execute fork-controlled code there without an explicit, reviewed trust design.

Account for automatic malicious-workflow holds

On github.com, some runs in public repositories that are identified as potentially malicious are held automatically. No repository configuration is needed. The run begins only after a repository collaborator with write access approves it in an authenticated web session, then proceeds normally.

Do not build automation that assumes every accepted event starts immediately. This hold does not apply to GitHub Enterprise Server. See security-trust-and-policy.md for the exact scope.

Re-evaluate pull_request_target refs

pull_request_target always loads the workflow and commit from the default branch, including when the pull request targets another base branch:

• GITHUB_REF is the default branch.
• GITHUB_SHA is the latest commit on that branch.

Environment branch protections evaluate the execution ref, not HEAD_REF. For pull_request, pull_request_review, and pull_request_review_comment, that ref is refs/pull/number/merge; for pull_request_target, it is the default branch. Adjust environment branch patterns that assumed the older ref selection.

Expect read-only caches in untrusted shared scopes

The cache token becomes read-only when an untrusted actor can trigger the event and both execution and cache scope use the shared default-branch SHA. Restores still work. A blocked save warns but does not fail the job.

Populate required caches from a trusted workflow such as push; do not treat the warning as proof that the cache was updated. The detailed reference lists the events that retain read-write access.

Keep fork checkout protection enabled

actions/checkout v7 rejects fork pull-request head or merge checkouts in:

• pull_request_target; and
• workflow_run when the originating event is a pull_request* event.

The check covers a fork repository, pull-request head or merge refs, and their corresponding SHAs when supplied with repository or ref. Same-repository pull requests and ordinary pull_request runs are unaffected.

Use allow-unsafe-pr-checkout only after security review. It does not protect shell-based fetches or checkouts of unrelated repositories. Floating major tags and immutable pins have different upgrade behavior; consult the detailed reference before relying on a supported pre-v7 major.

Apply policy before execution

Public-preview workflow execution protections use rulesets at enterprise, organization, and repository scope. Actor rules can allowlist users, repository roles, GitHub Apps, Copilot, or Dependabot. Event rules can allowlist triggers such as push, pull_request, pull_request_target, and workflow_dispatch.

Rules are evaluated before a run starts and are configured separately from general Actions settings under Actions > Policies. Use evaluate mode to preview enforcement, and custom properties to target repositories from an organization-wide ruleset.

Action and reusable-workflow allowlisting is available on Free, Team, and Enterprise plans. Repository policy can restrict execution to an explicitly selected set of actions and reusable workflows.

Bind OIDC decisions to a job

OIDC tokens include check_run_id alongside claims such as run_id and run_attempt. Use check_run_id when an external authorization or audit system must identify the exact job and compute that requested a token.

Enforce both self-hosted runner version gates

Runner 2.329.0 is the minimum for configuring or re-registering a self-hosted runner on the new platform. It is not a permanent execution floor. Every runner release, including patch releases, must be installed within 30 days of publication or the service stops queuing jobs to that runner.

Auto-update satisfies the rolling requirement when its update service is reachable. Fleets with auto-update disabled need a regular manual upgrade process. A critical security release pauses queuing until installed and has no normal grace period.

Full enforcement begins July 31, 2026 for Enterprise Cloud with Data Residency and September 25, 2026 for Enterprise Cloud. Enterprise Server is not affected. Registration-only and registration-and-runtime brownouts occur before the standard cloud date; use self-hosted-runners.md for every window.

Inventory runner versions through the self-hosted-runners REST API using API version 2026-03-10. Registration audit events include a version but are not a complete inventory. Runtime annotations identify outdated runners before enforcement.

Gate features on runner interfaces

Runner 2.336.0 supports $GITHUB_ARTIFACTS environment files and exposes the effective cache mode through ACTIONS_CACHE_MODE. Workflows or actions using either interface require that runner version or later.

The same runner floor applies to self-repository $/ references. A uses: value beginning with $/ resolves an action or reusable workflow in the same repository at the exact commit being run, without a checkout:

steps:
  - uses: $/.github/actions/setup

Use this syntax anywhere a ./ reference is accepted on github.com.

Coordinate concurrent steps explicitly

Steps can run asynchronously with background: true while retaining separate logs. Use wait for a named earlier background step, wait-all for all earlier background steps, and cancel for graceful termination. parallel starts a group as background steps and then waits.

jobs:
  integration:
    runs-on: ubuntu-latest
    steps:
      - name: Start service
        run: ./serve
        background: true
      - name: Exercise service
        run: ./test

On runner 2.336.0, canceled background steps no longer affect the job result, and cancellation waits for the worker to finish. Gate runner versions when correctness depends on these semantics.

Use the expanded workflow limits

• A run can nest up to 10 reusable workflows.
• A run can call up to 50 reusable workflows in total.
• workflow_dispatch accepts up to 25 top-level inputs, including API starts.

These replace the earlier limits of four nested reusable workflows, 20 total reusable workflows, and 10 manual-dispatch inputs.

Choose runner capacity deliberately

The public-preview actions/scaleset Go client orchestrates runner scale-set APIs for custom autoscaling outside Kubernetes and supports multiple labels per scale set. The integrator still owns infrastructure provisioning, scaling, and destruction. Actions Runner Controller remains the recommended Kubernetes implementation.

Hosted choices include the public-preview windows-2025-vs2026 and macos-26-large labels plus generally available M2 xlarge macOS labels. Read hosted-runner-images.md before selecting one; preview status, architecture, and image migration affect reproducibility.