Skip to content
Jefferson Gonçalves
← Back to projects

Pinact

pinact is a CLI to edit GitHub Workflow and Composite action files and pin versions of Actions and Reusable Workflows. pinact can also update their versions and verify version annotations.

#pinact

Ask DeepWiki 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 <name> 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.

$ pinact run
.github/workflows/test.yaml:8
-       - uses: actions/checkout@83b7061638ee4956cf7545a6f7efe594e5ad0247 # v3
+       - uses: actions/checkout@83b7061638ee4956cf7545a6f7efe594e5ad0247 # v3.5.1
.github/workflows/test.yaml:9
-       - uses: actions/setup-go@v4
+       - uses: actions/setup-go@7b8cf10d4e4a01d4992d18a89f4d7dc5a3e6d6f4 # v4.3.0
.github/workflows/test.yaml:10
-       - uses: actions/cache@v3.3.1
+       - uses: actions/cache@88522ab9f39a2ea568f7027eddc7d8d8bc9d59c8 # v3.3.1
.github/workflows/test.yaml:16
-     uses: suzuki-shunsuke/actionlint-workflow/.github/workflows/actionlint.yaml@v0.5.0
+     uses: suzuki-shunsuke/actionlint-workflow/.github/workflows/actionlint.yaml@b6a5f966d4504893b2aeb60cf2b0de8946e48504 # v0.5.0

#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=<your 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 <name>, 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 <name> (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.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/cache@v3.3.1

#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

New version available.