ghalint

https://github.com/suzuki-shunsuke/ghalint
Admin
ghalint is a GitHub Actions linter that validates workflows and action.yaml files for security best...
Tokens:33,186
Snippets:271
Trust Score:9.6
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install ghalint with Scoop

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

Add the suzuki-shunsuke bucket and install ghalint using Scoop.

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

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

### Install ghalint with Homebrew

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

Install ghalint using Homebrew. The first command installs the default formula, while the second installs from the suzuki-shunsuke tap.

```sh
brew install ghalint
```

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

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

### Install ghalint with mise

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

Install ghalint globally using mise.

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

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

### Build ghalint from source with Go

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

Build and install ghalint from source using Go's install command.

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

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

### Install Cosign with aqua

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

Install Cosign using aqua, which is required for verifying assets with Cosign.

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

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

### Install slsa-verifier with aqua

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

Install slsa-verifier using aqua, which is required for verifying assets with slsa-verifier.

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

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

### Install ghalint with aqua

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

Install ghalint using aqua, which adds the package to your aqua configuration.

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

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

### Install GitHub CLI with aqua

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

Install GitHub CLI using aqua, which is required for verifying assets via GitHub CLI.

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

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

### deny_job_container_latest_image: failing and passing container image examples

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

The first block shows a failing example that uses the 'latest' tag for the container image, which violates the deny_job_container_latest_image policy. The second block shows a passing example that pins the image to a specific tag (node:10) and notes that a hash is ideal.

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

```

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

```

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

### Compliant example: passing only required secrets

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

Shows the recommended approach: explicitly pass only the required secrets instead of using `secrets: inherit`.

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

```

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

### Compliant example: persist-credentials set to false

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

Shows the correct usage where actions/checkout is configured with persist-credentials: "false" to satisfy the policy.

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

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

### Configuration to ignore deny_inherit_secrets

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

Example ghalint.yaml configuration to exclude the policy for a specific workflow file and job. Requires `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

```

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

### ghalint run command output

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

Example output from running ghalint run, showing three error messages about workflow file parsing failures and security policy violations (workflow_secrets policy) with their corresponding file paths and environment names.

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

```

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

### Valid action ref (full length commit SHA)

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

Example of a valid action ref pinned to a full length commit SHA, with a comment indicating the original tag.

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

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

### Violating example: secrets: inherit

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

Shows a workflow job using `secrets: inherit`, which is disallowed by this policy. The comment marks the violation.

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

```

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

### tibdex/github-app-token without repositories (incorrect)

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

This YAML shows a GitHub Actions step using tibdex/github-app-token without the `repositories` input, which is a violation of this policy. The step lacks repository restriction, so the token has broad access. Use this as a contrast to the correct example below.

```yaml
- uses: tibdex/github-app-token@3beb63f4bd073e61482598c45c71c1019b59b73a # v2.1.0
  with:
    app_id: ${{secrets.APP_ID}}
    private_key: ${{secrets.PRIVATE_KEY}}
```

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

### GitHub Actions workflow with least privilege permissions (valid)

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

Example of a GitHub Actions workflow that grants only the necessary `contents: write` permission instead of `write-all`, following the least privilege principle.

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

```

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

### Invalid action ref (short tag)

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

Example of an action ref that violates the policy because it uses a short tag 'v3' instead of a full length commit SHA.

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

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

### Violating example: persist-credentials not set or true

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

Shows two jobs where actions/checkout is used without setting persist-credentials (defaults to true) or explicitly setting it to "true", which violates the policy.

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

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

### ghalint run error output

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

Example console output showing the ghalint error 'parse a workflow file as YAML: EOF' when running `ghalint run` on an invalid workflow file.

```console
$ ghalint run
ERRO[0000] read a workflow file                          error="parse a workflow file as YAML: EOF" program=ghalint version=0.2.6 workflow_file_path=.github/workflows/test.yaml
```

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

### GitHub Actions workflow with write-all permission (invalid)

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

Example of a GitHub Actions workflow that uses the `write-all` permission, which is not allowed by the `deny_write_all_permission` policy. The comment `# Don't use write-all` marks the offending line.

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

```

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

### Set GHALINT_LOG_COLOR to always for GitHub Actions

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

This YAML example demonstrates setting the GHALINT_LOG_COLOR environment variable to 'always' in a GitHub Actions workflow or configuration file. Enabling color logging is recommended for GitHub Actions, as otherwise logs may appear without color.

```yaml
env:
  GHALINT_LOG_COLOR: always

```

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

### ghalint --help: top-level CLI help

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

Displays the top-level help for ghalint. Enumerates available commands (run, run-action, experiment, version, completion) and global options, including environment variables for log color/level and config path.

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

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

VERSION:
   1.5.6

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 version --help: show version

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

Help for the `version` command. Use `-j` or `--json` to output version information 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 run --help: lint workflows

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

Shows the help for the `run` subcommand, which lints GitHub Actions Workflows. The only option is `--help`.

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

USAGE:
   ghalint run

OPTIONS:
   --help, -h  show help

```

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

### Verify ghalint asset with Cosign

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

Download a release asset and its checksum files, verify the checksum file with Cosign, and then verify the checksums. The version and asset variables are set before the commands.

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

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

### ghalint run-action --help: lint actions

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

Help for the `run-action` (alias `act`) command that lints actions. Accepts arguments.

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

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

OPTIONS:
   --help, -h  show help

```

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

### ghalint experiment --help: experimental commands

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

Help for the `experiment` (alias `exp`) group. Contains the experimental `validate-input` command; these commands may change without major updates.

```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 completion --help: shell completion scripts

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

Help for the `completion` command. Generates shell completion scripts for bash, zsh, fish, or Powershell; source or execute the output as shown.

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

```

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

### Verify ghalint asset with slsa-verifier

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

Download a release asset and its provenance, then verify it with slsa-verifier. The version and asset variables are set before the commands.

```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
slsa-verifier verify-artifact "$asset" \
  --provenance-path multiple.intoto.jsonl \
  --source-uri github.com/suzuki-shunsuke/ghalint \
  --source-tag "$version"
```

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

### ghalint experiment validate-input --help

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

Help for the `experiment validate-input` command. Validates action inputs; no options besides `--help`.

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

```

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

### actions/create-github-app-token with repositories (correct)

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

This YAML shows a GitHub Actions step using actions/create-github-app-token with the `repositories` input set to a comma-separated list of repository names. This is the recommended way to limit the token's scope to specific repositories, which satisfies the policy.

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

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

### Verify ghalint asset with GitHub CLI

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

Download a release asset and verify its attestation using GitHub CLI. The version and asset variables are set before the commands.

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

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

### actions/create-github-app-token scoped to current repository (alternative)

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

This YAML shows an alternative configuration for actions/create-github-app-token where both `owner` and `repositories` are omitted. According to the source, if they are empty, access is scoped to only the current repository, which also satisfies the policy.

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

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

### Specify configuration file with -c option

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

Specifies a configuration file with the -c flag. The environment variable GHALINT_CONFIG also sets the configuration file path.

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

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

### Run ghalint exp validate-input Command

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

This console command shows how to run the experimental 'ghalint exp validate-input' command, which validates inputs of actions and reusable workflows. The output is an error log indicating an invalid input key, with details such as the action, input key, job key, and workflow file path.

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

```

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

### Validate action files with ghalint run-action

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

Runs ghalint to validate action files matching the pattern ^([^/]+/){0,3}action\.ya?ml$ on the current directory.

```sh
ghalint run-action
```

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

### Run ghalint and observe EOF error

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

Running `ghalint run` with an empty or comment-only configuration file produces a fatal error indicating that parsing the YAML configuration file reached EOF.

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

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

### actions/create-github-app-token without repositories (incorrect)

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

This YAML shows a GitHub Actions step using actions/create-github-app-token without the `repositories` input, which is a violation unless the token is scoped to the current repository only. The step uses `owner` and `permission-issues` but no repository restriction.

```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}}
    permission-issues: write
```

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

### Default file patterns validated by ghalint exp validate-input

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

This text block lists the default file patterns that the 'ghalint exp validate-input' command validates. It includes GitHub Actions workflow files in the .github/workflows directory and action files at various directory depths.

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

```

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

### Validate workflows with ghalint run

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

Runs ghalint to validate workflow files matching the pattern ^\.github/workflows/.*\.ya?ml$ on the repository root directory.

```sh
ghalint run
```

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

### Validate configuration with ajv-cli

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

Validates a ghalint configuration file against the JSON Schema using ajv-cli.

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

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

### tibdex/github-app-token with repositories (correct)

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

This YAML shows a GitHub Actions step using tibdex/github-app-token with the `repositories` input to restrict access to the current repository. This is the correct usage that satisfies the policy. The `repositories` input is set to a JSON array containing the current repository name.

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

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

### Exception: all steps set timeout-minutes

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

This YAML shows an exception where the job lacks timeout-minutes but is allowed because every step sets timeout-minutes.

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

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

### Set ghalint token with ghalint exp token set

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

This shell command sets a GitHub access token for use by the 'ghalint exp validate-input' command. The optional '-stdin' flag allows the token to be passed via standard input.

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

```

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

### actions/create-github-app-token: add permission-issues input

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

For actions/create-github-app-token, the first block is non-compliant because it does not set any permission-* input. The second block adds permission-issues: write to limit the token scope. Requires create-github-app-token v1.12.0 or later.

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

```

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

