GitHub Action

Automated dependency override management for CI/CD

Quick Start

Basic PR Check

name: Override Check
on: [pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: yowainwright/pastoralist@v1
        with:
          mode: check
          check-security: false

name: Override Check
on: [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 Maintenance
on:
  schedule:
    - cron: "0 0 * * 1" # Weekly on Monday

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"

name: Override Maintenance
on:
  schedule:
    - cron: "0 0 * * 1" # Weekly on Monday

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	Description
`check`	Validate only - reports issues without modifying files
`update`	Modify package.json (default) - you handle commits
`pr`	Create pull request with changes automatically

Check Mode

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

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

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

Update Mode (Default)

Runs pastoralist and modifies package.json. Use when you want to handle commits yourself.

- uses: actions/checkout@v7

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

- name: Commit changes
  run: |
    git config user.name github-actions[bot]
    git config user.email github-actions[bot]@users.noreply.github.com
    git add package.json
    git diff --staged --quiet || git commit -m "chore: update overrides"
    git push

- uses: actions/checkout@v7

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

- name: Commit changes
  run: |
    git config user.name github-actions[bot]
    git config user.email github-actions[bot]@users.noreply.github.com
    git add package.json
    git diff --staged --quiet || git commit -m "chore: update overrides"
    git push

PR Mode

Runs pastoralist and creates a PR if changes are needed. Ideal 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"

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

Inputs

Input	Description	Default
`mode`	Operation mode: `check`, `update`, or `pr`	`update`
`check-security`	Enable security scanning	`true`
`security-provider`	Provider: `osv`, `github`, `npm`, `snyk`, `socket`, `spektion`	`osv`
`security-token`	Token for security provider	-
`auto-fix`	Apply security fixes automatically when the action can write	`true`
`dry-run`	Preview changes only	`false`
`root-dir`	Project root directory	-
`dep-paths`	Workspace patterns (space-separated)	-
`config`	Deprecated; config files are auto-detected from `root-dir`	-
`fail-on-security`	Fail if vulnerabilities found	`true`
`fail-on-unused`	Fail if unused overrides found	`false`
`silent`	Deprecated compatibility input; ignored with a warning	`false`
`debug`	Enable debug logging	`false`
`pr-title`	PR title (mode: pr)	`chore(deps): update dependency overrides`
`pr-body`	PR body (mode: pr)	Auto-generated
`pr-branch`	PR branch name (mode: pr)	`pastoralist/updates`
`pr-labels`	PR labels (space-separated)	`dependencies`
`github-token`	GitHub token for PR creation	`GITHUB_TOKEN`

Outputs

Output	Description
`has-security-issues`	`true` if vulnerabilities were found
`has-unused-overrides`	`true` if unused overrides detected
`updated`	`true` if package.json was modified
`security-count`	Number of security vulnerabilities found
`unused-count`	Number of unused overrides detected
`override-count`	Number of tracked overrides
`pr-url`	URL of created PR (mode: pr only)

Examples

PR Check with Security Gate

name: Override Security
on: [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

name: Override Security
on: [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"

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

Using GitHub Security Provider

- uses: yowainwright/pastoralist@v1
  with:
    security-provider: github
    security-token: ${{ secrets.GITHUB_TOKEN }}

- uses: yowainwright/pastoralist@v1
  with:
    security-provider: github
    security-token: ${{ secrets.GITHUB_TOKEN }}

Conditional PR on Vulnerabilities

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

- name: Create security PR
  if: steps.pastoralist.outputs.has-security-issues == 'true'
  run: |
    # Custom PR logic here

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

- name: Create security PR
  if: steps.pastoralist.outputs.has-security-issues == 'true'
  run: |
    # Custom PR logic here

Weekly Maintenance with Slack Notification

name: Weekly Override Maintenance
on:
  schedule:
    - cron: "0 9 * * 1"

permissions:
  contents: write
  pull-requests: write

jobs:
  maintain:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - uses: yowainwright/pastoralist@v1
        id: pastoralist
        with:
          mode: pr

      - name: Notify Slack
        if: steps.pastoralist.outputs.pr-url != ''
        uses: slackapi/[email protected]
        with:
          payload: |
            {
              "text": "Pastoralist created a PR: ${{ steps.pastoralist.outputs.pr-url }}"
            }

name: Weekly Override Maintenance
on:
  schedule:
    - cron: "0 9 * * 1"

permissions:
  contents: write
  pull-requests: write

jobs:
  maintain:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - uses: yowainwright/pastoralist@v1
        id: pastoralist
        with:
          mode: pr

      - name: Notify Slack
        if: steps.pastoralist.outputs.pr-url != ''
        uses: slackapi/[email protected]
        with:
          payload: |
            {
              "text": "Pastoralist created a PR: ${{ steps.pastoralist.outputs.pr-url }}"
            }

Permissions

For mode: pr, the action needs write permissions:

permissions:
  contents: write
  pull-requests: write

permissions:
  contents: write
  pull-requests: write

Security Providers

Provider	Auth	Notes
`osv`	None	Open Source Vulnerabilities database (default)
`npm`	None	Uses the detected package manager's audit command
`github`	Required	Reads Dependabot alerts; pass `GITHUB_TOKEN` or rely on an authenticated `gh` CLI session
`snyk`	Required	Requires `SNYK_TOKEN` [EXPERIMENTAL]
`socket`	Required	Requires `SOCKET_SECURITY_API_KEY` [EXPERIMENTAL]
`spektion`	Required	Requires `SPEKTION_API_KEY` [EXPERIMENTAL]