[FAQ] Update: off-platform admission control for safe outputs#29535
[FAQ] Update: off-platform admission control for safe outputs#29535
Conversation
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>
chrizbo
added
automated
faq-update
question-answered
| ```yaml wrap | ||
| jobs: | ||
| external-admission: | ||
| runs-on: ubuntu-latest |
There was a problem hiding this comment.
Added needs: [agent, detection] to the external-admission job in commit 8d408c7. This ensures the external policy call only runs after the agent job completes and threat scanning has finished — consistent with the approval-gate example above it.
There was a problem hiding this comment.
Pull request overview
Updates the FAQ entry on requiring external human approval before safe outputs are applied, extending it to include fully off-platform admission control via an external authority called from a gate job.
Changes:
- Adds a new “Fully off-platform admission control” subsection under the existing FAQ entry.
- Provides a GitHub Actions YAML example showing an external admission job gating
safe-outputs. - Clarifies the intended fail-closed behavior when external admission is not granted.
Show a summary per file
| File | Description |
|---|---|
| docs/src/content/docs/reference/faq.md | Expands the existing approval-gate FAQ entry with an off-platform admission-control pattern and example YAML. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 1/1 changed files
- Comments generated: 2
| 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 }}"}' |
There was a problem hiding this comment.
The text says the external call can be "denied", but the example only fails the job on non-2xx/3xx HTTP responses (curl --fail). If the policy engine returns 200 with a denial decision in the response body, this workflow would still proceed and allow safe-outputs to run. Either clarify that denial must be indicated via a failing HTTP status code, or update the example to explicitly check the response and exit non-zero on denial (fail-closed).
| steps: | ||
| - name: Request admission from external authority | ||
| run: | | ||
| curl --fail -X POST https://YOUR_POLICY_ENGINE/v1/admit \ |
There was a problem hiding this comment.
The placeholder URL https://YOUR_POLICY_ENGINE/... includes an underscore, which is not valid in a DNS hostname and can cause copy/paste confusion. Consider using a syntactically valid example host (e.g., https://policy.example.com/...) while keeping it clearly placeholder text.
| curl --fail -X POST https://YOUR_POLICY_ENGINE/v1/admit \ | |
| curl --fail -X POST https://policy.example.com/v1/admit \ |
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>
Extends the existing FAQ entry "Can I require external human approval before safe outputs are applied?" to cover fully off-platform admission control — i.e., calling an external policy engine, PAM/PIM system, or compliance approval API from the gate job before safe output jobs are allowed to run.
The previous entry covered GitHub-hosted Environment protection rules. This adds a concrete example for users whose threat model requires an authority entirely outside GitHub's control plane.
Change type: Update to existing entry (no new section added)
Source issue: github/agentic-workflows#517