[pelikhan]

Motivation

Define centralized cost controls for participating AW workflows as a cooperative admission check—not an unbypassable organization policy or hard spending cap—without forwarding repository API credentials or exposing AI Credit spend through denial diagnostics.

Design

Adds a new-feature specification, bounded formal model, and implementation plan only; no admission runtime implementation is included. The Astro-ready page lives alongside the other published specifications at docs/src/content/docs/specs/admission-service-specification.md and describes a generic admission authority server. Example URLs use the neutral, reserved admission.example.org domain.

• Run an OIDC-authenticated POST /api/admission from the existing activation job, with execution identity and distinct actor/triggering_actor values in a JSON body. No additional job or alternate authentication path. Policy or accounting use of the rerun initiator requires independent run-attempt verification; original actor privileges remain unchanged.
• Configure admission exclusively through managed runtime Actions variables. An unset endpoint is a no-op; transient failures use bounded retries and default to ignore, with block available. Explicit denials, malformed success responses, and fatal configuration/credential errors block.
• Require an admitted 200 JSON response containing max_ai_credits for the verified workflow invocation and a service-generated opaque correlation_id. Preserve stricter local credit limits, share the ceiling across continuations, and block enforcement failures. Keep uniform empty denials and do not expose remaining organization credit.
• Propagate the service ID as gh-aw.admission.correlation_id on subsequent workflow OTel records across jobs and processes, independently of W3C trace/span IDs. traceparent is optional when AW OTel is disabled; admission does not require enabling client tracing/export. Successful admission still requires the service correlation ID.
• Keep the admission authority's optional GitHub App integration entirely server-side, using GitHub's documented App JWT/installation-token flow, approved installation grants, scoped permissions, expiry/renewal, and opaque token handling. Distinguish organization/repository Variables permissions from Actions read permissions; enterprise-wide rollout provisions organization variables rather than assuming an enterprise Actions-variable API.
• Require cleanup of installation tokens separately minted by an authorized runtime capability through DELETE /installation/token. Consider conditional, commit-SHA-pinned actions/create-github-app-token with its default post-job revocation enabled; report cleanup failures and keep tokens job-local. This action does not mint or revoke OIDC JWTs, and GitHub provides no documented Actions OIDC-token revocation endpoint. Admission remains OIDC-only and does not introduce runtime App credentials.
• Document tenant and workflow verification, replay handling, accounting limits, proxy-friendly headers, compact protocol/credential-location diagrams, and 39 acceptance scenarios.

Formal model

specs/workflow-security/ActivationAdmission.tla and its TLC configuration formalize activation gating, verified identity and rerun metadata, retry/outage classification, stable invocation-bound decisions, effective shared credit budgets, response privacy, financially side-effect-free admission, and optional tracing with service correlation. The shared checksum-pinned checker supports --model admission and includes admission in default runs.

The model has 23 safety/type invariants and a weak-fairness termination property. Four secure profiles cover both outage policies with OTel enabled/disabled; 20 synthetic negative controls and eight reachability witnesses exercise the guards and intended paths. Witnesses explicitly demonstrate no-endpoint and fail-open execution, cross-replica lost-response recovery, verified reruns, untraced admission, and credit consumption on both sides of a continuation.

Security boundaries

Repository variables can override organization variables, including shadowing the endpoint with an empty value or choosing fail-open behavior. Workflow editors can omit the step or change its environment wiring. The gate therefore cannot mandate participation or provide an unbypassable organization policy or hard spending cap. Stronger enforcement must occur independently at the controlled AI/backend resource.

The plan covers job-wide id-token: write access and the fail-open tradeoff. Skipped or fail-open executions preserve existing local controls without fabricating a service allowance or correlation ID. GitHub App credentials do not authenticate the workflow or mint its OIDC token.

Formal verification is bounded and applies to the reference state machine, not an implementation. Cryptographic verification, runtime installation-token revocation, HTTP/JSON parsing, trusted URL handling, distributed cache concurrency/expiry, entropy, timing/logging privacy, and actual runtime billing enforcement remain implementation obligations. Synthetic counterexamples are not confirmed product vulnerabilities. Client and admission authority server implementations remain future work.

