### Install ghalint with Go

Source: https://context7.com/suzuki-shunsuke/ghalint/llms.txt

Install ghalint using the Go toolchain.

```bash
# Go install
go install github.com/suzuki-shunsuke/ghalint/cmd/ghalint@latest
```

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

### Install ghalint with Homebrew

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/install.md

Use Homebrew to install ghalint. Ensure Homebrew is installed on your system.

```sh
brew install ghalint
```

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

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

### Install ghalint with mise

Source: https://context7.com/suzuki-shunsuke/ghalint/llms.txt

Install ghalint using the mise version manager.

```bash
# mise
mise use -g ghalint@latest
```

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

### Install ghalint with Homebrew

Source: https://context7.com/suzuki-shunsuke/ghalint/llms.txt

Install ghalint using the Homebrew package manager.

```bash
# Homebrew
brew install suzuki-shunsuke/ghalint/ghalint
```

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

### Install ghalint with Scoop

Source: https://context7.com/suzuki-shunsuke/ghalint/llms.txt

Install ghalint on Windows using the Scoop package manager. Ensure you add the necessary bucket first.

```bash
# Scoop (Windows)
scoop bucket add suzuki-shunsuke https://github.com/suzuki-shunsuke/scoop-bucket
scoop install ghalint
```

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

### Install ghalint with Scoop

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/install.md

Install ghalint using Scoop. This requires adding the Suzuki-Shunsuke scoop bucket first.

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

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

### Install ghalint with aqua

Source: https://context7.com/suzuki-shunsuke/ghalint/llms.txt

Install ghalint using the aqua package manager.

```bash
# aqua
aqua g -i suzuki-shunsuke/ghalint
```

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

### Build ghalint from source

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/install.md

Build an executable binary for ghalint from its source code using Go. Ensure Go is installed and configured.

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

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

### Install ghalint with aqua

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/install.md

Install ghalint using the aqua package manager. This command fetches and installs the latest version.

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

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

### Install ghalint with mise

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/install.md

Install ghalint globally using mise. This command ensures the latest version is available.

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

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

### ghalint configuration file example

Source: https://context7.com/suzuki-shunsuke/ghalint/llms.txt

Example `.ghalint.yaml` configuration file demonstrating how to exclude specific policy violations based on policy name, file path, job name, or action name.

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

