### GHES Token Setup for Fallback Example

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

Sets up the necessary GitHub access tokens for GHES and github.com when using the fallback feature. GHES_TOKEN is for the GHES instance, and GITHUB_TOKEN is for github.com.

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

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

### Add Scoop bucket and install pinact

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

Install pinact using Scoop. First, add the repository containing the pinact scoop manifest, then install the package.

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

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

### GHES Token Setup Example (without fallback)

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

Sets up the GHES token for accessing the GitHub Enterprise Server instance when fallback is disabled. This token is used to authenticate requests to the GHES API.

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

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

### Build pinact from source using Go

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

Build and install the pinact executable from its source code using the Go toolchain. Ensure Go is installed and in your PATH.

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

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

### Install pinact with Homebrew (specific repo)

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

Install pinact using Homebrew by specifying the repository. Use this if the official formula is not yet available or for development versions.

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

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

### Install pinact with aqua

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

Install pinact using the aqua package manager. This command globally installs the tool.

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

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

### CI Workflow Example

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

Example of a GitHub Actions workflow file demonstrating the use of pinact or other actions. It shows how to integrate actions within a CI build job.

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

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

### Pinact Completion Help and Usage

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

Provides help and usage examples for generating shell completion scripts for bash, zsh, fish, and Powershell.

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

USAGE:
   pinact completion [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.


OPTIONS:
   --help, -h  show help

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

```

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

### GHES Configuration File Example (with fallback)

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

Example of a .pinact.yaml file enabling GHES and fallback to github.com. This configuration allows Pinact to search for actions on the specified GHES instance first, then on github.com if not found.

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

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

### Example Pinact Configuration (Schema v3)

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

A comprehensive example of a pinact configuration file using schema version 3. It includes file patterns, ignored actions, GitHub Enterprise Server settings, and custom rules.

```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 mise (formerly direnv). This command globally installs the latest version of pinact.

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

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

### Install GitHub CLI with aqua

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

Installs the GitHub CLI tool using the aqua package manager. This is a prerequisite for some verification steps.

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

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

### Install Development Tools with Aqua

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

Installs development tools, including cmdx, using the aqua CLI. Ensure aqua is installed before running this command.

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

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

### Install pinact with Homebrew

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

Install pinact using the Homebrew package manager. This command adds the official Homebrew Core formula.

```sh
brew install pinact
```

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

### Install Cosign with aqua

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

Installs the Cosign tool using the aqua package manager. Cosign is used for signing and verifying container images and artifacts.

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

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

### Download and verify checksums with Cosign

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

Downloads release assets including checksums and their signatures, then verifies the checksum file's integrity using Cosign. Ensure Cosign is installed.

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

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

### Download and verify artifact with slsa-verifier

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

Downloads a release asset and its provenance data, then verifies the artifact's integrity using slsa-verifier. Ensure slsa-verifier is installed.

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

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

### GHES Configuration File Example

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

Configure GHES settings, including the API URL and fallback behavior, in a YAML configuration file. The configuration file takes precedence over environment variables.

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

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

### GHES Configuration File Example

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

Defines GHES settings in the .pinact.yaml configuration file. The api_url specifies the GHES instance, and fallback enables searching on github.com if an action is not found on GHES.

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

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

### Install slsa-verifier with aqua

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

Installs the slsa-verifier tool using the aqua package manager. This tool is used for verifying software supply chain artifacts.

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

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

### Download and verify asset with GitHub CLI

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

Downloads a specific release asset of pinact and verifies its attestation using GitHub CLI. Requires GitHub CLI to be installed.

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

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

### Validate Configuration with ajv-cli

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

Uses ajv-cli to validate a pinact.yaml file against the JSON schema. Ensure you have ajv-cli installed.

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

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

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

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

Use the --min-age option to filter updates, considering only versions released more than the specified number of days ago. This example shows how to exclude versions released within the past 7 days from updates.

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

```sh
pinact run -u -m 7
```

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

### Generate Diff File in GitHub Actions

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

Example of generating a diff file using pr-unified-diff-action in a GitHub Actions workflow.

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

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

### Example of a non-semver action version

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/why-pinact-not-pin.md

pinact does not pin actions with non-semver versions like 'main'. This is to maintain workflow stability as 'main' branches are not stable and their SHAs change frequently.

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

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

### Example of changing 'main' to the latest semver

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/why-pinact-not-pin.md

pinact refrains from changing a 'main' branch to the latest semver. This is to prevent potential workflow breakage caused by SHA changes, even if the semver version itself is stable.

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

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

### Example of a Version Annotation Mismatch

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

This YAML snippet shows a common scenario where the version annotation (e.g., v3.5.1) does not match the actual commit SHA (e.g., ee0669bd1cc54295c223e0bb666b733df41de1c5) of a GitHub Action.

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

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

### Example of pinning 'main' to a full commit SHA

Source: https://github.com/suzuki-shunsuke/pinact/blob/main/docs/why-pinact-not-pin.md

pinact avoids pinning a 'main' branch to its full commit SHA. This is because such SHAs cannot be updated according to semantic versioning, and tools like Renovate might not safely update them due to the instability of the 'main' branch.

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

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

### Pinact Init Command Help

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

Shows help for the 'pinact init' command, which is used to create a 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]

