gh-actions

name	gh-actions
description	GitHub Actions best practices — current action versions, caching, security, and common patterns. Activate when writing or modifying GitHub Actions workflows.

GitHub Actions Best Practices

When writing or modifying GitHub Actions workflows (.github/workflows/*.yml), follow these guidelines.

Action Versions

Never guess action versions. Before writing or updating a workflow, check the latest release for each action you use:

gh api repos/{owner}/{action}/releases/latest --jq '.tag_name'

The {owner}/{action} maps directly to the GitHub repo — e.g. actions/checkout lives at github.com/actions/checkout.

For example:

gh api repos/actions/checkout/releases/latest --jq '.tag_name'
gh api repos/actions/setup-node/releases/latest --jq '.tag_name'

Use the latest major version (e.g. if the latest tag is v6.3.0, use v6). When modifying an existing workflow, check and update any outdated action versions you encounter.

Security

• Always set top-level permissions to least privilege. Start with permissions: {} and add only what's needed:

  permissions:
    contents: read
  

• Never use permissions: write-all or omit permissions entirely
• Use pull_request, not pull_request_target. Only use pull_request_target when the workflow must write to the base repo from a fork — it runs with write access and secrets from the base branch