excluds:
  # Exclude deny_inherit_secrets for a specific job
  - policy_name: deny_inherit_secrets
    workflow_file_path: .github/workflows/actionlint.yaml
    job_name: actionlint

  # Exclude job_secrets for a specific job
  - policy_name: job_secrets
    workflow_file_path: .github/workflows/actionlint.yaml
    job_name: actionlint

  # Exclude action_ref_should_be_full_length_commit_sha for specific actions
  - policy_name: action_ref_should_be_full_length_commit_sha
    action_name: slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml

  # Use glob patterns for action names (v1.1.0+)
  - policy_name: action_ref_should_be_full_length_commit_sha
    action_name: suzuki-shunsuke/tfaction/*

  # Exclude github_app_should_limit_repositories for a specific step
  - policy_name: github_app_should_limit_repositories
    workflow_file_path: .github/workflows/test.yaml
    job_name: test
    step_id: create_token
```

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

### ghalint run example output

Source: https://context7.com/suzuki-shunsuke/ghalint/llms.txt

Example output from `ghalint run` when policy violations are detected. It shows error messages, policy names, and file paths.

```bash
# Example output when violations are found
# ERRO[0000] read a workflow file                          error="parse a workflow file as YAML: yaml: line 10: could not find expected ':'" program=ghalint version= workflow_file_path=.github/workflows/release.yaml
# ERRO[0000] github.token should not be set to workflow's env  env_name=GITHUB_TOKEN policy_name=workflow_secrets program=ghalint version= workflow_file_path=.github/workflows/test.yaml
# ERRO[0000] secret should not be set to workflow's env    env_name=DATADOG_API_KEY policy_name=workflow_secrets program=ghalint version= workflow_file_path=.github/workflows/test.yaml
```

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

### ghalint validate-input example output

Source: https://context7.com/suzuki-shunsuke/ghalint/llms.txt

Example output from `ghalint exp validate-input` when an invalid input key is detected. It specifies the action, job, and policy violation.

```bash
# Example output
# ERRO[0000] invalid input key                             action=suzuki-shunsuke/actionlint-action@c8d3c0dcc9152f1d1c7d4a38cbf4953c3a55953d input_key=actionlint_option job_key=actionlint program=ghalint required_inputs= valid_inputs="sparse-checkout, actionlint_options" version=v1.0.0-local workflow_file_path=.github/workflows/actionlint.yaml
```

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

### Job with Empty Permissions

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/policies/001.md

This example demonstrates setting an empty `permissions: {}` for a job. This explicitly grants no special permissions to the job, enforcing least privilege.

```yaml
jobs:
  foo:
    runs-on: ubuntu-latest
    permissions: {} # Set permissions
    steps:
      - run: echo hello
```

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

### Integrate ghalint into GitHub Actions CI Pipeline

Source: https://context7.com/suzuki-shunsuke/ghalint/llms.txt

Add ghalint to your CI workflow to automatically check for security policies on pull requests. This example demonstrates checkout, aqua installation, and ghalint execution.

```yaml
name: ghalint
on:
  pull_request:
    paths:
      - '.github/workflows/**'
      - 'action.yaml'
      - 'action.yml'
      - '.ghalint.yaml'

jobs:
  ghalint:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions: {}
    steps:
      - uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3
        with:
          persist-credentials: "false"
      - uses: aquaproj/aqua-installer@928a2f6f06f9af4e1de7f29ed2be4e288f72b9ee # v3.0.1
        with:
          aqua_version: v2.29.0
      - run: aqua g -i suzuki-shunsuke/ghalint
      - run: ghalint run
        env:
          GHALINT_LOG_COLOR: always
```

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

### Download asset with slsa-verifier

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/install.md

Download a release asset and its provenance data using the GitHub CLI for verification with slsa-verifier. Ensure you have the GitHub CLI installed.

```sh
version=v1.2.0
asset=ghalint_darwin_arm64.tar.gz
gh release download -R suzuki-shunsuke/ghalint "$version" -p "$asset" -p multiple.intoto.jsonl
```

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

### GitHub Actions Step With Shell

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/policies/011.md

This example demonstrates a valid GitHub Actions step that includes both `run` and `shell` properties. Specifying `shell: bash` ensures the command is executed with Bash.

```yaml
- run: echo hello
  shell: bash
```

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

### Correct Job Secret Exposure

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/policies/006.md

This example demonstrates the correct way to handle secrets by exposing GITHUB_TOKEN only within the specific step that needs it. This limits the scope of the secret's exposure.

```yaml
jobs:
  foo:
    runs-on: ubuntu-latest
    permissions:
      issues: write
    steps:
      - run: echo foo
      - run: gh label create bug
        env:
          GITHUB_TOKEN: ${{github.token}} # secret is set in step
```

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

### GitHub Actions Step Without Shell

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/policies/011.md

This example shows a GitHub Actions step that uses the `run` property without explicitly defining `shell`. This configuration is invalid.

```yaml
- run: echo hello
```

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

### Configuration to Exclude Policy

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/policies/004.md

This example shows how to configure `ghalint.yaml` to exclude the `deny_inherit_secrets` policy for specific workflow files and job names.

```yaml
excludes:
  - policy_name: deny_inherit_secrets
    workflow_file_path: .github/workflows/actionlint.yaml
    job_name: actionlint
```

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

### Get ghalint version

Source: https://context7.com/suzuki-shunsuke/ghalint/llms.txt

Display the current version of the ghalint tool. Supports both plain text and JSON output formats.

```bash
# Text output
ghalint version

# JSON output
ghalint version --json
```

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

### Incorrect: Using 'read-all' permission

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/policies/002.md

This example demonstrates the incorrect usage of the 'read-all' permission in a GitHub Actions workflow. Avoid this configuration.

```yaml
name: test
jobs:
  foo:
    runs-on: ubuntu-latest
    permissions: read-all # Don't use read-all
    steps:
      - run: echo foo
```

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

### ghalint Error Output Examples

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

Example output from ghalint showing various errors encountered during workflow validation, including YAML parsing issues and security policy violations related to environment variables and secrets.

```console
ERRO[0000] read a workflow file                          error="parse a workflow file as YAML: yaml: line 10: could not find expected ":"" program=ghalint version= workflow_file_path=.github/workflows/release.yaml
ERRO[0000] github.token should not be set to workflow's env  env_name=GITHUB_TOKEN policy_name=workflow_secrets program=ghalint version= workflow_file_path=.github/workflows/test.yaml
ERRO[0000] secret should not be set to workflow's env    env_name=DATADOG_API_KEY policy_name=workflow_secrets program=ghalint version= workflow_file_path=.github/workflows/test.yaml
```

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

### Correct Use of Secrets: Explicitly Pass

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/policies/004.md

This example shows the recommended way to pass secrets by explicitly listing only the required ones. This improves security by limiting secret exposure.

```yaml
jobs:
  release:
    uses: suzuki-shunsuke/go-release-workflow/.github/workflows/release.yaml@v0.4.4
    secrets: # Only required secrets should be passed
      gh_app_id: ${{ secrets.APP_ID }}
      gh_app_private_key: ${{ secrets.APP_PRIVATE_KEY }}
```

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

### Correct: Specifying granular read permission

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/policies/002.md

This example shows the recommended way to grant read permissions for contents in a GitHub Actions workflow. Specify 'contents: read' for least privilege.

```yaml
name: test
jobs:
  foo:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - run: echo foo
```

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

### Correct Workflow Secrets Configuration

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/policies/005.md

This example demonstrates the correct way to set secrets by exposing them only to the specific jobs or steps that require them. This improves security by limiting the scope of secret exposure.

```yaml
name: test
jobs:
  foo:
    runs-on: ubuntu-latest
    permissions: {}
    env:
      GITHUB_TOKEN: ${{github.token}}
    steps:
      - run: echo foo
  bar:
    runs-on: ubuntu-latest
    permissions: {}
    env:
      DATADOG_API_KEY: ${{secrets.DATADOG_API_KEY}}
    steps:
      - run: echo bar
```

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

### Correct Action Reference with Full Commit SHA

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/policies/008.md

This is an example of a correctly pinned action reference using a full-length commit SHA. This ensures the action is immutable and mitigates security risks.

```yaml
actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3
```

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

### Recommended Specific Image Tag in GitHub Actions Job

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/policies/007.md

This example shows the recommended practice of using a specific version tag for a container image in a GitHub Actions job. Pinning to a specific tag or hash ensures build reproducibility.

```yaml
jobs:
  container-test-job:
    runs-on: ubuntu-latest
    container:
      image: node:10 # Ideally, hash is best
```

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

### Avoid 'write-all' permission in GitHub Actions workflow

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/policies/003.md

This example demonstrates the incorrect use of 'write-all' permission. Avoid this configuration in your GitHub Actions workflows.

```yaml
name: test
jobs:
  foo:
    runs-on: ubuntu-latest
    permissions: write-all # Don't use write-all
    steps:
      - run: echo foo
```

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

### Incorrect Use of Secrets: Inherit

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/policies/004.md

This example demonstrates the incorrect usage of `secrets: inherit`, which should be avoided. It exposes all available secrets to the job.

```yaml
jobs:
  release:
    uses: suzuki-shunsuke/go-release-workflow/.github/workflows/release.yaml@v0.4.4
    secrets: inherit # `inherit` should not be used
```

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

### Incorrect Action Reference

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/policies/008.md

This is an example of an action reference that does not use a full-length commit SHA. It uses a tag, which can be mutable and pose a security risk.

```yaml
actions/checkout@v3
```

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

### Exclude checkout_persist_credentials_should_be_false policy

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/policies/013.md

Example of a `ghalint.yaml` configuration file to exclude the `checkout_persist_credentials_should_be_false` policy for a specific job within a workflow. This is useful when persisting tokens is intentionally required for a particular job.

```yaml
excludes:
  - policy_name: checkout_persist_credentials_should_be_false
    workflow_file_path: .github/workflows/actionlint.yaml
    job_name: actionlint
```

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

### Grant specific write permission in GitHub Actions workflow

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/policies/003.md

This example shows the recommended way to grant permissions by specifying 'contents: write'. Always grant only the necessary permissions for your workflow.

```yaml
name: test
jobs:
  foo:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - run: echo foo
```

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

### ghalint Configuration Error Example

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

This console output shows a FATAL error from ghalint indicating a failure to parse the configuration file as YAML due to an unexpected end of file. This typically happens when the YAML file is empty or contains only commented-out lines.

```console
$ ghalint run
FATA[0000] ghalint failed                                config_file=ghalint.yaml error="read a configuration file: parse configuration file as YAML: EOF"
```

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

### Incorrect Job Secret Exposure

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/policies/006.md

This example shows a job where a secret (GITHUB_TOKEN) is exposed as an environment variable at the job level, which is a security risk. Secrets should be limited to the steps that require them.

```yaml
jobs:
  foo:
    runs-on: ubuntu-latest
    permissions:
      issues: write
    env:
      GITHUB_TOKEN: ${{github.token}} # secret is set in job
    steps:
      - run: echo foo
      - run: gh label create bug
```

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

### Job without Permissions Field

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/policies/001.md

This example shows a job that does not explicitly define the `permissions` field. This can lead to default permissions being applied, which may not adhere to the principle of least privilege.

```yaml
jobs:
  foo: # The job doesn't have `permissions`
    runs-on: ubuntu-latest
    steps:
      - run: echo hello
```

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

### Incorrect Workflow Secrets Configuration

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/policies/005.md

This example shows an incorrect way to set secrets at the workflow level, which is discouraged. Secrets should not be exposed to all jobs via the workflow's environment variables.

```yaml
name: test
env:
  GITHUB_TOKEN: ${{github.token}} # The secret should not be set to workflow's environment variables 
  DATADOG_API_KEY: ${{secrets.DATADOG_API_KEY}} # The secret should not be set to workflow's environment variables 
jobs:
  foo:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - run: echo foo
  bar:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - run: echo bar
```

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

### Disallowed 'latest' Image Tag in GitHub Actions Job

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/policies/007.md

This example demonstrates the incorrect usage of the 'latest' tag for a container image in a GitHub Actions job. Avoid using 'latest' as it can cause build inconsistencies.

```yaml
jobs:
  container-test-job:
    runs-on: ubuntu-latest
    container:
      image: node:latest # latest tags should not be used
```

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

### ghalint experiment Command Help

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

Provides help for the 'ghalint experiment' command, which includes experimental features. Use with caution as these commands may change.

```console
$ ghalint experiment --help
NAME:
   ghalint experiment - experimental commands

USAGE:
   ghalint experiment [command [command options]]

DESCRIPTION:
   experimental commands. These commands are not stable and may change in the future without major updates.

COMMANDS:
   validate-input  validate action inputs

OPTIONS:
   --help, -h  show help

```

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

### ghalint run-action Command Help

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

Displays the help message for the 'ghalint run-action' command, used for linting GitHub Actions.

```console
$ ghalint run-action --help
NAME:
   ghalint run-action - lint actions

USAGE:
   ghalint run-action [arguments...]

OPTIONS:
   --help, -h  show help

```

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

### ghalint version Command Help

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

Displays help for the 'ghalint version' command, which shows the tool's current version. Includes an option to output in JSON format.

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

USAGE:
   ghalint version

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

```

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

### ghalint Global Help

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

Displays the main help message for the ghalint CLI, outlining its usage, version, commands, and global options.

```console
$ ghalint --help
NAME:
   ghalint - GitHub Actions linter

USAGE:
   ghalint [global options] [command [command options]]

VERSION:
   1.5.5

COMMANDS:
   run              lint GitHub Actions Workflows
   run-action, act  lint actions
   experiment, exp  experimental commands
   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-color string          log color [$GHALINT_LOG_COLOR]
   --log-level string          log level [$GHALINT_LOG_LEVEL]
   --config string, -c string  configuration file path [$GHALINT_CONFIG]
   --help, -h                  show help
   --version, -v               print the version

```

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

### ghalint run-action Command

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

Lints actions.

```APIDOC
## ghalint run-action

### Description
Lints actions.

### Method
CLI Command

### Endpoint
ghalint run-action [arguments...]

### Parameters
#### Query Parameters
- **--help** (boolean) - Optional - Show help.
- **-h** (boolean) - Optional - Show help.
```

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

### ghalint experiment validate-input Help

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

Shows help for the 'ghalint experiment validate-input' command, used to validate action inputs.

```console
$ experiment validate-input --help
NAME:
   ghalint experiment validate-input - validate action inputs

USAGE:
   ghalint experiment validate-input

DESCRIPTION:
   validate action inputs

OPTIONS:
   --help, -h  show help

```

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

### Download assets with Cosign

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/install.md

Download release assets, checksums, and signatures using the GitHub CLI for verification with Cosign. This prepares for signature verification.

```sh
version=v1.2.0
checksum_file="ghalint_${version#v}_checksums.txt"
asset=ghalint_darwin_arm64.tar.gz
gh release download "$version" \
  -R suzuki-shunsuke/ghalint \
  -p "$asset" \
  -p "$checksum_file" \
  -p "${checksum_file}.pem" \
  -p "${checksum_file}.sig"
```

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

### ghalint run Command Help

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

Shows the help message for the 'ghalint run' command, which is used to lint GitHub Actions workflows.

```console
$ ghalint run --help
NAME:
   ghalint run - lint GitHub Actions Workflows

USAGE:
   ghalint run

OPTIONS:
   --help, -h  show help

```

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

### Run ghalint

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

Execute ghalint to validate all workflow files in the repository root directory. It checks for security policy compliance.

```console
$ ghalint run
```

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

### ghalint run Command

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

Lints GitHub Actions Workflows.

```APIDOC
## ghalint run

### Description
Lints GitHub Actions Workflows.

### Method
CLI Command

### Endpoint
ghalint run

### Parameters
#### Query Parameters
- **--help** (boolean) - Optional - Show help.
- **-h** (boolean) - Optional - Show help.
```

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

### ghalint completion Command Help

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

Provides help for the 'ghalint completion' command, which generates shell completion scripts for bash, zsh, fish, and Powershell.

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

USAGE:
   ghalint completion

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

   # .bashrc
   source <(ghalint completion bash)

   # .zshrc
   source <(ghalint completion zsh)

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

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


OPTIONS:
   --help, -h  show help

```

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

### Set Ghalint Configuration Path

Source: https://context7.com/suzuki-shunsuke/ghalint/llms.txt

Configure the path to the Ghalint configuration file using the GHALINT_CONFIG environment variable.

```bash
export GHALINT_CONFIG=/path/to/ghalint.yaml
```

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

### Enable Colored Output in CI

Source: https://context7.com/suzuki-shunsuke/ghalint/llms.txt

Force colored output in continuous integration environments using the GHALINT_LOG_COLOR environment variable.

```bash
export GHALINT_LOG_COLOR=always
```

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

### Run ghalint on action.yaml files

Source: https://context7.com/suzuki-shunsuke/ghalint/llms.txt

Lint `action.yaml` files using `ghalint run-action` or its alias `act`. This command applies action-specific security policies.

```bash
# Lint all action.yaml files in current directory
ghalint run-action

# Using the alias
ghalint act

# Lint specific action files
ghalint act foo/action.yaml bar/action.yml
```

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

### Specify configuration file with ghalint

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

Use the `-config` option or `GHALINT_CONFIG` environment variable to specify a custom configuration file.

```sh
ghalint -c foo.yaml run
```

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

### Verify asset with slsa-verifier

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/install.md

Verify a downloaded artifact using slsa-verifier against its provenance data. This ensures the artifact was built securely.

```sh
version=v1.2.0
asset=ghalint_darwin_arm64.tar.gz
slsa-verifier verify-artifact "$asset" \
  --provenance-path multiple.intoto.jsonl \
  --source-uri github.com/suzuki-shunsuke/ghalint \
  --source-tag "$version"
```

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

### Checkout with persist-credentials not set or true

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/policies/013.md

Demonstrates incorrect configurations where `persist-credentials` is either not set (defaults to true) or explicitly set to `true`. This can lead to security risks by allowing subsequent steps to access the token.

```yaml
jobs:
  foo:
    runs-on: ubuntu-latest
    steps:
      # persist-credentials is not set
      - uses: actions/checkout@v4

  bar:
    runs-on: ubuntu-latest
    steps:
      # persist-credentials is true
      - uses: actions/checkout@v4
        with:
          persist-credentials: "true"
```

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

### Scope actions/create-github-app-token to specific repositories

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/policies/009.md

Configure actions/create-github-app-token to grant access to a comma-separated list of repositories. If `owner` and `repositories` are omitted, access is limited to the current repository.

```yaml
- uses: actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547 # v1.12.0
  with:
    app-id: ${{vars.APP_ID}}
    private-key: ${{secrets.PRIVATE_KEY}}
    owner: ${{github.repository_owner}}
    repositories: "repo1,repo2"
    permission-issues: write
```

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

### Manage ghalint token keyring

Source: https://context7.com/suzuki-shunsuke/ghalint/llms.txt

Commands to set and remove GitHub tokens from the system keyring for use with experimental features like input validation.

```bash
# Store token in system keyring
ghalint exp token set
ghalint exp token set -stdin

# Remove token from keyring
ghalint exp token rm
```

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

### Run ghalint to validate action.yaml

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

Use this command to validate action files in the current directory. The alias `act` is also available.

```sh
ghalint run-action
```

```sh
ghalint act
```

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

### Download asset with GitHub CLI

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/install.md

Download a specific release asset using the GitHub CLI. This is part of the verification process for downloaded assets.

```sh
version=v1.2.0
asset=ghalint_darwin_arm64.tar.gz
gh release download -R suzuki-shunsuke/ghalint "$version" -p "$asset"
```

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

### Specify Ghalint Config File via CLI

Source: https://context7.com/suzuki-shunsuke/ghalint/llms.txt

Override the default configuration file path using the -c or --config command-line options.

```bash
ghalint -c custom-config.yaml run
```

```bash
ghalint --config custom-config.yaml run
```

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

### ghalint Global Options

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

Global options available for the ghalint CLI that can be used with any command.

```APIDOC
## ghalint Global Options

### Description
Global options that can be applied to any ghalint command.

### Parameters
#### Global Options
- **--log-color** (string) - Optional - Log color. Can also be set via the GHALINT_LOG_COLOR environment variable.
- **--log-level** (string) - Optional - Log level. Can also be set via the GHALINT_LOG_LEVEL environment variable.
- **--config** (string) - Optional - Configuration file path. Alias: -c. Can also be set via the GHALINT_CONFIG environment variable.
- **--help** (boolean) - Optional - Show help. Alias: -h.
- **--version** (boolean) - Optional - Print the version. Alias: -v.
```

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

### Verify asset with GitHub CLI

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/install.md

Verify a downloaded asset using the GitHub CLI's attestation feature. This command checks the integrity and origin of the asset.

```sh
version=v1.2.0
asset=ghalint_darwin_arm64.tar.gz
gh attestation verify "$asset" \
  -R suzuki-shunsuke/ghalint \
  --signer-workflow suzuki-shunsuke/go-release-workflow/.github/workflows/release.yaml
```

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

### ghalint version Command

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

Shows the current version of ghalint.

```APIDOC
## ghalint version

### Description
Show version.

### Method
CLI Command

### Endpoint
ghalint version

### Parameters
#### Query Parameters
- **--json** (boolean) - Optional - Output version in JSON format. Alias: -j.
- **--help** (boolean) - Optional - Show help.
- **-h** (boolean) - Optional - Show help.
```

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

### Specify action file paths for ghalint

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

You can specify individual action file paths to be validated by ghalint.

```sh
ghalint act foo/action.yaml bar/action.yml
```

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

### Run ghalint on workflows

Source: https://context7.com/suzuki-shunsuke/ghalint/llms.txt

Execute ghalint to lint all GitHub Actions workflow files in the `.github/workflows/` directory. This command checks against all workflow policies.

```bash
# Run from repository root directory
ghalint run
```

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

### ghalint completion Command

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

Outputs shell completion script for various shells.

```APIDOC
## ghalint completion

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

### Method
CLI Command

### Endpoint
ghalint completion

### Usage Examples
```bash
# .bashrc
source <(ghalint completion bash)

# .zshrc
source <(ghalint completion zsh)

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

# Powershell
# Output the script to path/to/autocomplete/ghalint.ps1 and run it.
```

### Parameters
#### Query Parameters
- **--help** (boolean) - Optional - Show help.
- **-h** (boolean) - Optional - Show help.
```

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

### Use Full-Length Commit SHA for Action References

Source: https://context7.com/suzuki-shunsuke/ghalint/llms.txt

Reference actions using their full-length commit SHA instead of tags for immutable and reliable releases.

```yaml
# Bad - using tag
- uses: actions/checkout@v3
```

```yaml
# Good - using full commit SHA
- uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3
```

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

### Validate action inputs with ghalint

Source: https://context7.com/suzuki-shunsuke/ghalint/llms.txt

Use the experimental `ghalint exp validate-input` command to validate action and reusable workflow inputs. It requires a GitHub token for metadata retrieval.

```bash
# Set GitHub token for downloading action metadata
export GITHUB_TOKEN="your-token"

# Validate action inputs
ghalint exp validate-input
```

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

### Verify signature with Cosign

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/install.md

Verify the integrity of downloaded assets using Cosign by checking the signature against the checksum file. This ensures the authenticity of the release.

```sh
version=v1.2.0
checksum_file="ghalint_${version#v}_checksums.txt"
asset=ghalint_darwin_arm64.tar.gz
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
```

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

### Use GitHub Token for Experimental Features

Source: https://context7.com/suzuki-shunsuke/ghalint/llms.txt

Provide a GitHub token for accessing experimental features in Ghalint. Both GITHUB_TOKEN and GHALINT_GITHUB_TOKEN can be used.

```bash
export GITHUB_TOKEN="your-token"
```

```bash
export GHALINT_GITHUB_TOKEN="your-token"
```

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

### Validate ghalint.yaml with ajv-cli

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

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

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

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

### Set GitHub Token for ghalint

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

Set a GitHub access token for `ghalint` to use when downloading actions and reusable workflows. The token can be provided via stdin or stored in a secret store.

```sh
ghalint exp token set [-stdin]
```

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

### Checkout with persist-credentials set to false

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/policies/013.md

Shows the correct configuration for `actions/checkout` where `persist-credentials` is explicitly set to `false`. This prevents subsequent steps from accessing the token, enhancing security.

```yaml
jobs:
  foo:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: "false"
```

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

### Specify Shell in Composite Actions

Source: https://context7.com/suzuki-shunsuke/ghalint/llms.txt

When using `run` in composite action `action.yaml` files, always explicitly specify the `shell` to ensure predictable execution.

```yaml
# Bad - no shell specified
runs:
  using: composite
  steps:
    - run: echo hello
```

```yaml
# Good - shell explicitly specified
runs:
  using: composite
  steps:
    - run: echo hello
      shell: bash
```

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

### Generate shell completion scripts

Source: https://context7.com/suzuki-shunsuke/ghalint/llms.txt

Generate shell completion scripts for various shells (bash, zsh, fish) to improve command-line usability.

```bash
# Bash - add to .bashrc
source <(ghalint completion bash)

# Zsh - add to .zshrc
source <(ghalint completion zsh)

# Fish
ghalint completion fish > ~/.config/fish/completions/ghalint.fish
```

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

### Job Timeout Exception: All Steps Have Timeout

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/policies/012.md

This job is an exception to the `timeout-minutes` requirement because all individual steps within the job have their own `timeout-minutes` set. This ensures that even without a job-level timeout, individual steps are constrained.

```yaml
jobs:
  foo: # The job is missing `timeout-minutes`, but it's okay because all steps set timeout-minutes
    runs-on: ubuntu-latest
    steps:
      - run: echo hello
        timeout-minutes: 5
      - run: echo bar
        timeout-minutes: 5
```

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

### Enable Colored Output via CLI

Source: https://context7.com/suzuki-shunsuke/ghalint/llms.txt

Force colored output in the terminal using the --log-color option.

```bash
ghalint --log-color always run
```

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

### ghalint experiment validate-input Command

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

Validates action inputs.

```APIDOC
## ghalint experiment validate-input

### Description
Validate action inputs.

### Method
CLI Command

### Endpoint
ghalint experiment validate-input

### Parameters
#### Query Parameters
- **--help** (boolean) - Optional - Show help.
- **-h** (boolean) - Optional - Show help.
```

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

### ghalint experiment Command

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

Experimental commands that are not stable and may change in the future.

```APIDOC
## ghalint experiment

### Description
Experimental commands. These commands are not stable and may change in the future without major updates.

### Method
CLI Command

### Endpoint
ghalint experiment [command [command options]]

### Commands
- **validate-input** - validate action inputs

### Parameters
#### Query Parameters
- **--help** (boolean) - Optional - Show help.
- **-h** (boolean) - Optional - Show help.
```

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

### Configure ghalint log color in GitHub Actions

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

Set the `GHALINT_LOG_COLOR` environment variable to `always` to enable log color in GitHub Actions.

```yaml
env:
  GHALINT_LOG_COLOR: always
```

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

### Specify GitHub App Token Permissions

Source: https://context7.com/suzuki-shunsuke/ghalint/llms.txt

Explicitly define permissions for GitHub App tokens using `tibdex/github-app-token` or `actions/create-github-app-token` to enforce the principle of least privilege.

```yaml
# Bad - no permissions specified
- uses: tibdex/github-app-token@3beb63f4bd073e61482598c45c71c1019b59b73a # v2.1.0
  with:
    app_id: ${{secrets.APP_ID}}
    private_key: ${{secrets.PRIVATE_KEY}}
    repositories: >-
      ["${{github.event.repository.name}}"]
```

```yaml
# Good - explicit permissions
- uses: tibdex/github-app-token@3beb63f4bd073e61482598c45c71c1019b59b73a # v2.1.0
  with:
    app_id: ${{secrets.APP_ID}}
    private_key: ${{secrets.PRIVATE_KEY}}
    repositories: >-
      ["${{github.event.repository.name}}"]
    permissions: >-
      {
        "contents": "read"
      }
```

```yaml
# Good - using actions/create-github-app-token with permissions
- uses: actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547 # v1.12.0
  with:
    app-id: ${{vars.APP_ID}}
    private-key: ${{secrets.PRIVATE_KEY}}
    permission-issues: write
```

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

### Set `persist-credentials` to `false` for `actions/checkout`

Source: https://context7.com/suzuki-shunsuke/ghalint/llms.txt

Configure the `actions/checkout` action with `persist-credentials: false` to prevent accidental exposure of tokens.

```yaml
# Bad - persist-credentials is true by default
- uses: actions/checkout@v3

# Good - persist-credentials is false
- uses: actions/checkout@v3
  with:
    persist-credentials: false
```

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

### Set Ghalint Log Level via CLI

Source: https://context7.com/suzuki-shunsuke/ghalint/llms.txt

Adjust the log level directly from the command line using the --log-level option.

```bash
ghalint --log-level debug run
```

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

### Validate Workflows with ghalint

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

The command to run ghalint for validating workflow files located in the `.github/workflows/` directory. This command initiates the security check process.

```sh
ghalint run
```

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

### Avoid `write-all` Permission

Source: https://context7.com/suzuki-shunsuke/ghalint/llms.txt

Do not use the `write-all` permission. Grant only the necessary write permissions required for the job's tasks.

```yaml
# Bad - using write-all
jobs:
  foo:
    runs-on: ubuntu-latest
    permissions: write-all
    steps:
      - run: echo foo
```

```yaml
# Good - specific permissions
jobs:
  foo:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - run: echo foo
```

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

### Set Ghalint Log Level

Source: https://context7.com/suzuki-shunsuke/ghalint/llms.txt

Control the verbosity of Ghalint logs by setting the GHALINT_LOG_LEVEL environment variable. Available levels are error, warn, info, and debug.

```bash
export GHALINT_LOG_LEVEL=debug
```

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

### Configure YAML language server schema

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

Specify the ghalint JSON schema for the YAML language server to enable input complementation. You can use a specific version or the main branch.

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

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

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

### Avoid `latest` Tag for Job Container Images

Source: https://context7.com/suzuki-shunsuke/ghalint/llms.txt

Pin job container images to specific versions or commit SHAs instead of using the `latest` tag to ensure reproducible builds.

```yaml
# Bad - using latest tag
jobs:
  container-test-job:
    runs-on: ubuntu-latest
    container:
      image: node:latest
```

```yaml
# Good - pinned version
jobs:
  container-test-job:
    runs-on: ubuntu-latest
    container:
      image: node:18.17.0
```

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

### Exclude github_app_should_limit_repositories policy

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/policies/009.md

Configure ghalint.yaml to exclude the `github_app_should_limit_repositories` policy for specific workflows, jobs, or steps. This requires specifying `policy_name` and at least one of `workflow_file_path`, `job_name`, or `step_id` for workflows, or `action_file_path` and `step_id` for actions.

```yaml
excludes:
  - policy_name: github_app_should_limit_repositories
    workflow_file_path: .github/workflows/actionlint.yaml
    job_name: actionlint
    step_id: create_token
```

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

### Restrict actions/create-github-app-token permissions

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/policies/010.md

Specify 'permission-issues: write' to grant write access only to issues when using actions/create-github-app-token. This ensures the token has the minimum necessary permissions.

```yaml
- uses: actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547 # v1.12.0
  with:
    app-id: ${{vars.APP_ID}}
    private-key: ${{secrets.PRIVATE_KEY}}
    permission-issues: write
```

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

### Avoid `read-all` Permission

Source: https://context7.com/suzuki-shunsuke/ghalint/llms.txt

Refrain from using the broad `read-all` permission; instead, grant only the specific permissions required for the job.

```yaml
# Bad - using read-all
jobs:
  foo:
    runs-on: ubuntu-latest
    permissions: read-all
    steps:
      - run: echo foo
```

```yaml
# Good - specific permissions
jobs:
  foo:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - run: echo foo
```

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

### Job With Timeout Minutes Set

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/policies/012.md

This job configuration correctly includes the `timeout-minutes` property, setting a limit of 30 minutes for the job's execution.

```yaml
jobs:
  foo:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - run: echo hello
```

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

### Limit tibdex/github-app-token to current repository

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/policies/009.md

Use this configuration to scope the token generated by tibdex/github-app-token to the current repository. Ensure the `repositories` input is correctly formatted as a JSON array string.

```yaml
- uses: tibdex/github-app-token@3beb63f4bd073e61482598c45c71c1019b59b73a # v2.1.0
  with:
    app_id: ${{secrets.APP_ID}}
    private_key: ${{secrets.PRIVATE_KEY}}
    repositories: >-
      ["${{github.event.repository.name}}"]
```

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

### Validate Action Inputs

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

Use this command to validate inputs of actions and reusable workflows. It will fail if required inputs are missing or unknown inputs are provided. This command requires a GitHub access token with `contents:read` permission.

```console
$ ghalint exp validate-input
ERRO[0000] invalid input key                             action=suzuki-shunsuke/actionlint-action@c8d3c0dcc9152f1d1c7d4a38cbf4953c3a55953d input_key=actionlint_option job_key=actionlint program=ghalint required_inputs= valid_inputs="sparse-checkout, actionlint_options" version=v1.0.0-local workflow_file_path=.github/workflows/actionlint.yaml
```

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

### Exclude Action with Glob Pattern

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/policies/008.md

This `ghalint.yaml` configuration demonstrates how to exclude actions matching a glob pattern from the `action_ref_should_be_full_length_commit_sha` policy. This allows for more flexible exclusion rules.

```yaml
excludes:
  - policy_name: action_ref_should_be_full_length_commit_sha
    action_name: suzuki-shunsuke/tfaction/* # glob pattern
```

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

### Disable ghalint policies

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

Configure exclusions for specific policies by providing policy name, workflow file path, and job name.

```yaml
excludes:
  - policy_name: deny_inherit_secrets
    workflow_file_path: .github/workflows/actionlint.yaml
    job_name: actionlint
  - policy_name: job_secrets
    workflow_file_path: .github/workflows/actionlint.yaml
    job_name: actionlint
  - policy_name: action_ref_should_be_full_length_commit_sha
    action_name: slsa-framework/slsa-github-generator
  - policy_name: github_app_should_limit_repositories
    workflow_file_path: .github/workflows/test.yaml
    job_name: test
    step_id: create_token
```

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

### Workflow with Empty Permissions and Job Missing Permissions

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/policies/001.md

This scenario illustrates an exception where a job can omit the `permissions` field if the entire workflow has `permissions: {}` defined. This is acceptable for least privilege as the workflow itself has no elevated permissions.

```yaml
permissions: {} # empty permissions
jobs:
  foo: # The job is missing `permissions`, but it's okay because the workflow's `permissions` is empty
    runs-on: ubuntu-latest
    steps:
      - run: echo hello
```

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

### Enforce Least Privilege with Job Permissions

Source: https://context7.com/suzuki-shunsuke/ghalint/llms.txt

Define explicit `permissions` for jobs to enforce the principle of least privilege. An empty `permissions: {}` at the workflow level is also acceptable.

```yaml
# Bad - job doesn't have permissions
jobs:
  foo:
    runs-on: ubuntu-latest
    steps:
      - run: echo hello
```

```yaml
# Good - explicit permissions defined
jobs:
  foo:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - run: echo hello
```

```yaml
# Good - empty permissions at workflow level
permissions: {}
jobs:
  foo:
    runs-on: ubuntu-latest
    steps:
      - run: echo hello
```

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

### Restrict tibdex/github-app-token permissions

Source: https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/policies/010.md

Use the 'permissions' argument to specify read-only access for contents when using tibdex/github-app-token. This limits the scope of the generated token.

```yaml
- uses: tibdex/github-app-token@3beb63f4bd073e61482598c45c71c1019b59b73a # v2.1.0
  with:
    app_id: ${{secrets.APP_ID}}
    private_key: ${{secrets.PRIVATE_KEY}}
    repositories: >-
      ["${{github.event.repository.name}}"]
    permissions: >-
      {
        "contents": "read"
      }
```

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

### Manage Secrets at Step Level, Not Job Level

Source: https://context7.com/suzuki-shunsuke/ghalint/llms.txt

Do not set secrets as environment variables at the job level. Define them at the step level to limit their scope.

```yaml
# Bad - secret at job level
jobs:
  foo:
    runs-on: ubuntu-latest
    permissions:
      issues: write
    env:
      GITHUB_TOKEN: ${{github.token}}
    steps:
      - run: echo foo
      - run: gh label create bug
```

```yaml
# Good - secret at step level
jobs:
  foo:
    runs-on: ubuntu-latest
    permissions:
      issues: write
    steps:
      - run: echo foo
      - run: gh label create bug
        env:
          GITHUB_TOKEN: ${{github.token}}
```