Foo GuardBeta
Menu

GitHub Action

Fail GitHub Actions workflows when agent configurations violate security policy.

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

| Input | Required | Default | Description |

|-------|----------|---------|-------------|

| `api-key` | Yes | — | Foo Guard API key (`agt_live_...` or `agt_team_...`) |

| `api-url` | No | `https://fooguard.com` | Foo Guard API base URL |

| `path` | No | `.` | File or directory to scan |

| `fail-on` | No | `high` | Fail on findings at or above this severity (`critical`, `high`, `medium`) |

| `min-grade` | No | — | Optional minimum acceptable grade (`A`–`F`) |

| `comment` | No | `false` | Publish a PR summary comment |

| `baseline` | No | `false` | Compare against a committed baseline file |

| `baseline-path` | No | `.agentguard.baseline.json` | Baseline JSON file path |

| `verbose` | No | `false` | Print expanded finding evidence |

Outputs

| Output | Description |

|--------|-------------|

| `exit-code` | CLI exit code (`0` pass, `1` policy fail, `2` error) |

| `policy-passed` | `true` when exit code is `0` |

Read outputs from the action step id:

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

Related

Related pages