From ac6c7075a3c9511e34c9ce75a6db31ae39b2cfe1 Mon Sep 17 00:00:00 2001 From: Chris Butler Date: Tue, 28 Apr 2026 05:25:16 -0700 Subject: [PATCH 1/2] docs(faq): add entry on external admission authority for trusted execution Addresses the architectural question of whether the execution platform should own the final admission decision for trusted execution context, covering the layered trust model, available workarounds using pre-agent steps and custom safe output jobs, and the current limitation that a truly external authority outside GitHub Actions is not natively supported. Relates to: github/agentic-workflows#485 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/src/content/docs/reference/faq.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/src/content/docs/reference/faq.md b/docs/src/content/docs/reference/faq.md index 23b6363dab..3751860899 100644 --- a/docs/src/content/docs/reference/faq.md +++ b/docs/src/content/docs/reference/faq.md @@ -216,6 +216,28 @@ 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/). +### Should the execution platform own the final admission decision for trusted execution context? + +This is a meaningful architectural distinction: *guardrail validation* answers whether the agent's proposed output looks acceptable; *admission authority* answers whether this execution intent is allowed to proceed at all. + +gh-aw's [layered trust model](/gh-aw/introduction/architecture/) roots at the GitHub Actions substrate (Layer 1). The execution platform — GitHub Actions — does own the final admission decision. Any in-workflow approval step, including GitHub Environments with required reviewers, is still within that same control plane. + +The closest approximation to an external admission gate today is to use **pre-agent `steps:`** to call an external policy service before the agent runs. If the step fails, the agent is blocked — 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) in your admission service to cryptographically verify that the request genuinely originates from the expected repo and ref. + +Similarly, 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 — providing an admission gate on the write side. + +The limitation is that both patterns still run within the GitHub Actions trust boundary. A truly external authority that intercepts execution before the workflow receives its token is not currently supported. If this is a hard requirement, the current approach treats the external call as a policy enforcement layer while accepting GitHub Actions as the underlying substrate. + ### 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: From 846023faeaffc41e9a8f0384532444ba0dc43e7d Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 28 Apr 2026 14:27:56 +0000 Subject: [PATCH 2/2] docs(faq): unslop admission authority entry - simpler title and tighter prose Agent-Logs-Url: https://github.com/github/gh-aw/sessions/6aa11b2b-16f7-4676-9ac9-51bd93f1ccd3 Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- docs/src/content/docs/reference/faq.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/docs/src/content/docs/reference/faq.md b/docs/src/content/docs/reference/faq.md index 3751860899..04cc3da73d 100644 --- a/docs/src/content/docs/reference/faq.md +++ b/docs/src/content/docs/reference/faq.md @@ -216,13 +216,11 @@ 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/). -### Should the execution platform own the final admission decision for trusted execution context? +### Can I use an external policy service to gate whether the agent runs? -This is a meaningful architectural distinction: *guardrail validation* answers whether the agent's proposed output looks acceptable; *admission authority* answers whether this execution intent is allowed to proceed at all. +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. -gh-aw's [layered trust model](/gh-aw/introduction/architecture/) roots at the GitHub Actions substrate (Layer 1). The execution platform — GitHub Actions — does own the final admission decision. Any in-workflow approval step, including GitHub Environments with required reviewers, is still within that same control plane. - -The closest approximation to an external admission gate today is to use **pre-agent `steps:`** to call an external policy service before the agent runs. If the step fails, the agent is blocked — fail-closed: +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: @@ -232,11 +230,11 @@ steps: -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) in your admission service to cryptographically verify that the request genuinely originates from the expected repo and 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. -Similarly, 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 — providing an admission gate on the write side. +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. -The limitation is that both patterns still run within the GitHub Actions trust boundary. A truly external authority that intercepts execution before the workflow receives its token is not currently supported. If this is a hard requirement, the current approach treats the external call as a policy enforcement layer while accepting GitHub Actions as the underlying substrate. +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?