pinact

https://github.com/suzuki-shunsuke/pinact
Admin
A CLI tool to pin GitHub Actions and Reusable Workflows to commit hashes for supply chain security,...
Tokens:25,445
Snippets:280
Trust Score:9.6
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install pinact with Scoop

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/INSTALL.md

Add the bucket and install pinact using Scoop.

```sh
scoop bucket add suzuki-shunsuke https://github.com/suzuki-shunsuke/scoop-bucket
scoop install pinact
```

--------------------------------

### Full .pinact.yaml Configuration Example

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/config.md

A comprehensive example of a version 3 configuration file, demonstrating file patterns, action ignores, GHES settings, and rule-based overrides.

```yaml
version: 3
files:
  - pattern: .github/workflows/*.yml
  - pattern: .github/workflows/*.yaml
  - pattern: .github/actions/*/action.yml
  - pattern: .github/actions/*/action.yaml

ignore_actions:
  # slsa-framework/slsa-github-generator doesn't support pinning version
  # > Invalid ref: 68bad40844440577b33778c9f29077a3388838e9. Expected ref of the form refs/tags/vX.Y.Z
  # https://github.com/slsa-framework/slsa-github-generator/issues/722
  - name: slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml
    ref: "v\\d+\\.\\d+\\.\\d+"
  - name: suzuki-shunsuke/.*
    ref: main

# GitHub Enterprise Server Support
ghes:
  api_url: https://ghes.example.com
  fallback: true # optional, default is false

# Separator between version and tag comment (optional, default is " # ")
# pinact >= v3.9.0
separator: " # "

# Default min-age in days (optional)
# pinact >= v4.0.0
min_age:
  value: 7
  always: true

rules:
  - ignore: true
    conditions:
      - expr: |
          ActionName == "slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml" && ActionVersion matches "v\\d+\\.\\d+\\.\\d+"
      - expr: |
          ActionName matches "suzuki-shunsuke/.*" && ActionVersion == "main"
  - min_age: 0
    conditions:
      - expr: |
          ActionName matches "suzuki-shunsuke/.*" && ActionVersion == "main"
```

--------------------------------

### Install pinact with mise

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/INSTALL.md

Install pinact using the mise tool manager.

```sh
mise use -g pinact@latest
```

--------------------------------

### Install pinact with Homebrew

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/INSTALL.md

Install pinact using the Homebrew package manager.

```sh
brew install pinact
```

--------------------------------

### Install pinact with Homebrew Tap

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/INSTALL.md

Install pinact using the specific Homebrew tap.

```sh
brew install suzuki-shunsuke/pinact/pinact
```

--------------------------------

### Build pinact from source with Go

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/INSTALL.md

Install the latest version of pinact directly from the source repository using Go.

```sh
go install github.com/suzuki-shunsuke/pinact/v5/cmd/pinact@latest
```

--------------------------------

### ignore_actions configuration example

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/config.md

Example YAML configuration for ignore_actions. The name and ref fields are required regular expressions that must match exactly. Go's regexp package is used.

```yaml
ignore_actions:
  - name: actions/.*
    ref: main

```

--------------------------------

### Install pinact with aqua

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/INSTALL.md

Install pinact using the aqua package manager.

```sh
aqua g -i suzuki-shunsuke/pinact
```

--------------------------------

### Install development tools with aqua

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/CONTRIBUTING.md

Installs development tools, including cmdx, using aqua. Run this before using cmdx commands.

```sh
aqua i # Install development tools including cmdx
```

--------------------------------

### Install pinact skill with gh skill install

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/README.md

Installs the pinact skill for a coding agent. The skill instructs the agent to read the embedded documentation via pinact docs commands.

```sh
gh skill install suzuki-shunsuke/pinact pinact
```

--------------------------------

### Pin actions in README.md

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/usage.md

Example of running pinact on a specific text file like README.md to pin actions.

```sh
pinact run README.md
```

--------------------------------

### Example unified diff file

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/diff_file.md

An example of a unified diff file that pinact can process. It shows a change in a GitHub Actions workflow file, updating the version of actions/setup-go.

```diff
diff --git a/testdata/diff-file/action.yaml b/testdata/diff-file/action.yaml
index 0000001..0000002 100644
--- a/testdata/diff-file/action.yaml
+++ b/testdata/diff-file/action.yaml
@@ -7,5 +7,5 @@ jobs:
     permissions: {}
     steps:
       - uses: actions/checkout@v3.6.0
-      - uses: actions/setup-go@v3.5.0
+      - uses: actions/setup-go@v4.0.0
       - uses: actions/cache@v3.3.1
```

--------------------------------

### Run pinact with multiple --branch-to-tag options

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/branch_to_tag.md

Example of specifying --branch-to-tag multiple times to match different branch patterns like 'main' and 'release/.*'.

```sh
pinact run --branch-to-tag '^main$' --branch-to-tag '^release/.*$'
```

--------------------------------

### Verify GitHub release with Cosign

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/INSTALL.md

Install Cosign via aqua and verify the blob signature and checksums.

```sh
aqua g -i sigstore/cosign
```