Validation

• BASE_REF=88d48aeea7 make agent-report-progress
• npm --prefix docs run validate-links — Astro production build (286 pages), all internal links valid
• python3 -m unittest discover -s specs/workflow-security -p 'check_test.py' — 24 tests passed
• Pinned TLA+ Tools v1.8.0: all four secure profiles exhausted, including termination; 77,872 distinct states per ignore profile and 39,416 per block profile
• All 20 synthetic negative controls and eight reachability witnesses produced their exact expected invariant violations, rather than tooling/parser failures; checked lost-response and continuation trace semantics against the final model hash
• GitHub App authentication, token expiry/scoping, exact Variables/Actions/Contents permissions, original/rerun actor semantics, and installation-token revocation checked against official GitHub documentation and the official action's documented cleanup behavior

[github-actions]

🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅

🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer

[github-actions]

✅ Test Quality Sentinel completed test quality analysis.

Test Quality Sentinel

Outcome: reported_no_action

The agent completed and reported no action. A no-op output alone does not verify that all required work was completed or that publication was possible.

Agent messages are omitted from this comment. The category uses structured run status, not interpretation of agent prose.

Generated from Test Quality Sentinel · sonnet50 · 16 AIC · ⌖ 14.1 AIC · ◇ 6.6 AIC · ⊞ 12.6K · ◷

🧪 Test quality analysis by Test Quality Sentinel

[github-actions]

✅ PR Code Quality Reviewer completed the code quality review.

🔎 Code quality review by PR Code Quality Reviewer

[github-actions]

✅ Ponytail Reviewer completed successfully!

Generated by Ponytail Reviewer for #70286

[github-actions]

L329-365: shrink: acceptance matrix duplicates the normative sections. Keep a compact behavior matrix and move permutations to implementation tests.
L371-377: shrink: implementation plan restates earlier requirements. Replace it with an owner-to-section map.

net: -30 lines possible.

Generated by ✂️ Ponytail Reviewer for #70286 · codex · gpt56 · 13.5 AIC · ⌖ 5.38 AIC · ⊞ 14.7K
_{Comment /ponytail to run again}

[github-actions]

Comment Memory

Peek at saved memory (pr-code-quality-reviewer)

reviewed_at: 2026-10-19T16:51:51.691+00:00
review_event: REQUEST_CHANGES
top_themes:
  - activation job OIDC trust-boundary expansion
  - workflow identity contract mismatch in admission request
files_reviewed:
  - specs/admission-service-spec.md
comment_count: 2

Note

This comment is managed by comment memory.

Expand the saved memory block to view or edit the persistent context for this thread.
Edit only the text inside the backtick fences; workflow metadata and the footer are regenerated automatically.

Learn more about comment memory

🔎 Code quality review by PR Code Quality Reviewer · copilot · gpt54 · 42.6 AIC · ⌖ 6.14 AIC · ⊞ 15.9K · ◷
_{Comment /review to run again}

[github-actions]

Request changes

This spec has two blocking contract problems: it widens OIDC minting to repo-controlled activation hooks, and it redefines workflow_id/workflow_call_id incompatibly with current gh-aw behavior.

Blocking themes

• Granting id-token: write to the existing activation job is not isolated today because custom activation setup/pre/step scripts are compiled into that same job.
• The request identity examples and field definitions do not match the values gh-aw currently emits in aw_info.json, especially for reusable workflows.
• This was a static diff review only; I did not run code or tests.

🔎 Code quality review by PR Code Quality Reviewer · copilot · gpt54 · 42.6 AIC · ⌖ 6.14 AIC · ⊞ 15.9K
_{Comment /review to run again}

[github-actions]

Skills-Based Review 🧠

Applied /grill-with-docs and /codebase-design (per pr-triage: change_type=documentation) — two minor clarification suggestions, no blocking issues.