```

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

### Build the Project

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

Build the pinact project by running the `go build` command on the main application executable located in `cmd/pinact`.

```bash
go build ./cmd/pinact
```

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

### Run All Tests (Alternative)

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

An alternative command to run all tests in the project using `go test ./...`.

```bash
go test ./...
```

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

### Pinact Token Set Help

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

Shows help for the 'pinact token set' command, detailing how to set the GitHub Access token.

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

```

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

### Initialize Configuration File

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

Generates a new configuration file for pinact. You can specify a custom path for the configuration file.

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

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

### Pinact Version Help

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

Shows help 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 CLI Help

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

Displays the main help information for the pinact CLI, including 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.0.0

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

```

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

### Pinact Migrate Command Help

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

Provides help for the 'pinact migrate' command, used for migrating .pinact.yaml files.

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

```

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

### Pinact Run Command Help

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

Displays help for the 'pinact run' command, used for pinning GitHub Actions versions. It details various options for verification, updating, and filtering.

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

```

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

### Pinact Token Help

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

Displays help information for the 'pinact token' command, outlining its purpose and subcommands.

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

```

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

### Project Structure Overview

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

Understand the directory structure of the pinact project, which includes directories for commands, packages, test data, JSON schemas, and scripts.

```bash
pinact/
├── cmd/           # Main applications
├── pkg/           # Go packages
│   ├── cli/       # CLI interface layer
│   ├── config/    # Configuration management
│   ├── controller/# Business logic
│   ├── github/    # GitHub API integration
│   └── util/      # Utility functions
├── testdata/      # Test fixtures
├── json-schema/   # JSON schema definitions
└── scripts/       # Build and utility scripts
```

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

### Configure pinact to Ignore Specific SHAs

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

This YAML configuration for pinact allows you to ignore specific SHA-pinned actions, for example, internal forks or pre-release pins, by defining rules and conditions.

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

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

### Display Cmdx Help

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

Shows available tasks and commands for the cmdx task runner. Use this to understand the project's task structure.

```sh
cmdx help
```

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

### Test Workflow File with --min-age

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

Demonstrates how to test the --min-age option against specific workflow files, including those with actions that have both releases and tags.

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

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

### Run Specific Package Tests

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

Execute tests for a specific package, such as `pkg/controller/run`, using the `go test` command.

```bash
go test ./pkg/controller/run
```

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

### Run Linting with Cmdx

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

Performs linting checks on the codebase. 'cmdx v' runs go vet, and 'cmdx l' runs golangci-lint.

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

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

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

### Run pinact Locally

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

Execute the pinact application locally using `go run` on the main executable in `cmd/pinact`.

```bash
go run ./cmd/pinact run
```

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

### Set GitHub Access Token using Keyring

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

Configure a GitHub Access token using the 'pinact token set' command. The token can be entered interactively or piped via standard input.

```sh
pinact token set
```

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

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

### Create Global Configuration File

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

Creates a global configuration file for pinact. This command respects the PINACT_GLOBAL_CONFIG environment variable for the target path.

```sh
pinact init -g
```

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

### Pinact Token Remove Help

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

Displays help for the 'pinact token remove' command, explaining how to remove the GitHub Access token.

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