```sh
version=v1.0.0
checksum_file="pinact_${version#v}_checksums.txt"
asset=pinact_darwin_arm64.tar.gz
gh release download "$version" \
  -R suzuki-shunsuke/pinact \
  -p "$asset" \
  -p "$checksum_file" \
  -p "${checksum_file}.pem" \
  -p "${checksum_file}.sig"
cosign verify-blob \
  --signature "${checksum_file}.sig" \
  --certificate "${checksum_file}.pem" \
  --certificate-identity-regexp 'https://github\.com/suzuki-shunsuke/go-release-workflow/\.github/workflows/release\.yaml@.*' \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  "$checksum_file"
cat "$checksum_file" | sha256sum -c --ignore-missing
```

--------------------------------

### Verify GitHub release with slsa-verifier

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/INSTALL.md

Install slsa-verifier via aqua and verify the artifact provenance.

```sh
aqua g -i slsa-framework/slsa-verifier
```

```sh
version=v1.0.0
asset=pinact_darwin_arm64.tar.gz
gh release download -R suzuki-shunsuke/pinact "$version" -p "$asset" -p multiple.intoto.jsonl
slsa-verifier verify-artifact "$asset" \
  --provenance-path multiple.intoto.jsonl \
  --source-uri github.com/suzuki-shunsuke/pinact \
  --source-tag "$version"
```

--------------------------------

### Commit message examples

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/AGENTS.md

Example commit messages demonstrating the Conventional Commits format with various types such as feat, fix, docs, and chore(deps).

```text
feat: add GitHub token management via keyring
fix: handle empty configuration file correctly
docs: add function documentation to controller package
chore(deps): update dependency aquaproj/aqua-registry to v4.403.0
```

--------------------------------

### Verify GitHub release with GitHub CLI

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/INSTALL.md

Install GitHub CLI via aqua and verify the downloaded asset using gh attestation.

```sh
aqua g -i cli/cli
```

```sh
version=v1.0.0
asset=pinact_darwin_arm64.tar.gz
gh release download -R suzuki-shunsuke/pinact "$version" -p "$asset"
gh attestation verify "$asset" \
  -R suzuki-shunsuke/pinact \
  --signer-workflow suzuki-shunsuke/go-release-workflow/.github/workflows/release.yaml
```

--------------------------------

### separator configuration examples

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/config.md

Examples of setting the separator option. The default is ' # ' and it must include '#'. It can also be set via --separator or PINACT_SEPARATOR. The separator is placed between the commit SHA and the version tag comment.

```yaml
# Default separator " # "
separator: " # "
# Results in: uses: actions/checkout@abc123... # v3.5.0

# Custom separator " # tag="
separator: " # tag="
# Results in: uses: actions/checkout@abc123... # tag=v3.5.0

# Custom separator with double space before #
separator: "  # "
# Results in: uses: actions/checkout@abc123...  # v3.5.0

```

--------------------------------

### Workflow

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/specs/839/README.md

Example GitHub Actions workflow showing how pinact behaves with GHES. When fallback is disabled (default), always use GHES; when enabled, check GHES first and fallback to github.com if not found.

```yaml
# .github/workflows/ci.yml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      # When fallback is disabled (default): always use GHES
      # When fallback is enabled: check GHES first, fallback to github.com if not found
      - uses: my-org/build-action@v1

      # Same behavior for all actions
      - uses: actions/checkout@v4

```

--------------------------------

### Unpinned action using a branch

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/why_pinact_not_pin.md

Example of an action reference using a branch name, which pinact will not automatically pin.

```yaml
uses: actions/checkout@main
```

--------------------------------

### pinact run diff output

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/README.md

