pinact

pinact

Install | Usage | Configuration | Agent Skill

pinact is a CLI to pin GitHub Actions and Reusable Workflows. pinact can also update their versions and verify version comments.

[!NOTE] If you are a coding agent and pinact is installed, run pinact docs list to list the documentation and pinact docs show to read it before answering questions about pinact or troubleshooting its errors. The embedded documentation matches the installed version. If pinact isn't installed, read the documents listed in Documentation.

…

Features

1. Pin GitHub Actions and Reusable Workflows
2. Check if actions are pinned without editing files
3. Offline check without GitHub API
4. Update actions with a minimum release age
5. Verify version comments
6. Require a version comment on SHA-pinned actions
7. Verify if actions meet the minimum release age
8. Pin branches
9. Include and exclude specific actions
10. Generate SARIF. This is useful to create reviews using reviewdog
11. Read GitHub access token via keyrings or ghtkn
12. Pin only changed lines
13. Support GitHub Enterprise Server
14. GitHub Action

Getting Started

1. Install pinact

2. Pin the actions of a repository:

pinact run

Without an argument, pinact pins the workflow files and the action files of the repository; Usage lists them and shows how to pin actions written in a document such as README.md.

1. Check them in CI instead of fixing them:

pinact run --check

The run exits with a non-zero code when something needs pinning. Checking without fixing covers --check, --fix=false, and the offline check --no-api.

1. Pass a GitHub access token so the API calls aren't rate limited:

export GITHUB_TOKEN=

pinact can also read the token from the OS keyring or from ghtkn.

1. Optionally, write a configuration file:

pinact init

The configuration file is optional. It says which files to pin, which actions to ignore, and what the default minimum release age is. See Configuration File.

Installing the Agent Skill

pinact ships a single skill. It holds no documentation of its own: it tells the coding agent to read the documentation embedded in the pinact binary with pinact docs list and pinact docs show , so the agent always reads the documentation of the version it is actually running.

gh skill install:

gh skill install suzuki-shunsuke/pinact pinact

Documentation

The documentation is split by topic under docs/. These documents are embedded in the pinact binary, so pinact docs list and pinact docs show (pinact >= v5.0.0) serve exactly what is listed below, matching the version that is installed. They are the single source of truth, shared between this README, the embedded documentation, and the skill, so there's no duplicated maintenance.

pinact docs list # The name and the description of every document, as JSON
pinact docs show config # One document
pinact docs show codes/005 # A document in a subdirectory is named by its path

• Usage - run pinact, which files it pins when none is given, and pinning actions written in a document.
• Checking without fixing - --check, --fix=false, the offline check --no-api, and verifying version comments.
• Updating actions - --update and the minimum release age (cooldown).
• Pin branches - --branch-to-tag, which opts a branch reference in to being pinned.
• Include and exclude specific actions - --include and --exclude.
• SARIF - --format sarif, reviewdog, and GitHub code scanning.
• Pin only changed lines - --diff-file, to introduce pinact gradually.
• GitHub access token - PINACT_GITHUB_TOKEN, the ghtkn integration, and the OS keyring.
• Configuration File - the configuration file, the global configuration file, and every field of the schema.
• GitHub Enterprise Server - pinning actions hosted on GHES.
• Exit codes - what 0, 1, 2, and 3 mean.
• Why doesn't pinact pin some actions? - why a branch reference isn't pinned by default.
• Verify version comments - why a version comment isn't necessarily true, and how --verify-comment checks it.
• SHA-pinned action requires a version comment - why a bare SHA is rejected, and how to resolve it.
• Schema version is required, this version was abandoned, unsupported configuration format version - the configuration schema version errors.
• Old schemas - the configuration schema versions pinact no longer supports.
• Upgrade guide: v3 to v4, v4 to v5 - what changed between major versions.

USAGE.md is the help of every command, generated from the CLI itself.

GitHub Actions

https://github.com/suzuki-shunsuke/pinact-action

We develop GitHub Actions to pin GitHub Actions and reusable workflows by pinact.

Motivation

It is a good manner to pin GitHub Actions versions by commit hash. GitHub tags are mutable so they have a substantial security and reliability risk.

See also Security hardening for GitHub Actions - GitHub Docs

Pinning an action to a full length commit SHA is currently the only way to use an action as an immutable release. Pinning to a particular SHA helps mitigate the risk of a bad actor adding a backdoor to the action's repository, as they would need to generate a SHA-1 collision for a valid Git object payload

:thumbsup:

uses: actions/cache@88522ab9f39a2ea568f7027eddc7d8d8bc9d59c8 # v3.3.1

:thumbsdown:

uses: actions/cache@v3

uses: actions/[email protected]

Why not using Renovate's helpers:pinGitHubActionDigestsToSemver preset?

The Renovate preset helpers:pinGitHubActionDigestsToSemver is useful, but pinact is still useful: You can use both the preset and pinact together.

1. Renovate can't pin actions in pull requests before merging them. If you use linters such as ghalint in CI, you need to pin actions before merging pull requests (ref. ghalint policy to enforce actions to be pinned)
2. Even if you use Renovate, sometimes you would want to update actions manually
3. pinact is useful for non Renovate users
4. pinact supports verifying version annotations

See also

• Renovate github-actions Manager - Additional Information
• sethvargo/ratchet is a great tool, but there are known issues.