GitHub Action

Overview

The Foo Guard GitHub Action runs the committed CLI in your workflow and fails the job when security policy is violated. It supports Pro personal API keys and Team organization service keys.

The action is a composite action located at action/action.yml in the Foo Guard repository. It executes packages/cli/dist/index.js and installs only runtime npm dependencies at workflow time.

Plan requirements

• Pro — create a personal API key (agt_live_...) in your dashboard
• Team — use an organization service key (agt_team_...) from Team settings

Store the key as a repository secret named FOOGUARD_API_KEY. Never commit API keys to source control.

Legacy workflows may still use the AGENTGUARD_API_KEY secret name; pass it to the action's api-key input the same way.

Team customers may prefer native GitHub Checks from the GitHub App instead of adding a workflow step.

Workflow permissions

Declare permissions in your workflow file:

permissions:
  contents: read
  pull-requests: write   # required only when comment: true

The action metadata itself does not set workflow permissions.

Minimal workflow

After the first tagged Action release is published, reference it externally:

name: Foo Guard

on:
  pull_request:
    paths:
      - "agents/**"
      - "**/.agentguard.yml"

permissions:
  contents: read

jobs:
  agent-security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - id: agentguard
        name: Foo Guard security gate
        uses: fshbeeb/agentguard/action@<version>
        with:
          api-key: ${{ secrets.FOOGUARD_API_KEY }}
          path: ./agents
          fail-on: high

Replace <version> with a release tag such as v1.0.0. A floating major alias such as @v1 will be available after the first tagged Action release.

For private pre-release certification within the same GitHub account, pin to an approved release candidate tag or commit SHA. Do not use main as a long-term consumer reference.

Advanced workflow

name: Foo Guard

on:
  pull_request:
    paths:
      - "agents/**"
      - "**/.agentguard.yml"

permissions:
  contents: read
  pull-requests: write

jobs:
  agent-security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - id: agentguard
        name: Foo Guard security gate
        uses: fshbeeb/agentguard/action@<version>
        with:
          api-key: ${{ secrets.FOOGUARD_API_KEY }}
          path: ./agents
          fail-on: high
          min-grade: B
          comment: "true"
          baseline: "true"
          baseline-path: .agentguard.baseline.json
          verbose: "false"

When comment: true on a pull request event, the action publishes or updates a PR summary comment.

Inputs

Outputs

Read outputs from the action step id:

steps.agentguard.outputs.exit-code
steps.agentguard.outputs.policy-passed

Related

• CI/CD enforcement
• CLI
• GitHub Checks — Team native alternative

Send findings to GitHub code scanning

Set the action's optional sarif-out input, then upload the report in a separate step. The upload permission belongs to this workflow; no change to the Foo Guard GitHub App is needed.

name: Foo Guard SARIF
on: [push, pull_request]

jobs:
  agent-security:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      actions: read # needed for uploads in private repositories
      security-events: write

    steps:
      - uses: actions/checkout@v4
      - name: Scan agent configs
        id: fooguard
        uses: fshbeeb/agentguard/action@<version>
        with:
          api-key: ${{ secrets.FOOGUARD_API_KEY }}
          path: ./agents
          sarif-out: fooguard-results.sarif
      - name: Upload complete scan findings
        if: ${{ !cancelled() && (steps.fooguard.outputs.exit-code == '0' || steps.fooguard.outputs.exit-code == '1') }}
        uses: github/codeql-action/upload-sarif@v4
        with:
          sarif_file: fooguard-results.sarif
          category: fooguard-agent-configs

Replace <version> with a release containing SARIF support, or pin a reviewed commit. Policy failure still fails the scan step; the upload runs for both a pass and a policy failure, but not an operational error. Keep the category and scanned scope stable across runs. Do not upload a subset of files as though it were the full previous scan.

GitHub code scanning availability depends on the repository and its GitHub plan. Fork pull requests may not have permission to access secrets or upload results. See GitHub SARIF support for eligibility, upload limits and location requirements. Foo Guard does not automatically upload these exports or enable GitHub Code Security.