Example output from running `pinact run` showing the changes it makes to a GitHub Actions workflow file. It replaces version tags with commit SHAs and adds version comments (e.g., # v3.5.1).

```diff
$ 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
```

--------------------------------

### Example of a mismatched version annotation

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/codes/001.md

A GitHub Action workflow step where the version comment v3.5.1 does not match the actual commit hash ee0669bd1cc54295c223e0bb666b733df41de1c5, which corresponds to v2.7.0.

```yaml
- uses: actions/checkout@ee0669bd1cc54295c223e0bb666b733df41de1c5 # v3.5.1
```

--------------------------------

### Action pinned to a full commit SHA

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/why_pinact_not_pin.md

An example of pinning to a full commit SHA, which pinact avoids for branches because it prevents updates following semantic versioning.

```yaml
uses: actions/checkout@85e6279cec87321a52edac9c87bce653a07cf6c2 # main
```

--------------------------------

### Short flags unchanged in v5

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/upgrade_guide/v5.md

Short flags can still be written with a single dash. These examples show valid short flag usage in v5.

```sh
pinact run -u -m 7
pinact run -i "^actions/.*$" -e "^actions/checkout$"
pinact init -g
pinact -c pinact.yaml run
```

--------------------------------

### Action pinned to a specific semver tag

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/why_pinact_not_pin.md

An example of changing a branch reference to a specific semver tag, which pinact avoids because it changes the SHA and may break workflows.

```yaml
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # 4.2.2
```

--------------------------------

### Error message for single-dash long flag

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/upgrade_guide/v5.md

When a single-dash long flag is used in v5, pinact rejects it with an error naming the form to use. This example shows the error for `-check`.

```console
$ pinact run -check
unknown flag: -check. Long flags need two dashes since pinact v5: --check
```

--------------------------------

### Long flags need two dashes: v4 vs v5 examples

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/upgrade_guide/v5.md

Shows the v4 single-dash long flags and the corresponding v5 two-dash forms. In v5, a single dash introduces short flags, so `-check` means `-c -h -e -c -k`. Use the v5 forms to avoid errors.

```sh
# v4
pinact run -check
pinact run -fix=false -no-api
pinact run -diff-file diff.txt

# v5
pinact run --check
pinact run --fix=false --no-api
pinact run --diff-file diff.txt
```

--------------------------------

### Display pinact init help

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/USAGE.md

Displays help for the init command, which creates a pinact configuration file.

```console
$ pinact init --help
NAME:
   pinact init - Create a pinact configuration file if it doesn't exist

USAGE:
   pinact init [options]

DESCRIPTION:
   Create a pinact configuration file if it doesn't exist. The resolved path is printed to stdout.

   $ pinact init                          # creates .pinact.yaml in the current directory
   $ pinact init .github/pinact.yaml      # explicit path
   $ pinact init -g                       # creates the user-wide global config


OPTIONS:
   --global, -g  Create the user-wide global config file (~/.config/pinact/pinact.yaml on Unix, %APPDATA%\pinact\pinact.yaml on Windows). The parent directory is created if it does not exist.
   --help, -h    show help

GLOBAL OPTIONS:
   --log-level string          log level [$PINACT_LOG_LEVEL]
   --config string, -c string  configuration file path [$PINACT_CONFIG]
```

--------------------------------

### Initialize configuration file

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/config.md

Use the init command to generate a configuration file at the specified path.

```sh
pinact init [<configuration file path>]
```

--------------------------------

### Lint with cmdx (go vet and golangci-lint)

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/CONTRIBUTING.md

Runs go vet and golangci-lint via cmdx. The comments indicate the underlying tools.

```sh
cmdx v # go vet
```

```sh
cmdx l # golangci-lint
```

--------------------------------

### pinact run --help output

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/USAGE.md

Shows the full help text for the `pinact run` command. It lists usage, options like `--verify-comment`, `--no-api`, `--check`, `--update`, `--fix`, `--diff`, `--format`, `--include`, `--exclude`, `--branch-to-tag`, `--min-age`, `--separator`, and `--diff-file`, along with global options. The description explains that without arguments it searches `.github/workflows` and that file paths can be passed as arguments.

```console
$ pinact run --help
NAME:
   pinact run - Pin GitHub Actions versions

USAGE:
   pinact run [options] [files ...] 

DESCRIPTION:
   If no argument is passed, pinact searches GitHub Actions workflow files from .github/workflows.

   $ pinact run

   You can also pass workflow file paths as arguments.

   e.g.

   $ pinact run .github/actions/foo/action.yaml .github/actions/bar/action.yaml


OPTIONS:
   --verify-comment, --verify, -v                               Verify that the version comment matches the pinned SHA
   --verify-min-age                                             Audit every pinned action against the min-age threshold (calls the GitHub API). Auto-enabled when -min-age is set on the CLI
   --no-api                                                     Skip GitHub API calls. Only the syntactic pin check (40-character SHA) is performed
   --check                                                      Alias for -fix=false. For offline check use -fix=false -no-api
   --update, -u                                                 Update actions to latest versions
   --fix                                                        Fix code. By default, this is true. If -check or -diff is true, this is false by default
   --diff                                                       Alias for -fix=false. Note: -diff=false is ignored because detail output is always printed in v4
   --format string                                              Output format. Currently only 'sarif' is supported. If sarif is specified, results are output in SARIF format to stdout
   --include string, -i string [ --include string, -i string ]  A regular expression to fix actions
   --exclude string, -e string [ --exclude string, -e string ]  A regular expression to exclude actions
   --branch-to-tag string [ --branch-to-tag string ]            A regular expression to convert non-semver versions (e.g. branch names) to the latest stable tag. Anchor with ^$ for exact match
   --min-age int, -m int                                        Minimum release age threshold in days. Setting this (either via CLI or PINACT_MIN_AGE) implicitly enables -verify-min-age (default: 0) [$PINACT_MIN_AGE]
   --separator string, --sep string                             Separator between version and tag comment
   --diff-file +                                                Path to a unified diff. Only the + lines of the diff are processed (use `-` to read the diff from stdin). Useful in PR CI to limit pinact to lines changed by the PR
   --help, -h                                                   show help

GLOBAL OPTIONS:
   --log-level string          log level [$PINACT_LOG_LEVEL]
   --config string, -c string  configuration file path [$PINACT_CONFIG]
```

--------------------------------

### Sample workflow for testing

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/specs/1265/test.md

A sample GitHub Actions workflow file and the corresponding command to run pinact against it.

```yaml
name: Test
on: push
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      # Test with actions/checkout (has releases)
      - uses: actions/checkout@v4

      # Test with an action that only has tags
      - uses: suzuki-shunsuke/tfcmt@v1
```

```sh
pinact run -u --min-age 7 .github/workflows/test.yaml --log-level info
# or
pinact run -u -m 7 .github/workflows/test.yaml --log-level info
```

--------------------------------

### Initialize pinact configuration

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/README.md

Creates an optional configuration file that specifies which files to pin, which actions to ignore, and the default minimum release age.

```sh
pinact init
```

--------------------------------

### pinact token command

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/USAGE.md

Displays help information for managing GitHub access tokens stored in the system keyring.

```console
$ pinact token --help
NAME:
   pinact token - Manage GitHub Access token

USAGE:
   pinact token [command [command options]]

DESCRIPTION:
   Manage GitHub Access token by keyring.

COMMANDS:
   set         Set GitHub Access token
   remove, rm  Remove GitHub Access token

OPTIONS:
   --help, -h  show help

GLOBAL OPTIONS:
   --log-level string          log level [$PINACT_LOG_LEVEL]
   --config string, -c string  configuration file path [$PINACT_CONFIG]
```

--------------------------------

### Display pinact help

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/USAGE.md

Displays the main help menu for the pinact CLI, listing available commands and global options.

```console
$ pinact --help
NAME:
   pinact - Pin GitHub Actions versions. https://github.com/suzuki-shunsuke/pinact

USAGE:
   pinact [global options] [command [command options]]

VERSION:
   4.1.1

COMMANDS:
   init        Create a pinact configuration file if it doesn't exist
   run         Pin GitHub Actions versions
   migrate     Migrate .pinact.yaml
   token       Manage GitHub Access token
   version     Show version
   help, h     Shows a list of commands or help for one command
   completion  Output shell completion script for bash, zsh, fish, or Powershell

GLOBAL OPTIONS:
   --log-level string          log level [$PINACT_LOG_LEVEL]
   --config string, -c string  configuration file path [$PINACT_CONFIG]
   --help, -h                  show help
   --version, -v               print the version
```

--------------------------------

### Initialize global configuration file

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/config.md

Use this command to create a global configuration file if it does not already exist. It respects the $PINACT_GLOBAL_CONFIG environment variable for the target path.

```sh
pinact init -g
```

--------------------------------

### pinact completion pwsh help

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/USAGE.md

Displays the help information for the pwsh completion command.

```console
$ completion pwsh --help
NAME:
   pinact completion pwsh - Output pwsh completion script

USAGE:
   pinact completion pwsh [options]

OPTIONS:
   --help, -h  show help
```

--------------------------------

### pinact completion bash help

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/USAGE.md

Displays the help information for the bash completion command.

```console
$ completion bash --help
NAME:
   pinact completion bash - Output bash completion script

USAGE:
   pinact completion bash [options]

OPTIONS:
   --help, -h  show help
```

--------------------------------

### pinact version help

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/USAGE.md

Displays the help information for the pinact version command, including options for JSON output.

```console
$ pinact version --help
NAME:
   pinact version - Show version

USAGE:
   pinact version [options]

OPTIONS:
   --json, -j  Output version in JSON format
   --help, -h  show help

GLOBAL OPTIONS:
   --log-level string          log level [$PINACT_LOG_LEVEL]
   --config string, -c string  configuration file path [$PINACT_CONFIG]
```

--------------------------------

### pinact completion zsh help

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/USAGE.md

Displays the help information for the zsh completion command.

```console
$ completion zsh --help
NAME:
   pinact completion zsh - Output zsh completion script

USAGE:
   pinact completion zsh [options]

OPTIONS:
   --help, -h  show help
```

--------------------------------

### pinact token set command

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/USAGE.md

Displays help for the token set command, used to store a GitHub access token in the keyring. Use the --stdin flag to provide the token via standard input.

```console
$ token set --help
NAME:
   pinact token set - Set GitHub Access token

USAGE:
   pinact token set [options]

DESCRIPTION:
   Set GitHub Access token to keyring.

OPTIONS:
   --stdin     Read GitHub Access token from stdin
   --help, -h  show help

GLOBAL OPTIONS:
   --log-level string          log level [$PINACT_LOG_LEVEL]
   --config string, -c string  configuration file path [$PINACT_CONFIG]
```

--------------------------------

### pinact completion fish help

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/USAGE.md

Displays the help information for the fish completion command.

```console
$ completion fish --help
NAME:
   pinact completion fish - Output fish completion script

USAGE:
   pinact completion fish [options]

OPTIONS:
   --help, -h  show help
```

--------------------------------

### Important Commands

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/AGENTS.md

Commands for validating code, running tests, building the project, generating the JSON schema, and running pinact locally.

```bash
# Validate code (go vet)
cmdx v

# Run tests
cmdx t

# Build the project
go build ./cmd/pinact

# Generate JSON schema
cmdx js

# Run pinact locally
go run ./cmd/pinact run
```

--------------------------------

### pinact completion help

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/USAGE.md

Displays the help information for the pinact completion command, which generates shell completion scripts.

```console
$ pinact completion --help
NAME:
   pinact completion - Output shell completion script for bash, zsh, fish, or Powershell

USAGE:
   pinact completion [command [command options]]

DESCRIPTION:
   Output shell completion script for bash, zsh, fish, or Powershell.
   Source the output to enable completion.

   # .bashrc
   source <(pinact completion bash)

   # .zshrc
   source <(pinact completion zsh)

   # fish
   pinact completion fish > ~/.config/fish/completions/pinact.fish

   # Powershell
   Output the script to path/to/autocomplete/pinact.ps1 an run it.


COMMANDS:
   bash  Output bash completion script
   zsh   Output zsh completion script
   fish  Output fish completion script
   pwsh  Output pwsh completion script

OPTIONS:
   --help, -h  show help
```

--------------------------------

### Using Configuration File (with fallback)

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/specs/839/README.md

Configure pinact to use GHES with fallback to github.com. Requires both GITHUB_TOKEN and GHES_TOKEN environment variables.

```yaml
# .pinact.yaml
ghes:
  api_url: https://ghes.example.com
  fallback: true

```

```bash
export GITHUB_TOKEN="ghp_xxxx"  # for github.com
export GHES_TOKEN="ghp_yyyy"    # for GHES

```

--------------------------------

### Using Configuration File (without fallback)

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/specs/839/README.md

Configure pinact to use GHES by setting the API URL in .pinact.yaml. Requires GHES_TOKEN environment variable.

```yaml
# .pinact.yaml
ghes:
  api_url: https://ghes.example.com

```

```bash
export GHES_TOKEN="ghp_yyyy"    # for GHES

```

--------------------------------

### Manage GitHub Access token with pinact token set and keyring

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/github_token.md

Configure a GitHub Access token in the OS keyring with `pinact token set`, optionally via standard input with `--stdin`. Enable the feature by setting `PINACT_KEYRING_ENABLED=true`; note that if `GITHUB_TOKEN` is set, the keyring feature is disabled. Remove the token with `pinact token rm`.

```console
$ pinact token set
Enter a GitHub access token: # Input GitHub Access token
```

```sh
echo "<github access token>" | pinact token set --stdin
```

```sh
export PINACT_KEYRING_ENABLED=true
```

```sh
pinact token rm
```

--------------------------------

### Configure minimum release age in .pinact.yml

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/update.md

Define default minimum release age and rule-specific overrides in the .pinact.yml configuration file.

```yaml
min_age:
  value: 7
rules:
  - min_age: 0
    conditions:
      - expr: |
          ActionRepoOwner == "suzuki-shunsuke"
```

--------------------------------

### Show cmdx tasks

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/CONTRIBUTING.md

Shows the available cmdx tasks.

```sh
cmdx help
```

--------------------------------

### Set minimum release age via CLI

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/update.md

Set the minimum release age in days using the --min-age flag.

```sh
pinact run --min-age 7
```

--------------------------------

### Run tests with cmdx

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/CONTRIBUTING.md

Runs the test suite via cmdx.

```sh
cmdx t
```

--------------------------------

### Verify current versions against minimum age

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/update.md

Use the --verify-min-age flag to check if current action versions meet the defined minimum release age requirement.

```sh
pinact run --verify-min-age
```

--------------------------------

### Default target files

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/usage.md

The list of files that pinact processes by default when no specific file is provided.

```text
.github/workflows/*.yml
.github/workflows/*.yaml
action.yml
action.yaml
*/action.yml
*/action.yaml
*/*/action.yml
*/*/action.yaml
*/*/*/action.yml
*/*/*/action.yaml
```

--------------------------------

### Validate configuration with ajv-cli

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/config.md

Use ajv-cli to validate your configuration file against the pinact JSON schema.

```sh
ajv --spec=draft2020 -s json-schema/pinact.json -d pinact.yaml
```

--------------------------------

### pinact migrate command

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/USAGE.md

Displays help information for the migrate command, which is used to update the version of the .pinact.yaml configuration file.

```console
$ pinact migrate --help
NAME:
   pinact migrate - Migrate .pinact.yaml

USAGE:
   pinact migrate [options]

DESCRIPTION:
   Migrate the version of .pinact.yaml

   $ pinact migrate


OPTIONS:
   --help, -h  show help

GLOBAL OPTIONS:
   --log-level string          log level [$PINACT_LOG_LEVEL]
   --config string, -c string  configuration file path [$PINACT_CONFIG]
```

--------------------------------

### Generate diff file with pr-unified-diff-action

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/diff_file.md

A GitHub Actions workflow step that uses suzuki-shunsuke/pr-unified-diff-action to generate a diff file, then runs pinact with that diff file. The diff path is stored in the `DIFF_FILE` environment variable.

```yaml
- uses: suzuki-shunsuke/pr-unified-diff-action@c932c1df5f577028d8ca05d2d3c0c059072d8821 # v0.0.1
  id: diff
- run: pinact run --diff-file "$DIFF_FILE"
  env:
    DIFF_FILE: ${{ steps.diff.outputs.diff_path }}
```

--------------------------------

### Using GITHUB_API_URL (GitHub Actions on GHES)

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/specs/839/README.md

When running on GitHub Actions hosted on GHES, GITHUB_API_URL is automatically set, so PINACT_GHES_API_URL is not required. Set GHES_TOKEN and optionally enable fallback.

```bash
# GITHUB_API_URL is automatically set by GitHub Actions on GHES
# GITHUB_API_URL="https://ghes.example.com/api/v3"

export GHES_TOKEN="ghp_yyyy"    # for GHES
# export PINACT_GHES_FALLBACK="true"  # optional: enable fallback
# export GITHUB_TOKEN="ghp_xxxx"  # required if fallback is enabled

```

--------------------------------

### Verify version annotation with pinact run --verify

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/codes/001.md

Running pinact with the --verify option detects a version annotation mismatch and reports an error for versions prior to v4.0.0.

```console
$ pinact run --verify testdata/bar.yaml
ERRO[0000] parse a line                                  action=actions/checkout action_version=ee0669bd1cc54295c223e0bb666b733df41de1c5 commit_hash_of_version_annotation=83b7061638ee4956cf7545a6f7efe594e5ad0247 error="verify the version annotation: action_version must be equal to commit_hash_of_version_annotation" help_docs="https://github.com/suzuki-shunsuke/pinact/blob/main/docs/codes/001.md" pinact_version= program=pinact version_annotation=v3.5.1 workflow_file=testdata/bar.yaml
```

--------------------------------

### Stable version filtering combined with min-age

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/specs/1265/test.md

Tests the combination of prerelease filtering and min-age filtering.

```yaml
- uses: owner/repo@sha # v1.0.0-beta
```

```sh
pinact run -u --min-age 30
```

--------------------------------

### Recommended: Pin GitHub Action to commit SHA with version comment

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/README.md

Use this format to pin an action to a full-length commit SHA, with a comment indicating the version. This is the recommended approach for security.

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

--------------------------------

### Run pinact with a diff file

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/diff_file.md

Use `pinact run --diff-file diff.txt` to pin only the lines changed in the unified diff file `diff.txt`. This is useful for introducing pinact gradually.

```sh
pinact run --diff-file diff.txt
```

--------------------------------

### Use --min-age 0

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/specs/1265/test.md

Setting --min-age to 0 disables filtering, behaving the same as a standard update.

```sh
pinact run -u --min-age 0
```

--------------------------------

### Run pinact command

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/usage.md

The basic command to execute pinact on specified workflow files.

```sh
pinact run [<workflow file>...]
```

--------------------------------

### Run go vet validation

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/AGENTS.md

Command to run go vet ./... for common Go mistakes. Must pass before committing changes.

```bash
cmdx v
```

--------------------------------

### Verify version comments with --verify-comment

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/check.md

Use --verify-comment to ensure that version comments accurately reflect the SHA of the action.

```sh
pinact run --verify-comment
```

--------------------------------

### YAML: bare SHA vs SHA with version comment

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/codes/005.md

Shows the error condition: a `uses:` line pinned to a bare SHA without a trailing `# <version>` comment, and the accepted form with a comment. The comment is required so pinact can verify the SHA against an upstream tag.

```yaml
# Error: bare SHA with no comment
- uses: owner/repo@e7500cdc5165d144721128822d9018f7be4eb43e

# OK: SHA backed by an upstream tag
- uses: owner/repo@e7500cdc5165d144721128822d9018f7be4eb43e # v1.2.3
```

--------------------------------

### Run pinact with --min-age option

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/specs/1265/README.md

Runs pinact with the update option and filters out versions released within the last 7 days. The short alias -m is equivalent to --min-age.

```sh
pinact run -u --min-age 7
# or using the short alias
pinact run -u -m 7
```

--------------------------------

### Run pinact with SARIF format and auto-fix

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/sarif.md

Generates output in SARIF format while still allowing file modifications via the --fix flag.

```sh
pinact run --format sarif --fix
```

--------------------------------

### pinact migrate command

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/codes/002.md

Migrate the configuration file to add the version field using the pinact migrate command.

```sh
pinact migrate
```

--------------------------------

### Shell: pinact run to add version comment

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/codes/005.md

Run pinact without `--no-api` so it can look up the tag and rewrite the line as `@<SHA> # <tag>`. This resolves the error when the SHA corresponds to an upstream tag.

```sh
pinact run
```

--------------------------------

### pinact token remove command

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/USAGE.md

Displays help for the token remove command, used to delete a stored GitHub access token from the keyring.

```console
$ token remove --help
NAME:
   pinact token remove - Remove GitHub Access token

USAGE:
   pinact token remove [options]

DESCRIPTION:
   Remove GitHub Access token from keyring.

OPTIONS:
   --help, -h  show help

GLOBAL OPTIONS:
   --log-level string          log level [$PINACT_LOG_LEVEL]
   --config string, -c string  configuration file path [$PINACT_CONFIG]
```

--------------------------------

### Skip recently released versions (tags)

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/specs/1265/test.md

Demonstrates skipping recent tags using a large min-age value.

```sh
pinact run -u --min-age 9999 --log-level info
```

--------------------------------

### GHES configuration file

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/ghes.md

Configure GHES via a configuration file. The configuration file takes precedence over environment variables. The fallback option is optional and defaults to false.

```yaml
ghes:
  api_url: https://ghes.example.com
  fallback: true # optional, default is false
```

--------------------------------

### Skip recently released versions (releases)

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/specs/1265/test.md

Demonstrates skipping recent GitHub releases using a large min-age value.

```sh
# Use a large min-age to skip recent releases
pinact run -u --min-age 9999 --log-level info
# or using short alias
pinact run -u -m 9999 --log-level info
```

--------------------------------

### Update actions to latest versions

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/update.md

Use the --update flag to update all actions to their latest available versions.

```sh
pinact run --update
```

--------------------------------

### Using Environment Variables Only

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/specs/839/README.md

Configure pinact for GHES using only environment variables. Set GHES_TOKEN and PINACT_GHES_API_URL. Optionally enable fallback with PINACT_GHES_FALLBACK and provide GITHUB_TOKEN if fallback is enabled.

```bash
export GHES_TOKEN="ghp_yyyy"    # for GHES
export PINACT_GHES_API_URL="https://ghes.example.com"
# export PINACT_GHES_FALLBACK="true"  # optional: enable fallback
# export GITHUB_TOKEN="ghp_xxxx"  # required if fallback is enabled

```

--------------------------------

### List and show embedded pinact documentation

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/README.md

Commands to list all embedded documents as JSON and to show a specific document by name or path. Requires pinact v5.0.0 or later.

```sh
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
```

--------------------------------

### Discouraged: Pin GitHub Action to version tag (v3.3.1)

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/README.md

This format uses a version tag, which is also mutable and not recommended for security.

```yaml
uses: actions/cache@v3.3.1
```

--------------------------------

### Configure Target Files

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/config.md

Defines the list of files that pinact should process using glob patterns.

```yaml
files:
  - pattern: .github/workflows/*.yml
  - pattern: .github/workflows/*.yaml
  - pattern: README.md
```

--------------------------------

### Run pinact with include regular expressions

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/include_exclude.md

Use `pinact run -i` to fix only actions matching the given regular expressions. Multiple `-i` options can be specified. Requires pinact >= v3.4.0.

```sh
pinact run -i "actions/.*" -i "^aquaproj/aqua-installer$"
```

--------------------------------

### Validate pinning with --check

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/check.md

Use --check to verify if actions are pinned without modifying files. This command exits with a non-zero exit code if issues are found, making it suitable for CI environments.

```sh
pinact run --check
```

--------------------------------

### Configure persistent minimum age verification

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/update.md

Set the always property to true in .pinact.yml to ensure current versions are verified against the minimum age on every run.

```yaml
min_age:
  value: 7
  always: true # default is false
```

--------------------------------

### GHES configuration in .pinact.yaml

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/specs/839/README.md

Defines the GHES API URL and fallback behavior in the configuration file. The api_url is optional and /api/v3/ is appended if not present. The fallback option defaults to false.

```yaml
ghes:
  api_url: https://ghes.example.com  # /api/v3/ is appended if not present
  fallback: false  # Whether to fallback to github.com (default: false)
```

--------------------------------

### Configure YAML language server for main branch

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/config.md

Add this comment to your YAML file to enable schema validation using the main branch schema.

```yaml
# yaml-language-server: $schema=https://raw.githubusercontent.com/suzuki-shunsuke/pinact/main/json-schema/pinact.json
```

--------------------------------

### Set GHES environment variables

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/specs/839/README.md

Exports the GHES API URL and optional fallback flag as environment variables. PINACT_GHES_API_URL is used if set, otherwise GITHUB_API_URL is considered if it is not https://api.github.com.

```bash
export PINACT_GHES_API_URL="https://ghes.example.com"
export PINACT_GHES_FALLBACK="true"  # optional: enable fallback
```

--------------------------------

### Run pinact with SARIF format

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/sarif.md

Generates output in SARIF format. Note that this flag implies --fix=false, meaning files will not be modified.

```sh
pinact run --format sarif
```

--------------------------------

### Define --min-age CLI flag

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/specs/1265/plan.md

Defines the --min-age integer flag with a validator to ensure non-negative values.

```go
&cli.IntFlag{
    Name:        "min-age",
    Aliases:     []string{"m"},
    Usage:       "Skip versions released within the specified number of days (requires -u)",
    Destination: &flags.MinAge,
    Validator: func(i int) error {
        if i < 0 {
            return errors.New("--min-age must be a non-negative integer")
        }
        return nil
    },
},
```

--------------------------------

### Calculate MinAge cutoff in getLatestVersion

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/specs/1265/plan.md

Calculates the cutoff time based on the MinAge parameter to be used for filtering.

```go
func (c *Controller) getLatestVersion(ctx context.Context, logger *slog.Logger, owner, repo, currentVersion string) (string, error) {
    isStable := isStableVersion(currentVersion)

    // Calculate cutoff once for min-age filtering
    var cutoff time.Time
    if c.param.MinAge > 0 {
        cutoff = time.Now().AddDate(0, 0, -c.param.MinAge)
    }

    lv, err := c.getLatestVersionFromReleases(ctx, logger, owner, repo, isStable, cutoff)
    // ...
    return c.getLatestVersionFromTags(ctx, logger, owner, repo, isStable, cutoff)
}
```

--------------------------------

### Debug Logging

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/AGENTS.md

Enables debug logging by setting PINACT_LOG_LEVEL to debug and running pinact.

```bash
export PINACT_LOG_LEVEL=debug
pinact run
```

--------------------------------

### Update to eligible version

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/specs/1265/test.md

Updates the action to the latest version that meets the min-age requirement.

```sh
# Use small min-age that allows some versions
pinact run -u --min-age 30 --log-level info
```

--------------------------------

### Run pinact with --branch-to-tag

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/branch_to_tag.md

Basic usage of the --branch-to-tag option. The value is evaluated as a regular expression with partial match.

```sh
pinact run --branch-to-tag '<regular expression matching branch name>'
```

--------------------------------

### Replace --review with SARIF output piped to reviewdog

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/upgrade_guide/v4.md

Use this shell command to replace the removed --review option. It runs pinact with SARIF format and pipes the output to reviewdog for GitHub PR review.

```sh
pinact run --format sarif |
  reviewdog -f sarif -name pinact -reporter github-pr-review
```

--------------------------------

### Read diff from stdin

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/diff_file.md

Use `--diff-file -` to read the diff from standard input. This allows piping a diff file directly into pinact.

```sh
cat diff.txt | pinact run --diff-file -
```

--------------------------------

### Upload SARIF to GitHub Code Scanning

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/sarif.md

A GitHub Actions workflow step to generate a SARIF file and upload it to GitHub Code Scanning.

```yaml
- run: pinact run --format sarif > sarif.json || true
- name: Upload SARIF file
  uses: github/codeql-action/upload-sarif@5d4e8d1aca955e8d8589aabd499c5cae939e33c7 # v4.31.9
  with:
    sarif_file: sarif.json
    category: pinact
```

--------------------------------

### Run pinact with exclude regular expressions

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/include_exclude.md

Use `pinact run -e` to skip actions matching the given regular expressions. Multiple `-e` options can be specified. Requires pinact >= v3.4.0.

```sh
pinact run -e "actions/.*" -e "^aquaproj/aqua-installer$"
```

--------------------------------

### Configure YAML language server for specific version

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/config.md

Add this comment to your YAML file to enable schema validation using a specific versioned schema.

```yaml
# yaml-language-server: $schema=https://raw.githubusercontent.com/suzuki-shunsuke/pinact/v1.1.2/json-schema/pinact.json
```

--------------------------------

### GHES environment variables

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/ghes.md

Configure GHES using environment variables instead of a configuration file. If GHES_API_URL is not set, GITHUB_API_URL will be used instead. This is convenient when running on GitHub Actions hosted on GHES.

```sh
export GHES_API_URL=https://ghes.example.com
export PINACT_GHES_FALLBACK=true
```

--------------------------------

### Configure Action Rules

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/config.md

Overrides per-action settings based on expression conditions. Rules are evaluated in order, and later rules override earlier ones for specific fields.

```yaml
rules:
  # Skip actions whose ref is a branch name in our own repos.
  - ignore: true
    conditions:
      - expr: |
          ActionRepoOwner == "suzuki-shunsuke" && ActionVersion == "main"
  # Lower the min-age threshold for trusted actions.
  - min_age: 0
    conditions:
      - expr: |
          ActionRepoFullName == "actions/checkout"
```

--------------------------------

### Output embedded JSON schema

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/config.md

Use the json-schema command to output the schema embedded in the binary.

```sh
pinact json-schema
```

--------------------------------

### No update when all versions are within min-age

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/specs/1265/test.md

Ensures no changes occur if all available versions are newer than the specified min-age.

```sh
# Test with a very new action or large min-age
pinact run -u --min-age 9999
```

--------------------------------

### Discouraged: Pin GitHub Action to mutable tag (v3)

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/README.md

This format uses a mutable tag, which is not recommended because tags can be changed, posing a security risk.

```yaml
uses: actions/cache@v3
```

--------------------------------

### YAML: .pinact.yaml rule to ignore untagged SHA

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/codes/005.md

Configuration in `.pinact.yaml` to ignore a specific action with an untagged SHA. The matched action is skipped entirely, including this check.

```yaml
rules:
  - ignore: true
    conditions:
      - expr: |
          ActionName == "owner/repo" && ActionVersion == "e7500cdc5165d144721128822d9018f7be4eb43e"
```

--------------------------------

### Automatic correction of version annotation in pinact v4.0.0+

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/codes/001.md

In pinact v4.0.0 and newer, the --verify option automatically detects and corrects the version comment to match the actual SHA.

```console
$ pinact run --verify testdata/bar.yaml
WARN[0000] version annotation mismatch detected, correcting comment program=pinact version="" workflow_file=testdata/bar.yaml line_number=15 line="      - uses: actions/checkout@ee0669bd1cc54295c223e0bb666b733df41de1c5 # v3.5.1" action=actions/checkout@ee0669bd1cc54295c223e0bb666b733df41de1c5 action=actions/checkout action_version=ee0669bd1cc54295c223e0bb666b733df41de1c5 version_annotation=v3.5.1 commit_hash_of_version_annotation=83b7061638ee4956cf7545a6f7efe594e5ad0247 correct_version=v2.7.0 help_docs=https://github.com/suzuki-shunsuke/pinact/blob/main/docs/codes/001.md
```

--------------------------------

### pinact .pinact.yaml version field

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/codes/002.md

Required version field in .pinact.yaml as of pinact v3. Use the latest version as much as possible.

```yaml
version: 3
```

--------------------------------

### Validate --min-age flag dependency

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/specs/1265/plan.md

Ensures that the --min-age flag is only used in conjunction with the --update flag.

```go
if flags.MinAge > 0 && !flags.Update {
    return errors.New("--min-age requires --update (-u) flag")
}
```
Tokens:
Raw