📋 Key Themes & Highlights

Key Themes

• Daily-cap interaction gap: Section 7 defines the per-run ceiling composition with local per-run limits but never states how it relates to the existing max-daily-ai-credits 24-hour window documented in docs/reference/cost-management.md.
• Validator contract underspecified: Implementation Plan step 1 references adding the three managed variables to gh aw env get/update but doesn't name the specific validation rules (HTTPS-only, no embedded credentials/expressions) that should live in pkg/cli/env_command.go, mirroring the existing validateNonZeroInt/validatePositiveInt pattern.

Positive Highlights

• ✅ Excellent terminology fidelity: aw_info.workflow_id/workflow_call_id, gh-aw.max_ai_credits OTel attribute, and ERR_* naming convention all match real codebase usage verified against generate_aw_info.cjs, aw_context.cjs, and send_otlp_span.cjs.
• ✅ All 35 acceptance-test table rows (ADM-001..ADM-035) are present and counted correctly; relative links to compiler_activation_context.go, compiler_activation_permissions.go, env_command.go, and the two .cjs files all resolve.
• ✅ Clear separation of concerns between gh-aw (OIDC client, activation step, budget propagation) and gh-cao (verification, policy, App credentials) with explicit "no job added" and "no credential fallback" invariants repeated consistently throughout.
• ✅ Threat model is unusually rigorous for a spec: timing-independent denials, trace-context untrusted-input handling, and explicit non-goals (not a billing API, not a hard spend cap) are called out up front and reinforced in Section 9.

No code changes accompany this PR (pure spec), so /tdd and /diagnosing-bugs don't apply — correctly excluded by triage.

🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · copilot · sonnet50 · 108.9 AIC · ⌖ 15 AIC · ⊞ 10.1K
_{Comment /matt to run again}

[Copilot]

🔵 Needs a closer look

Unresolved invocation-identity and admission-lifecycle contracts prevent a consistent, safe implementation.

No open issues 🎉

What changed in this PR

Adds a specification for OIDC-authenticated admission within gh-aw’s existing activation job. Runtime implementation remains future work.

Changes:

• Defines managed configuration, authentication, retries, and outage behavior.
• Specifies credit ceilings, telemetry correlation, and credential/privacy boundaries.
• Includes an implementation plan and 35 acceptance scenarios.

File	Description
specs/​admission-service-spec.md	Defines the admission protocol, security requirements, and implementation plan.

_{Review effort: Max}

[pelikhan]

Reply to the original comment

Accepted the substantive clarifications: Section 7 now preserves the independent rolling 24-hour daily guardrail, and Section 12 names URL, audience, and outage-policy validation for both CLI-managed and effective runtime values. This remains a specification-only change.

[pelikhan]

Reply to the original comment

Accepted the no-change disposition, but not as evidence that validation succeeded. I independently checked the request against the actual call-ID helper, ran the 24 checker unit tests, and built the Astro documentation with link validation; admission runtime conformance remains future implementation work.

[pelikhan]

Reply to the original comment

Partially accepted the underlying review: the request now uses the executing workflow references and call IDs emitted by aw_info.json, with signed caller/executing reference binding and fail-closed handling of ambiguous reusable calls. The specification also explicitly covers admission-audience OIDC access by trusted activation hooks without claiming step isolation or adding another job.

[pelikhan]

Reply to the original comment

Partially accepted: Section 12 is now an owner-to-contract map instead of a repeated implementation checklist. All 38 acceptance categories and their security edge cases remain because this downstream specification needs a conformance contract; concrete fixture permutations belong in the implementation tests.

[pelikhan]

Reply to the original comment

Partially accepted the saved themes: the workflow identity contract now matches existing aw_info semantics, including reruns and reusable workflows, and ambiguous repeated calls receive a uniform denial. The job-wide OIDC boundary is explicit, including the fact that an admission-audience token does not prove the admission helper ran; no step-level isolation is claimed.

done

[github-actions]

🎉 This pull request is included in a new release.

Release: v0.92.6