diff --git a/docs/src/content/docs/reference/faq.md b/docs/src/content/docs/reference/faq.md index 23b6363dab..04cc3da73d 100644 --- a/docs/src/content/docs/reference/faq.md +++ b/docs/src/content/docs/reference/faq.md @@ -216,6 +216,26 @@ See [Text Sanitization](/gh-aw/reference/safe-outputs/#text-sanitization-allowed Guardrails are foundational to the design. Agentic workflows implement defense-in-depth through compilation-time validation (schema checks, expression safety, action SHA pinning), runtime isolation (sandboxed containers with network controls), permission separation (read-only defaults with [safe outputs](/gh-aw/reference/safe-outputs/) for writes), tool allowlisting, and output sanitization. See the [Security Architecture](/gh-aw/introduction/architecture/). +### Can I use an external policy service to gate whether the agent runs? + +gh-aw's trust model is rooted in the GitHub Actions substrate. GitHub Actions owns the final admission decision — even GitHub Environments with required reviewers operates within that same control plane. + +To enforce an external policy before the agent runs, add a **pre-agent `steps:`** that calls your policy service. If the step fails, the workflow stops fail-closed: + +```yaml wrap +steps: + - name: External admission check + run: | + curl -sf -X POST https://admission.internal/check \ + -d '{"repo":"${{ github.repository }}","ref":"${{ github.ref }}"}' +``` + +Use [GitHub Actions OIDC tokens](https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect) to cryptographically verify the request originates from the expected repo and ref. + +For write-side control, a [custom safe output job](/gh-aw/reference/safe-outputs/#custom-safe-output-jobs-jobs) can call an external policy service before applying the agent's proposed changes. + +Both patterns run within the GitHub Actions trust boundary. A truly external authority that intercepts execution before the workflow receives its token is not currently supported. + ### How is my code and data processed? By default, your workflow is run on GitHub Actions, like any other GitHub Actions workflow, and as one if its jobs it invokes your nominated [AI Engine (coding agent)](/gh-aw/reference/engines/), run in a container. This engine may in turn make tool calls and MCP calls. When using the default **GitHub Copilot CLI**, the workflow is processed by the `copilot` CLI tool which uses GitHub Copilot's services and related AI models. The specifics depend on your engine choice: