pinact

When GHES is enabled, pinact changes how it searches for GitHub Actions:

1. If fallback: false (Default): pinact searches only the GHES instance. If an action is not found on GHES, an error is returned. This is the most secure mode and aligns with GHES defaults where GitHub Connect is disabled.
2. If fallback: true: pinact first searches the GHES instance. If the GHES API returns a 404 Not Found for the repository, pinact then searches github.com. Results are cached per repository to optimize performance.

Important Constraints:

• No Fallback for Comments: While action searching can fallback to github.com, the creation of PR review comments (via pinact run -review) does not fallback. If GHES is enabled, pinact attempts to post the comment to the GHES instance. If this fails, an error is returned.
• Single Instance: Only one GHES instance is supported at a time.
• Error Handling: If a GHES API request fails with any error other than a 404, pinact will return that error immediately and will not attempt to fallback to github.com.

pinact supports a global configuration file for user-wide defaults which is merged with project-level configuration files (like .pinact.yaml).

Global Configuration Paths

1. $PINACT_GLOBAL_CONFIG (if set)
2. Linux/macOS: $XDG_CONFIG_HOME/pinact/pinact.yaml or ~/.config/pinact/pinact.yaml
3. Windows: %APPDATA%\pinact\pinact.yaml

Merge Behavior

When both exist, they are merged field-by-field. Project values generally take precedence.

Note: Each file's schema version is validated independently. If either file uses an unsupported version, pinact will abort.

To ensure safety and avoid unexpected workflow changes, pinact follows these rules regarding version pinning:

1. Semver versions: If a version follows semantic versioning (e.g., v1), pinact will update it to a newer semver (e.g., v1.1.0) only if the SHA remains identical. If the SHA changes, pinact will not automatically update the version to a different semver.
2. Non-semver versions: Versions that do not follow semver (e.g., main, master, release/v1) are treated as potential branches. pinact does not pin these to a full commit SHA because doing so would prevent future semantic version updates and could break workflows if the branch is unstable.
3. Safety Design: pinact is designed to pin actions without changing the underlying SHA at the moment of pinning, unless it is a safe semver update. It avoids pinning branches to SHAs because branch SHAs are volatile.

To mitigate supply chain risks, you can enforce a "cooldown" period for new action releases. This prevents pinact from automatically adopting very recent releases that haven't been vetted by the community.

Supported methods for setting minimum age:

1. CLI Flag: -min-age <days>
2. Environment Variable: PINACT_MIN_AGE
3. Configuration File: Using .pinact.yml with min_age.value or rule-specific min_age.

Verification Modes:

• During Update: When using -update, pinact filters out versions that don't meet the age requirement. If no suitable version is found, pinact exits with an error.
• Verification Only: Use -verify-min-age to check if your currently pinned versions meet the minimum age requirement without attempting to update them.

# Example .pinact.yml configuration
min_age:
  value: 7
  always: true # Verifies current versions every run

rules:
  - min_age: 0
    conditions:
      - expr: | 
          ActionRepoOwner == "suzuki-shunsuke"

1. GitHub CLI

Install GitHub CLI via aqua, then use gh attestation verify to check the asset against the release workflow.

aqua g -i cli/cli

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

2. slsa-verifier

Install slsa-verifier via aqua, then use verify-artifact with the downloaded provenance file.

aqua g -i slsa-framework/slsa-verifier

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"

3. Cosign

Install cosign via aqua. This method verifies the signature, certificate, and identity, then validates the checksum.

aqua g -i sigstore/cosign

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