```

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

### Valid: --min-age 0

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

Confirms that setting --min-age to 0 works correctly, effectively disabling age-based filtering and allowing all versions.

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

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

### Enable Keyring Token Management

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

Enable the feature for managing GitHub Access tokens using a secret store by setting the PINACT_KEYRING_ENABLED environment variable.

```sh
export PINACT_KEYRING_ENABLED=true
```

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

### Generate Test Coverage Report

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

Generate a test coverage report for the project by running the `coverage.sh` script located in the `scripts/` directory.

```bash
./scripts/coverage.sh
```

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

### Configure Default Minimum Release Age

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

Configures the default minimum release age in days via a configuration file. This setting is used when --verify-min-age is set or .min_age.always is true.

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

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

### Configure YAML Language Server Schema (Main)

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

Instructs the YAML language server to use the pinact schema from the main branch for autocompletion and validation.

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

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

### Using SARIF output with reviewdog for GitHub PR reviews

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

This command demonstrates the recommended approach for integrating pinact's SARIF output with reviewdog to provide GitHub pull request reviews. It pipes the output of `pinact run -format sarif` to `reviewdog` for processing.

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

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

### Run Code Validation (go vet)

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

Always run `go vet ./...` using the `cmdx v` command to check for common Go mistakes before committing changes.

```bash
cmdx v
```

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

### Configure GHES with Environment Variables

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

Set GHES_TOKEN and PINACT_GHES_API_URL to configure pinact for GitHub Enterprise Server. The fallback option can be enabled by setting PINACT_GHES_FALLBACK.

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

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

### Run pinact to Add Version Comment

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

Execute this command to allow pinact to automatically add the correct version comment to SHA-pinned actions if the SHA corresponds to an upstream tag.

```sh
pinact run
```

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

### Set GHES API URL and Fallback via Environment Variables

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

Configure GHES API URL and fallback behavior using environment variables. This is an alternative to using a configuration file.

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

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

### Correct: SHA with Version Comment

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

This YAML snippet demonstrates the correct way to pin a GitHub Action using a full commit SHA, including the required trailing version comment.

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

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

### No Update When All Versions Within --min-age

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

Tests the scenario where all available versions are within the specified --min-age, ensuring no update occurs and the current version is retained.

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

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

### Update to Eligible Version with --min-age

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

Verifies that the tool updates to the latest eligible version when a small --min-age value is set, allowing versions older than the specified duration.

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

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

### Enable Minimum Release Age Verification

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

Enables verification of current action versions against the minimum release age. Pinact will exit with an error if versions do not meet the requirement.

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

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

### Enable Debug Logging

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

Enable debug logging for pinact by setting the `PINACT_LOG_LEVEL` environment variable to `debug` before running the application.

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

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

### Migrate Pinact Configuration

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

Use this command to update your `.pinact.yaml` configuration file to the latest schema version. This is necessary when encountering errors related to an old schema version.

```sh
pinact migrate
```

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

### Run pinact on a specific file

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

This command demonstrates how to run pinact on a specific file, such as README.md, to pin actions within that file. This is useful for pinning actions in non-workflow text files.

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

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

### GHES Configuration via Environment Variables

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

Configures GHES API URL and fallback behavior using environment variables. PINACT_GHES_API_URL or GITHUB_API_URL can set the API endpoint, and PINACT_GHES_FALLBACK controls the fallback mechanism.

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

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

### Pinact Run with --verify (Error Output)

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

This console output demonstrates the error message generated by pinact v0.1.3 when a version annotation mismatch is detected. It highlights the action name, the annotated version, and the actual commit hash, indicating a verification failure.

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

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

### Update actions to latest versions

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

Run pinact with the `-update` flag to automatically update all specified actions to their latest available versions.

```sh
pinact run -update
```

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

### Define --min-age CLI Flag

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

Defines the `--min-age` integer flag for the CLI, including its alias, usage text, destination, and a validator to ensure it's a non-negative integer. Requires the `--update` flag to be used in conjunction.

```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
        },
    },

```

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

### Filter Releases by Published Date

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

Filters GitHub releases to include only those published after a specified cutoff date. Debug logging is added to indicate when a release is skipped due to the min-age constraint.

```go
// cutoff is passed as parameter (zero value means no filtering)
if !cutoff.IsZero() && release.GetPublishedAt().Time.After(cutoff) {
    logger.Debug("skip release due to min-age",
        slog.String("tag", tag),
        slog.Time("published_at", release.GetPublishedAt().Time))
    continue
}

