GitHub

This page covers the GitHub Actions particulars of the Plumber CLI: how to authenticate, the controls that ship for GitHub, the issues they emit, a complete github.controls: configuration block, and the drop-in GitHub Action for automated compliance scanning with SARIF upload. For installation, see the Installation page. For the provider-agnostic command reference, see the main CLI page.

On GitHub Actions, Plumber flags issues like:

• Third-party actions not pinned by commit SHA, the tj-actions / reviewdog supply chain vector (CVE-2025-30066)
• Actions hosted in archived repositories or carrying published GitHub Advisory entries
• Dangerous triggers (pull_request_target, workflow_run) that expose secrets to PR-author code
• Template injection via ${{ github.event.* }} inlined into shell scripts
• Reusable workflows called with secrets: inherit instead of named-secret passing
• Implicit / over-broad permissions: blocks and permissions: write-all grants
• Debug-trace toggles (ACTIONS_STEP_DEBUG, ACTIONS_RUNNER_DEBUG) that leak secrets into job logs
• Docker-in-Docker services and weakened security jobs

Quick Start

Two ways to scan a GitHub repository. Pick the path that matches how you work: Local CLI or GitHub Action.

Run the CLI locally

Best for trying Plumber on one repo, checks before you push, security-team audits, or scanning upstream repos without changing CI.

Installation

Authentication

Pick whichever auth flow fits your environment:

# Option 1: GitHub CLI (recommended for local use)
gh auth login

# Option 2: Fine-grained Personal Access Token
# Settings > Developer settings > Personal access tokens > Fine-grained tokens
#   Repository access: pick the repo(s) to scan
#   Permissions: Contents = Read, Metadata = Read, Administration = Read
export GH_TOKEN=github_pat_xxxx

# Option 3: Classic PAT (broader scope, still works)
# Permissions: `repo` scope (read access to repo + admin metadata)
export GH_TOKEN=ghp_xxxx

