GitHub Action¶

Available CLI Options¶

When running Agronomist in GitHub Actions, you can use these CLI options:

• --github-token GitHub token for API calls (or use GITHUB_TOKEN env var).
• --root Root directory to scan. Default: .
• --include Glob patterns to include. Can be specified multiple times.
• --exclude Glob patterns to exclude. Can be specified multiple times.
• --json JSON report file name. If omitted, no report is generated.
• --markdown Markdown report file (optional).
• --github-base-url GitHub API base URL (for GitHub Enterprise).
• --resolver Version resolver strategy: git, github, or auto. Default: git
• --config Path to configuration file. Default: .agronomist.yaml
• --validate-token Validate API token before processing.

Minimal Example¶

LATEST=$(curl -s https://api.github.com/repos/Ops-Talks/agronomist/releases/latest | jq -r .tag_name)

The following workflow installs Agronomist from GitHub Releases and applies updates:

name: Agronomist Updates
on:
  schedule:
    - cron: "0 7 * * 1"
  workflow_dispatch: {}

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Agronomist
        run: |
          AGRONOMIST_VERSION="vX.Y.Z" # Use the latest version
          WHEEL="agronomist-${AGRONOMIST_VERSION#v}-py3-none-any.whl"
          curl -L -o "$WHEEL" "https://github.com/Ops-Talks/agronomist/releases/download/${AGRONOMIST_VERSION}/${WHEEL}"
          pip install "$WHEEL"
      - name: Run Agronomist
        run: |
          agronomist update --root .
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Full Multi-PR Example¶

For production use, the recommended workflow creates one pull request per updated module. Each branch is named with the module identifier and a short hash, and every run with diffs tries to create a PR first. If a PR for the same branch already exists, the workflow updates it (or reopens it when closed).

See examples/workflows/agronomist-ci.yml for the full workflow that:

• Runs agronomist update and generates report.json.
• Iterates over each module in the report using jq.
• Creates a dedicated branch and PR per module via gh pr create.
• Uses SHA-256 hashing to produce deterministic, unique branch names.

Branch naming¶

When creating one PR per module, each branch is named:

agronomist/update-<base-module>-<hash8>

• <base-module> — the module name (path before @), with / and @ replaced by -, truncated to 50 characters.
• <hash8> — first 8 characters of the SHA-256 hash of the full module ID (base module + file path). This ensures two files that reference the same upstream module produce distinct branch names.

The PR title and commit message use the same pattern: [Agronomist] Update <base-module> to <latest-ref>.

Examples¶

The last two rows show the same upstream module (cloudwatch-log-group) referenced from two different files. Because the hash is derived from the full module ID (including the file path), each file gets a unique branch and PR — even though the base module name is identical.