```

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

### Enable ghtkn for GitHub Token Management

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

Enable the use of ghtkn for managing GitHub App User Access Tokens by setting the PINACT_GHTKN environment variable.

```sh
export PINACT_GHTKN=true
```

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

### Pin GitHub Action to Commit Hash

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

This snippet demonstrates how to pin a GitHub Action to a specific commit hash. This is the recommended practice for immutable releases and security hardening.

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

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

### Generate JSON Schema

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

Generate the JSON schema for the project's configuration by running the `cmdx js` command.

```bash
cmdx js
```

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

### Set Minimum Release Age (Days)

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

Sets a minimum release age in days for actions. Pinact will only consider versions released on or after this age.

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

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

### Output SARIF and Fix Files

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

Outputs results in SARIF format while also enabling file modifications. This allows for both analysis and automatic fixing of issues identified by pinact.

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

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

### Set GHES Access Token

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

Set a GitHub Access Token for GHES using environment variables. The order of precedence is PINACT_GHES_TOKEN, GHES_TOKEN, GITHUB_TOKEN_ENTERPRISE, and GITHUB_ENTERPRISE_TOKEN.

```shell
export GHES_TOKEN=xxx
```

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

### Run Tests with Cmdx

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

Executes tests using the cmdx task runner. This is a primary command for verifying code changes.

```sh
cmdx t
```

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

### Configure YAML Language Server Schema (Pinned Version)

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

Instructs the YAML language server to use a specific version of the pinact schema for autocompletion and validation.

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

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

### Pinact Run with --verify (Corrected Output)

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

This console output shows how pinact v4.0.0 automatically corrects a version annotation mismatch. It logs a warning indicating the detection and correction of the comment to match the actual SHA, providing details about the action and the corrected version.

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

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

### Specify Target Files with Glob Patterns

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

Define the files to be processed by pinact using glob patterns. Paths are relative to the configuration file.

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

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

### Pin Specific Branches to Latest Tags

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

Allows pinning specific branches by converting them to their latest stable tags. This option takes a regular expression to match branch names and respects the --min-age setting.

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

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

### Always Verify Minimum Release Age

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

Configures the pinact tool to always verify the minimum release age, even if not explicitly requested via command-line flags. This ensures that all actions are checked against the set minimum age.

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

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

### Error: --min-age without -u

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

Tests that the --min-age flag requires the --update (-u) flag to be present. This ensures proper usage of the filtering mechanism.

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

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

### Error: Negative --min-age

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

Validates that the --min-age flag rejects negative integer values, enforcing non-negative input for age filtering.

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

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

### Commit Fetch Failure Warning

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

Tests the handling of commit fetch failures for tags, ensuring a warning is logged and the tag is skipped due to the inability to check its commit.

```sh
pinact run -u --min-age 7 --log-level warn
```

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

### Configure GHES on GitHub Actions with GITHUB_API_URL

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, making PINACT_GHES_API_URL unnecessary. Ensure GHES_TOKEN is exported.

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

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

### Ignore Actions by Name and Ref Regex

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

Specify actions and reusable workflows to be ignored by pinact using regular expressions for both name and ref. Note that regex must match exactly.

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

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

### Define Rules to Override Action Settings

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

Configure rules to conditionally override per-action settings like ignore or min_age. Rules are evaluated in order, with later rules overriding earlier ones for specified 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"
```

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

### Verify Version Comments

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

Enables verification of version comments. This option is used to ensure that version comments meet certain criteria, potentially for security or consistency.

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

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

### Check if actions are pinned without editing files

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

Use the `-check` flag or `-fix=false` to have pinact verify if actions are pinned without modifying any files. This is useful for validation purposes.

```sh
pinact run -check
```

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

### Include Specific Actions with Regex

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

Filters actions to include only those matching the provided regular expression. This is useful for targeting specific actions for updates or checks.

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

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

### Pin Multiple Specific Branches

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

Specifies multiple branches to be pinned to their latest stable tags using regular expressions. This allows for granular control over which branches are pinned.

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

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

### Output Results in SARIF Format

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

Outputs the pinact results in the SARIF format, which is compatible with tools like reviewdog and GitHub SARIF Code Scanning. This format is read-only and does not modify files.

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

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

### Skip Recent Releases with --min-age

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

Tests skipping recently released versions using a large --min-age value. This verifies the cooldown mechanism for GitHub Releases.

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

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

### Pin Only Changed Lines

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

Use the -diff-file option to pin only changed lines. The diff.txt file must be in the unified diff format.

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

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

### Validate --min-age Flag Combination

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

Ensures that the `--min-age` flag is only used when the `--update` flag is also provided. This validation is performed within the `action()` method of the CLI command.

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

```

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

### Offline check for SHA pinning

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

The `-no-api` flag enables an offline check that only verifies the 40-character SHA syntax without making GitHub API calls. This cannot pin actions as it doesn't fetch versions or SHAs.

```sh
pinact run -fix=false -no-api
```

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

### Update GitHub Actions Versions

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

This diff shows the changes when updating GitHub Actions to specific versions. It highlights the SHA updates for actions like 'actions/checkout', 'actions/setup-go', 'actions/cache', and a reusable workflow.

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