```

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

### Alias act for ghalint run-action

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

Alias for 'ghalint run-action'. Validates action files on the current directory.

```sh
ghalint act
```

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

### Correct: job with empty permissions

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

This YAML shows a job with an empty 'permissions' object, which satisfies the rule. The comment indicates setting permissions.

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

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

### Compliant workflow with secrets at job level

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

Shows a workflow that sets GITHUB_TOKEN and DATADOG_API_KEY in each job's env, which complies with the workflow_secrets policy. Secrets are exposed only to the necessary jobs.

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

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

### Valid job with timeout-minutes set

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

This YAML shows a compliant job that sets timeout-minutes to 30, which is the recommended value.

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

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

### Valid YAML for action_shell_is_required (with shell)

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

An action step that includes 'shell: bash' to satisfy the action_shell_is_required rule when 'run' is present.

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

```

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

### YAML language server schema directive (main)

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

Configures YAML language server for schema validation using the 'main' version of the schema.

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

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

### Exception 2: single job with workflow permissions

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

This YAML shows a workflow with a single job and workflow-level permissions, so the job does not need its own permissions. The comment explains the exception.

```yaml
permissions:
  contents: read
jobs:
  foo: # The job is missing `permissions`, but it's okay because the workflow has permissions and the workflow has only one job.
    runs-on: ubuntu-latest
    steps:
      - run: echo hello
```

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

### Invalid YAML for action_shell_is_required (missing shell)

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

An action step without a shell property that triggers the rule failure because 'shell' is required when 'run' is set.

```yaml
- run: echo hello

```

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

### tibdex/github-app-token: add permissions input

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

For tibdex/github-app-token, the first block is non-compliant because it omits the permissions input. The second block adds a permissions object with contents: read to limit the token scope.

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

```

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

```

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

### Exception 1: workflow-level empty permissions

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

This YAML shows a workflow with empty permissions at the top level, so a job without its own permissions is allowed. The comment explains the exception.

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

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

### Exception: job uses a reusable workflow

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

This YAML shows an exception where a job uses a reusable workflow with 'uses', and timeout-minutes is not available.

```yaml
jobs:
  foo:
    uses: suzuki-shunsuke/renovate-config-validator-workflow/.github/workflows/validate.yaml@v0.2.3
```

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

### Deny read-all permission in GitHub Actions workflow

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

The first block shows the discouraged use of `read-all` permission. The second block shows the recommended approach of granting only necessary permissions, such as `contents: read`.

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

```

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

```

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

### Validate specific action files with ghalint act

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

Specifies custom file paths for action validation using the act alias.

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

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

### Compliant workflow: secret set in step env

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

Shows the correct fix: set the secret in the step's env, limiting exposure to only that step.

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

```

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

### Violating workflow with secrets in workflow-level env

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

Shows a workflow that sets GITHUB_TOKEN and DATADOG_API_KEY in the workflow-level env, which violates the workflow_secrets policy. The secrets should be moved to job or step level.

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

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

### Exclude action from policy in ghalint.yaml

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

Configuration to exclude a specific action from the policy. The action_name is the full path to the reusable workflow. The comment includes an error message from the action indicating it doesn't support pinning.

```yaml
excludes:
  # 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
  - policy_name: action_ref_should_be_full_length_commit_sha
    action_name: slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml
```

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

### Disable policies in ghalint configuration

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

Configuration to disable specific policies. Each entry uses policy_name and optional filters like workflow_file_path, job_name, action_name, and step_id.

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

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

### Exclude actions with glob pattern in ghalint.yaml

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

Configuration to exclude actions matching a glob pattern. As of v1.1.0, action_name supports glob patterns using path.Match syntax.

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

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

### YAML language server schema directive (pinned version)

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

Configures YAML language server for schema validation with a pinned version (v1.2.1).

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

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

### Remove ghalint token with ghalint exp token rm

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

This shell command removes a stored GitHub access token from the secret store using the 'ghalint exp token rm' command. The comment indicates its purpose.

```sh
ghalint exp token rm # Remove a token from secret store

```

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

### Exclusion config for job_secrets policy

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

Configuration to ignore the job_secrets policy for a specific workflow and job. Requires policy_name, workflow_file_path, and job_name.

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

```

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

### Violation: job without permissions

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

This YAML shows a job that lacks the 'permissions' field, which triggers the rule. The job runs on ubuntu-latest and has a simple echo step.

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

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

### Invalid job without timeout-minutes

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

This YAML shows a job that violates the rule because it lacks timeout-minutes. The comment indicates the job doesn't have timeout-minutes.

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

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

### Violating job_secrets: secret set in job env

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

Shows the violation: setting a secret (GITHUB_TOKEN) in the job's env. This exposes the secret to all steps.

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

```
Tokens:
Raw