Block pull requests that fail agent policy

Choose your integration

This guide uses the Foo Guard GitHub App in a Team workspace. It scans supported agent configuration changes and publishes a Foo Guard Security check. GitHub branch protection or rulesets can then require that check before merging.

If you use API keys and your own workflow instead, see the GitHub Action and CI/CD guide. The Action and the App are separate integrations with different check names and setup requirements. Follow the Action guide's release and repository-access prerequisites rather than assuming a public Action version is available.

Connect and enable a repository

1. Connect the GitHub App to your Team workspace.
2. Grant the installation access to the intended repository.
3. Enable repository scanning in Foo Guard.
4. Commit supported agent configurations under a directory such as agents/.

For MCP-connected agents, use explicit tool and permission declarations. A list of MCP server launch commands alone does not describe the capabilities that Foo Guard analyzes.

Set repository policy

Add .fooguard.yml at the repository root:

version: 1
scan:
  paths:
    - agents/
  include:
    - "**/*.yaml"
    - "**/*.json"
policy:
  failOn: high

This fails policy when findings meet or exceed the high severity threshold. You can also configure minGrade, such as B, if a minimum grade is part of your policy.

Organization policy is a mandatory floor. Repository settings cannot weaken it; the strictest applicable threshold wins. See the repository policy reference for limits, exclusions, and precedence.

Confirm the check runs

Open an in-scope pull request that changes a supported configuration. Inspect Foo Guard Security on the current commit and follow its link to the scan evidence.

Distinguish these outcomes:

• Success: the scan completed and policy passed.
• Failure: the scan completed but policy failed.
• Neutral: no supported configuration was found, or an operational/configuration error occurred.

A completed scan or a “No regression” baseline label does not by itself mean policy passed. Review the check conclusion and policy outcome. A neutral result is not a successful security assessment and should be investigated.

Require the check before merging

In GitHub repository settings, add Foo Guard Security as a required status check for the target branch using branch protection or a repository ruleset. Foo Guard does not change those settings for you.

Follow the branch protection guide. Confirm the rule applies to the intended branches and review who can bypass it. A failing optional check provides feedback but does not enforce a merge gate.

Requiring this check enforces its policy failures. It does not turn neutral outcomes into policy failures or guarantee that every change was scanned. If your process requires every pull request to have a completed assessment, review unsupported files, skipped events, and operational errors as separate coverage requirements.

Test the gate

1. In a test pull request, introduce a known policy violation in an in-scope supported configuration. Use synthetic data without secrets.
2. Confirm a scan exists for the current commit and Foo Guard Security reports failure.
3. Confirm GitHub blocks merging under the configured rule.
4. Remediate the violation and push the corrected configuration.
5. Confirm the new commit receives a successful assessment before merging.

Do not use continue-on-error or a protection bypass to make a failing gate appear successful. For CLI workflows, exit code 0 is pass, 1 is policy failure, and 2 is an operational error; handle both nonzero outcomes explicitly.

Know the coverage boundaries

The App handles supported pull-request events and default-branch pushes. Fork pull requests outside the installation scope are skipped. Review pull-request scanning and troubleshooting before relying on coverage for your contribution model.

This is pre-deployment configuration checking. It does not enforce live agent permissions or execute tools. Keep configuration declarations aligned with the deployed agent, and combine the check with your existing review and runtime controls.