Signed AI Agent Audit Trails for GitHub and Runtime Guardrails

Summary: An auditor reviewing an AI-assisted change needs more than a passing job or an agent's explanation. The record should show the identity, policy result and evidence of what executed. APort's decision-versus-enforcement contract defines those as separate facts; the GitHub integration adds OIDC-bound repository identity and verifies hosted decision signatures.

A signed OAP decision preserves what the verifier concluded about submitted context. It does not, by itself, prove that a runtime blocked a tool, that a merge happened, or that every sensitive action went through the verifier. An audit trail needs to retain those limits.

Audit logs are not enough when agents can act

An event log can establish that a workflow ran, a pull request merged or a tool returned successfully. The authorization question is different: what policy evaluated the proposed operation, for which identity, using which evidence, before the relevant enforcement point?

Keep both records. A policy deny without an execution record does not establish that dispatch stopped. A successful tool result without a decision does not establish that the operation was authorized. This distinction gives incident reviewers a way to identify missing coverage without guessing from the model's explanation.

What a passport gives an AI agent

The passport product documentation and OAP specification describe the identity and scope model. Relevant information includes the agent ID, owner, active status, capabilities, limits, regions and assurance evidence. Integration metadata can bind that identity to a framework or repository.

A passport is not an API secret and is not proof that enforcement happened. Its authority must be checked by the connected verifier. For an investigation, preserve enough information to identify the passport and policy used at decision time; reading a later edited passport alone may give the reviewer a different scope.

The owner also determines where governance records belong. A repository-scoped passport issued by the default hosted GitHub path and a customer-managed passport have different ownership. Decide that deliberately before interpreting an organization dashboard as a complete activity inventory.

Read the decision as a policy receipt

The GitHub Action verifies the hosted signature against the OAP JWKS endpoint. Preserve the original record for validation rather than copying selected fields into an unsigned summary and treating that summary as equivalent evidence.

Signature verification supports record integrity. The trustworthiness of input evidence still depends on its source. GitHub OIDC claims and runner-observed diffs have different roles; attribution heuristics are evidence, not a substitute for the token's repository binding.

GitHub context makes the decision operational

This is a retention checklist, not a guarantee that every field appears in every response. The Action's documented outputs include actor classification, confidence, provenance, decision ID, outcome and structural findings. Record which evidence was actually available.

Treat a missing workflow patch as a limit on the review, not as an empty harmless change. Likewise, keep runner-observed content distinct from the trusted repository identity. A valid signature preserves what the verifier received and decided; it does not independently make every supplied fact trustworthy.

One vocabulary across runtime and repository records

The same review should work across Claude Code, Cursor, MCP tools and GitHub Guard: identify the agent, requested operation, evaluated policy, decision and actual outcome where known.

That vocabulary simplifies comparison while preserving integration differences. A local fixture test may have no hosted decision ID. A CI-time receipt can describe a repository change after a command ran. An adapter with no post-action reporter leaves execution unknown. Those differences belong in the record instead of being erased to make a uniform dashboard.

Reconcile a denial with a passing workflow

Suppose policy returns allow: false, but the operator has configured warn mode. The correct audit interpretation is a denial with expected continuation, not an allowed action. If there is no post-action report, actual execution remains unknown.

The contract uses enforcement_mode and expected_runtime_disposition for pre-action metadata, with runtime_disposition as optional post-action evidence. Keep an infrastructure fail-open exception distinct from both an allow and a warn-mode denial.

For GitHub, a report-only job may pass while identifying a policy violation. Blocking requires the enforcement configuration and a required branch check. A push-triggered record concerns an event that already landed; it is not evidence of pre-push prevention.

Choose where the evidence belongs

Default hosted GitHub OIDC issuance uses an APort-owned repository passport. A team needing decisions in its own organization should configure the managed hosted audit path with a managed passport and scoped API key, while retaining the OIDC binding.

GitHub local JSON mode uses verification with a supplied passport and skips hosted persistence, telemetry and replay lookup. Runtime local/offline guardrails likewise do not appear in hosted dashboards unless the operator enables telemetry. Document these choices so missing hosted rows are not mistaken for an absence of activity.

The OIDC setup explanation covers the credential choices. The Claude Code security review covers the runtime's part of the evidence chain.

What this looks like in practice

A hosted GitHub evidence chain has several reviewable steps:

1. A supported repository event triggers the Action.
2. The job obtains a GitHub OIDC token for its workflow identity.
3. APort resolves or issues a repository-bound passport, or uses the configured managed passport with both required checks.
4. The Action collects changed files, commits, workflow context and completeness signals.
5. The repository verifier evaluates the submitted action and returns a policy result.
6. The Action validates the hosted decision signature against the issuer's verification material.
7. The job reports or enforces according to its configuration; branch rules determine merge gating.
8. The reviewer joins the decision to workflow and runtime outcomes, preserving any unavailable evidence.

The process cannot establish more than its weakest unobserved step. Retain the original signed payload, the key identifier and the verification result. An unsigned hand-written summary may help a human read it, but should not replace the receipt that can be checked.

Work through a denial with unknown execution

Suppose the policy returns a deny for a sensitive file operation and the runtime configuration is warn mode. The pre-action metadata can describe expected continuation. If there is no post-action report, the reviewer should record actual execution as unknown.

If a tool-side record later confirms a read, join it by the available decision and operation references. The completed case is then a policy denial with continued execution under warn mode. Calling it an allow would lose the violation; calling it a block would invent protection.

Similarly, a hosted outage that triggers an operator-approved fallback has no successful policy decision to relabel. Keep the error, fallback configuration and observed execution separate. This makes an incident review able to distinguish a policy problem, an enforcement choice and an availability exception.

What to measure

Do not infer complete coverage from a high decision count. An uninstrumented tool contributes no row. The employee-tool governance guide starts with an inventory and owner so that the denominator exists outside the dashboard.

The CIO and CISO value

Engineering leadership needs to know which legitimate workflows continue and who can change their policy. Security leadership needs to know which prohibited actions stopped, which continued by configuration and which outcomes remain unknown. An auditor needs the evidence to reconstruct one case without relying on a verbal account.

For all three, local-versus-hosted mode and retention scope are operational decisions. Document them along with who may suspend a passport, change enforcement or approve an exception. A signed-decision format supports that process; it does not assign those responsibilities automatically or certify the organization.

Assemble one reviewable case

Select a harmless allowed operation and a prohibited fixture operation. Retain their policy results, mode configuration and observed tool effects. Where hosted decisions exist, join them using decision_id; where runtime telemetry is missing, label that explicitly.

For a GitHub case, include the repository, relevant commit and workflow context available to the review. Redact secrets and unnecessary personal data. Do not publish raw prompts or customer records merely to make a receipt look detailed.

Plan your Team Pilot around the evidence one reviewer needs to explain an allowed action, a blocked action and an unknown runtime outcome.

Budget the evidence workflow with the rollout

Assign a reviewer and retention owner before expanding the pilot. Agree which signed records, repository context and runtime outcomes are required for an investigation. A dashboard cannot report activity from an unconnected tool, so use the independent inventory to label coverage gaps.

Team provides hosted signed decisions and organization audit through organization billing. Enterprise rollout planning is appropriate when IT deployment, custom policy support or leadership reporting needs an agreed scope. Keep audit review, adoption outcomes and remaining control gaps in the same expansion decision.

Product and implementation sources

• Decision Audit Trails
• Signed decisions and audit evidence
• Decision and enforcement contract
• Plan features and billing