From 1591eeb87380049a19af0015e55756e314614ead Mon Sep 17 00:00:00 2001
From: Chris Butler <chrizbo@github.com>
Date: Fri, 1 May 2026 05:05:27 -0700
Subject: [PATCH 1/2] FAQ: add off-platform admission control example

Extend the external approval FAQ entry to cover the case where
users need an admission authority completely outside GitHub's
control plane (e.g. external policy engine, PAM/PIM system).

Closes github/agentic-workflows#517

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 docs/src/content/docs/reference/faq.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/docs/src/content/docs/reference/faq.md b/docs/src/content/docs/reference/faq.md
index 8add66517af..1fff00e171e 100644
--- a/docs/src/content/docs/reference/faq.md
+++ b/docs/src/content/docs/reference/faq.md
@@ -242,6 +242,30 @@ This approval is enforced by GitHub's infrastructure, not by workflow logic the
 
 Note that the *policy* — which environments require approval, what safe outputs are configured — is defined by whoever controls the repository. The admission decision for each run can be external; the admission policy itself is internal to repository owners.
 
+**Fully off-platform admission control**
+
+If your threat model requires an authority completely outside GitHub's control plane — such as an external policy engine, a PAM/PIM system, or a compliance approval workflow — call that system from your gate job before it proceeds:
+
+```yaml wrap
+jobs:
+  external-admission:
+    runs-on: ubuntu-latest
+    environment: production-deploy   # optional: also adds GitHub-native reviewer gate
+    steps:
+      - name: Request admission from external authority
+        run: |
+          curl --fail -X POST https://YOUR_POLICY_ENGINE/v1/admit \
+            -H "Authorization: Bearer $POLICY_TOKEN" \
+            -d '{"workflow_run": "${{ github.run_id }}"}'
+        env:
+          POLICY_TOKEN: ${{ secrets.POLICY_TOKEN }}
+
+safe-outputs:
+  needs: [external-admission]   # write jobs don't run until external admission is granted
+```
+
+If the external call fails or is denied, the safe output jobs never run. This places the final admission decision in a system entirely independent of GitHub.
+
 ### 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 8d408c765acc21334e4260ed1f6b1be2c2866230 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 1 May 2026 15:00:04 +0000
Subject: [PATCH 2/2] docs: add needs [agent, detection] to external-admission
 job example

Agent-Logs-Url: https://github.com/github/gh-aw/sessions/2fc7968f-cb46-4067-a732-f733aedc89e4

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 docs/src/content/docs/reference/faq.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/src/content/docs/reference/faq.md b/docs/src/content/docs/reference/faq.md
index 1fff00e171e..ffb3058c4fa 100644
--- a/docs/src/content/docs/reference/faq.md
+++ b/docs/src/content/docs/reference/faq.md
@@ -250,6 +250,7 @@ If your threat model requires an authority completely outside GitHub's control p
 jobs:
   external-admission:
     runs-on: ubuntu-latest
+    needs: [agent, detection]        # waits for agent output and threat scanning to complete
     environment: production-deploy   # optional: also adds GitHub-native reviewer gate
     steps:
       - name: Request admission from external authority