proto-grove - Documentation

Quick Start

- uses: ageha734/proto-grove@v1
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}

That's it. proto-grove will parse your .prototools, check for updates, and create PRs.

Inputs Reference

Input	Default	Description
`prototools-path`	`.prototools`	Path to .prototools file
`config-path`	`.github/proto-grove.toml`	Configuration file path
`github-token`	`${{ github.token }}`	Token for API access
`branch-prefix`	`deps/proto`	PR branch prefix
`automerge-label`	`automerge`	Label for auto-merge
`labels`	`dependencies`	Base labels for all PRs
`dashboard`	`true`	Enable dashboard issue
`dry-run`	`false`	Audit only mode
`log-level`	`info`	Log verbosity

Outputs

Output	Description
`outdated-count`	Number of outdated tools detected
`prs-created`	Number of PRs created
`cves-found`	Number of CVEs found
`summary`	Markdown summary

Configuration

Create .github/proto-grove.toml:

[general]
create-dashboard = true
commit-message-prefix = "chore(deps):"

[automerge]
patch = true
minor = true
major = false
security-fix = true

[repos]
go = "golang/go"
kubectl = "kubernetes/kubernetes"
shfmt = "mvdan/sh"

[ignore]
tools = ["npm", "gcloud"]

[security]
enabled = true
ecosystems = ["Go", "PyPI", "npm", "crates.io"]

Version Constraint Support

Format	Example	Update Behavior
`>=x.y.z`	`>=1.7.7`	Updates floor to latest
`x.y.z`	`1.7.7`	Pins to new exact
`x.y`	`1.25`	Latest within major.minor
`x`	`22`	Latest within major
`stable`	-	Skipped
`""`	-	Skipped

Repository Resolution

proto-grove resolves upstream repos in order:

Config overrides — [repos] in proto-grove.toml
Plugin TOML — Fetches plugin definition, reads git-url / github-repo
GitHub search — Searches by tool name, sorted by stars

Security Scanning

Queries OSV.dev for known vulnerabilities in current versions. Checks multiple ecosystems (Go, PyPI, npm, crates.io, RubyGems). CVEs are included in PR descriptions and the dashboard issue.

Dependency Dashboard

When dashboard: true, proto-grove maintains a single GitHub issue titled "Dependency Dashboard" with:

Pending updates (with links to PRs)
Up-to-date tools
Skipped tools (with reasons)
Security alerts

Examples

Weekly update check

on:
  schedule:
    - cron: "0 9 * * 1"
  workflow_dispatch:

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: ageha734/proto-grove@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

Dry-run on PRs (audit only)

on:
  pull_request:
    paths: ['**/.*prototools']

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ageha734/proto-grove@v1
        id: grove
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          dry-run: 'true'
      - run: echo "Outdated: ${{ steps.grove.outputs.outdated-count }}"

Custom prototools path (chezmoi)

- uses: ageha734/proto-grove@v1
  with:
    prototools-path: 'dot_proto/dot_prototools'
    github-token: ${{ secrets.GITHUB_TOKEN }}