If a workflow uses an action hosted in an org with an IP allow list, a runner's GITHUB_TOKEN is blocked when Plumber resolves that action's version for the known-CVE check; Plumber falls back to an anonymous read, and skips the check rather than guessing if that is rate-limited too. To resolve those versions reliably, set PLUMBER_METADATA_TOKEN (or the action's metadata-token input) to a token with public-repository read.

When a token-scoped control cannot fully evaluate, Plumber adds a partialControls entry to report.json so CI gates can tell the difference between "100% compliant" and "100% on what we could see":

"partialControls": [
  {
    "control": "branchMustBeProtected",
    "reason": "Token lacks Administration:Read scope; force-push and code-owner-approval rules (ISSUE-505) not evaluated.",
    "affectedBranches": 1,
    "remediation": "Re-run with a token carrying Administration:Read (fine-grained PAT) or `repo` scope (classic PAT)."
  }
]

When this array is non-empty, at least one control abstained on at least part of its input. Treat the run as suspect rather than trusting the compliance percentage. On a clean run the array is either omitted or empty.

Running a scan

# Local clone (auto-detected from git remote)
plumber analyze

# Upstream-fetch: scan a repo without cloning it
plumber analyze --github-url github.com --project myorg/myrepo

On GitHub Enterprise Server, pass the GHES host via --github-url ghes.example.com. Plumber auto-detects github.com from your git remote.

Command Reference

plumber analyze

The main command for analyzing GitHub Actions workflows.

plumber analyze [flags]

Flags

Environment Variables

For the configuration commands (plumber config init / generate / migrate / view / validate), plumber explain, and exit codes, see the main CLI page. They behave identically for both providers.

Usage Examples

Save JSON Output

docker run --rm \
  -e GH_TOKEN=ghp_xxxx \
  -v $(pwd):/output \
  getplumber/plumber:latest analyze \
  --github-url github.com \
  --project myorg/myrepo \
  --branch main \
  --config /.plumber.yaml \
  --threshold 100 \
  --output /output/results.json

Silent Mode (JSON Only)

plumber analyze \
  --github-url github.com \
  --project myorg/myrepo \
  --config .plumber.yaml \
  --threshold 100 \
  --output results.json \
  --print false

Example Output

The CLI output is color-coded in your terminal for easy scanning: green for passing controls, red for failures.

Available Controls

Plumber ships 16 GitHub controls (14 default-on plus the opt-in workflowMustIncludeRequiredActions and pipelineMustNotLeakSecretsInConfig). Each can be enabled / disabled and customized in .plumber.yaml. When a control detects a violation, it creates an Issue (e.g., ISSUE-701) with a direct link to its documentation page.

github:
  controls:
    securityJobsMustNotBeWeakened:
      enabled: true
      securityJobPatterns:
        - "*codeql*"
        - "*dependency-review*"
        - "*trufflehog*"
        - "*gitleaks*"
        - "*osv-scanner*"
        - "*-sast"
        - "*-sast-*"
        - "*-scan"
        - "*scan*"
        - "*-security"
        - "*-security-*"
        - "*-audit"
        - "*-audit-*"
        # Real-world slash-form examples (commented; uncomment and
        # adapt to your repo for a tighter match than the wildcards
        # above). Format: <workflow-filename-without-extension>/<job-id>.
        # - codeql-analysis/analyze              # GitHub's default CodeQL template
        # - dependency-review/dependency-review  # GitHub's default Dependency Review template
        # - security/gitleaks                    # gitleaks job in security.yml
        # - security/trufflehog                  # trufflehog job in security.yml
        # - security/*                           # every job in security.yml
        # - "*/sast"                             # any job named "sast", any workflow
        # - ci/semgrep-sast                      # exact match, no wildcard
      allowFailureMustBeFalse:
        enabled: true
      rulesMustNotBeRedefined:
        enabled: true
      whenMustNotBeManual:
        enabled: true

github:
  controls:
    pipelineMustNotExecuteUnverifiedScripts:
      enabled: true
      trustedUrls: []
        # - https://internal-artifacts.example.com/*

github:
  controls:
    pipelineMustNotUseDockerInDocker:
      enabled: true
      detectInsecureDaemon: true

Issues

The CLI reports Issues using identifiers like ISSUE-XXX. Each links to a documentation page with a description, the impact, and before/after fix examples. You can also inspect a code locally:

plumber explain ISSUE-703
# shorthand:
plumber explain 703

Example Configuration

The github.controls: section of a schema v2 .plumber.yaml:

version: "2.0"

github:
  controls:
    # Third-party action references must be pinned by 40-character commit SHA.
    # trustedOwners is the exemption list; first-party `actions/*` and
    # `github/*` are exempt by default.
    actionsMustBePinnedByCommitSha:
      enabled: true
      trustedOwners:
        - actions
        - github

    # uses: owner/repo@ref pointing at an archived GitHub repository.
    actionsMustNotBeArchived:
      enabled: true

    # Cross-references every pinned action against the GitHub Advisory
    # Database under the `actions` ecosystem.
    actionsMustNotCarryKnownCVEs:
      enabled: true

    # Same forbidden-tag list as GitLab plus a digest-pinning sub-option.
    containerImageMustNotUseForbiddenTags:
      enabled: true
      tags:
        - latest
        - dev
        - development
        - staging
        - main
        - master
      containerImagesMustBePinnedByDigest: true

    # Truthy ACTIONS_STEP_DEBUG / ACTIONS_RUNNER_DEBUG in any merged env
    # block, expression binding, or runtime $GITHUB_ENV write.
    pipelineMustNotEnableDebugTrace:
      enabled: true
      forbiddenVariables:
        - ACTIONS_STEP_DEBUG
        - ACTIONS_RUNNER_DEBUG

    # Docker-in-Docker services + insecure daemon configuration
    # (DOCKER_TLS_CERTDIR="" or DOCKER_HOST tcp://...:2375).
    pipelineMustNotUseDockerInDocker:
      enabled: true
      detectInsecureDaemon: true

    # `jobs.<name>.secrets: inherit` hands every secret visible to the
    # caller (repo, organisation, environment) to the reusable workflow.
    # Declare each secret explicitly instead.
    reusableWorkflowsMustNotInheritSecrets:
      enabled: true

    # See the Security Job Weakening Detection section above for the full
    # naming-format reference and slash-form pattern examples.
    securityJobsMustNotBeWeakened:
      enabled: true
      securityJobPatterns:
        - "*codeql*"
        - "*dependency-review*"
        - "*trufflehog*"
        - "*gitleaks*"
        - "*osv-scanner*"
        - "*-sast"
        - "*-sast-*"
        - "*-scan"
        - "*scan*"
        - "*-security"
        - "*-security-*"
        - "*-audit"
        - "*-audit-*"
      allowFailureMustBeFalse:
        enabled: true
      rulesMustNotBeRedefined:
        enabled: true
      whenMustNotBeManual:
        enabled: true

    # curl | bash, wget | sh, download-then-execute, base64 pipe-to-shell.
    pipelineMustNotExecuteUnverifiedScripts:
      enabled: true
      trustedUrls: []
        # - https://internal-artifacts.example.com/*

    # `${{ github.event.* }}`, `${{ github.head_ref }}` or `${{ github.actor }}`
    # interpolated directly into a `run:` shell. Bind through env: first.
    workflowMustNotInjectUserInputInScripts:
      enabled: true

    # `pull_request_target` and `workflow_run` run with the base repo's
    # secrets while being influenceable by an unprivileged caller.
    workflowMustNotUseDangerousTriggers:
      enabled: true

    # Workflows without an explicit `permissions:` block fall back to the
    # repo-wide GITHUB_TOKEN default. Declare `permissions: { contents: read }`
    # at the workflow level for least privilege.
    workflowsMustDeclarePermissions:
      enabled: true

    # `permissions: write-all` at workflow or job scope.
    workflowMustNotGrantPermissionsWriteAll:
      enabled: true

    # Opt-in. Assert every workflow includes the action(s) your org requires.
    workflowMustIncludeRequiredActions:
      enabled: false
      # requiredGroups:
      #   - ["actions/attest-build-provenance"]
      #   - ["your-org/license-scan", "your-org/sbom"]

    # Reads both classic Branch Protection and Repository / Organization
    # Rulesets, unions them, stricter wins.
    branchMustBeProtected:
      enabled: true
      defaultMustBeProtected: true
      namePatterns:
        - main
        - master
        - release/*
        - production
        - dev
      allowForcePush: false
      codeOwnerApprovalRequired: true

See the full configuration reference for every option, the Installation page, and the main CLI page for the provider-agnostic commands and output formats.

Selective Control Execution

You can run or skip specific controls using their YAML key names from .plumber.yaml. This is useful for iterative debugging or targeted CI checks.

# Only check SHA pinning and declared permissions
plumber analyze --controls actionsMustBePinnedByCommitSha,workflowsMustDeclarePermissions

# Run everything except the advisory-database check
plumber analyze --skip-controls actionsMustNotCarryKnownCVEs

Controls not selected are reported as skipped in the output. The --controls and --skip-controls flags are mutually exclusive.

GitHub Action

Use this path for automated compliance on every push or pull request, SARIF in Code Scanning, and no Plumber install on developer machines. Plumber ships as the Plumber Compliance Scanner on the GitHub Marketplace: a uses: step that runs the same engine, the same .plumber.yaml, and the same controls and issues as the CLI.

The action automatically:

• Downloads and checksum-verifies the Plumber binary (with optional SLSA attestation verification)
• Runs plumber analyze with your chosen inputs
• Uploads findings to GitHub Code Scanning via SARIF
• Uploads the JSON report, PBOM, and CycloneDX SBOM as workflow artifacts
• Posts a job summary with compliance percentage, Plumber score, and severity counts

Quick Start

Customizing the action

Override any input to fit your needs:

- uses: getplumber/plumber@COMMIT_SHA   # vX.Y.Z
  with:
    threshold: "80"
    config-file: configs/strict.plumber.yaml
    controls: actionsMustBePinnedByCommitSha,branchMustBeProtected
    score: "true"
    soft-fail: "true"
    upload-sarif: "true"
    upload-artifacts: "true"

All inputs

Outputs

Use outputs in downstream steps:

- uses: getplumber/plumber@COMMIT_SHA   # vX.Y.Z
  id: plumber
- run: echo "Compliance is ${{ steps.plumber.outputs.compliance }}%"

Code Scanning integration

When upload-sarif is true (the default), the action uploads a SARIF 2.1.0 report to GitHub Code Scanning. Each Plumber finding becomes an alert in the Security tab with:

• The issue code as the rule ID (e.g. ISSUE-701)
• Severity mapped to SARIF level (error, warning, note) and a numeric security-severity for triage
• File location pointing at the workflow YAML line
• A helpUri linking to the issue's documentation page on getplumber.io

GitHub Enterprise Server

For GHES, pass the host via github-url:

- uses: getplumber/plumber@COMMIT_SHA   # vX.Y.Z
  with:
    github-url: ghes.example.com
    verify-attestation: "false"

Set verify-attestation: "false" if the runner cannot reach the sigstore transparency log or your GHES instance does not support gh attestation verify.

Examples

Scan a remote repo without cloning:

- uses: getplumber/plumber@COMMIT_SHA   # vX.Y.Z
  with:
    project: my-org/other-repo
    github-token: ${{ secrets.PLUMBER_PAT }}

Run only SHA-pinning and permissions checks:

- uses: getplumber/plumber@COMMIT_SHA   # vX.Y.Z
  with:
    controls: actionsMustBePinnedByCommitSha,workflowsMustDeclarePermissions

Soft-fail in PRs, hard-fail on main:

- uses: getplumber/plumber@COMMIT_SHA   # vX.Y.Z
  with:
    soft-fail: ${{ github.event_name == 'pull_request' && 'true' || 'false' }}

Troubleshooting