GitHub Action

Automated dependency override management for CI

Quick Start

Basic PR Check

name: Override Checkon: [pull_request] jobs:  check:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v7      - uses: yowainwright/pastoralist@v1        with:          mode: check          check-security: false

The action enables OSV security scanning by default. Set check-security: false when you only want to validate override tracking.

Scheduled Maintenance with PR Creation

name: Override Maintenanceon:  schedule:    - cron: "0 0 * * 1" permissions:  contents: write  pull-requests: write jobs:  maintain:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v7      - uses: yowainwright/pastoralist@v1        with:          mode: pr          pr-title: "chore(deps): update dependency overrides"          pr-labels: "dependencies automated"

Modes

`mode: check`

Runs Pastoralist in dry-run mode. Reports issues without modifying files.

- uses: yowainwright/pastoralist@v1  with:    mode: check

`mode: update`

Default: selected when mode is unset

Writes changes to the configured project files without committing them.

- uses: yowainwright/pastoralist@v1  with:    mode: update

`mode: pr`

Runs Pastoralist and creates a PR if changes are needed. This is best for scheduled workflows. Use this mode with contents: write and pull-requests: write workflow permissions.

- uses: yowainwright/pastoralist@v1  with:    mode: pr    pr-title: "fix(security): update vulnerable overrides"

Inputs

`mode`

Type: "check" | "update" | "pr" Default: "update"

Selects validation, direct file updates, or PR creation.

`check-security`

Type: boolean Default: true

Enables vulnerability scanning.

`security-provider`

Type: "osv" | "github" | "npm" | "snyk" | "socket" | "spektion" Default: "osv"

Selects the security provider used when check-security is enabled.

`security-token`

Type: string Default: unset

Passes a token to providers that require authentication.

`auto-fix`

Type: boolean Default: true

Applies security fixes automatically when the action can write files.

`dry-run`

Type: boolean Default: false

Previews changes without modifying files. mode: check always runs as a dry run.

`root-dir`

Type: string Default: unset

Sets the project root directory passed to pastoralist --root.

`dep-paths`

Type: string Default: unset

Passes space-separated workspace package patterns to pastoralist --depPaths.

`config`

Type: string Default: unset

Deprecated. Config files are auto-detected from root-dir.

`fail-on-security`

Type: boolean Default: true

Fails on findings, except when an auto-fix PR has changes ready to submit.

`fail-on-scan-error`

Type: boolean Default: true

Fails the action if a security provider cannot complete its scan.

`fail-on-unused`

Type: boolean Default: false

Fails the action when unused overrides are detected.

`silent`

Type: boolean Default: false

Deprecated compatibility input. The action ignores it and prints a warning when it is enabled.

`debug`

Type: boolean Default: false

Passes --debug to Pastoralist.

`pr-title`

Type: string Default: "chore(deps): update dependency overrides"

Sets the PR title for mode: pr.

`pr-body`

Type: string Default: auto-generated

Sets the PR body for mode: pr.

`pr-branch`

Type: string Default: "pastoralist/updates"

Sets the PR branch for mode: pr.

`pr-labels`

Type: string Default: "dependencies"

Adds space-separated labels to the PR created by mode: pr.

`github-token`

Type: string Default: github.token

Sets the GitHub token for PR creation.

Outputs

`has-security-issues`

Type: "true" | "false" Default: "false"

Reports whether vulnerabilities were found.

`has-unused-overrides`

Type: "true" | "false" Default: "false"

Reports whether unused overrides were detected.

`security-fixes-applied`

Type: "true" | "false"

Reports whether every detected vulnerability received a new security override. This does not report a post-install rescan.

`updated`

Type: "true" | "false" Default: "false"

Reports whether package.json was modified.

`security-count`

Type: number Default: 0

Reports the number of security vulnerabilities found.

`unused-count`

Type: number Default: 0

Reports the number of unused overrides detected.

`override-count`

Type: number Default: 0

Reports the number of tracked overrides after the run.

`pr-url`

Type: string Default: ""

Reports the created PR URL in mode: pr.

Examples

PR Check with Security Gate

name: Override Securityon: [pull_request] jobs:  security:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v7       - uses: yowainwright/pastoralist@v1        with:          mode: check          fail-on-security: true          security-provider: osv

Monorepo Support

- uses: yowainwright/pastoralist@v1  with:    dep-paths: "packages/*/package.json apps/*/package.json"

Using GitHub Security Provider

name: Dependabot Alert Checkon: [pull_request] permissions:  contents: read  vulnerability-alerts: read jobs:  security:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v7      - uses: yowainwright/pastoralist@v1        with:          mode: check          security-provider: github          security-token: ${{ secrets.GITHUB_TOKEN }}

Permissions

For mode: pr, the action needs write permissions:

permissions:  contents: write  pull-requests: write

Security Providers

`security-provider: osv`

Auth: none Default: selected when security-provider is unset

Uses the Open Source Vulnerabilities database.

`security-provider: npm`

Auth: none Default: unset

Uses the detected package manager's audit command.

`security-provider: github`

Auth: required Default: unset

Reads Dependabot alerts. Pass GITHUB_TOKEN or rely on an authenticated gh CLI session.

`security-provider: snyk`

Auth: required Default: unset

Requires SNYK_TOKEN.

`security-provider: socket`

Auth: required Default: unset

Requires SOCKET_SECURITY_API_KEY.

`security-provider: spektion`

Auth: required Default: unset

Requires SPEKTION_API_KEY.