Troubleshooting

When an exchange fails, the JSON error response carries two useful fields. code is the machine-readable error code that tells you which layer rejected the request. trace_id correlates the response to a server log line that carries the full reason. error is deliberately generic; branch on code, not on error.

{ "error": "forbidden", "code": "policy_denied", "trace_id": "abc-123" }

# In your server logs / kubectl logs
grep abc-123 /var/log/github-sts.log

Common errors

Deployment

OIDC validation

Audience

Policy

Bundle signature verification

Every signature failure reports a signature_error_code and a signature_operation in the logs. The code names the phase that failed, which is what tells you whether to re-sign, fix registry access, or upgrade a publisher.

Only the standardized Sigstore bundle format is verified. A bundle whose only signature is a legacy sha256-<digest>.sig tag reports signature_not_found, because as far as this broker is concerned it is unsigned.

Replay

App pools

Upstream and audit

Debugging an exchange end-to-end

1. Obtain an OIDC token from your identity provider. In GitHub Actions, request one with id-token: write and core.getIDToken():

   # In a workflow step that has id-token: write
   #   const token = await core.getIDToken('https://sts.example.com')
   # Or, outside a workflow, use your provider's CLI (e.g. gcloud auth print-identity-token).
   export OIDC_TOKEN="<the token>"

2. Set GITHUBSTS_SERVER_LOG_LEVEL=debug temporarily. Each exchange logs the validation pipeline at this level, with the trace_id correlating server-side reasons to the response code.

3. Decode the OIDC token locally to confirm iss, sub, aud, repository_owner_id, repository_id, and any custom claims:

   echo "$OIDC_TOKEN" | cut -d. -f2 | base64 -d 2>/dev/null | jq .

4. Read the trust policy the server is loading:

   gh api repos/myorg/myrepo/contents/.github/sts/default/ci.sts.yaml \
     --jq .content | base64 -d

5. Compare claims to the policy line by line:

   • policy.issuer == token.iss (exact match)
   • policy.subject == token.sub (or subject_pattern regex matches token.sub)
   • policy.audience == token.aud (and oidc.required_audience if set)
   • Each claim_pattern[k] regex matches token[k]
   • github.sources[] contains the token’s exact owner/repository ID pair
   • github.target matches the target owner/repository IDs shown in audit

Verify bundle posture

curl -s http://localhost:8080/health | jq '{security, bundles}'
curl -s http://localhost:8080/metrics | grep githubsts_bundle_enforcement_required

Production should report require_immutable_subject_claims: true, bundle_enforcement: "required", yaml_only_authorization_possible: false, and metric value 1. Per-bundle health should identify exactly one mandatory: true baseline whose policy_revision matches its configured expected_policy_revision. Audit events always carry bundle_enforcement; when evaluation runs, use org_decision.applicable and org_decision.evaluated to distinguish participation from a fault. Evaluated bundle_decisions[] entries include the signed revision and digest.

If startup or reload reports a revision mismatch, compare the deployed expected_policy_revision with .manifest.revision from the cosign-verified artifact and with mandatory Rego metadata.policy_revision. Do not bypass the check or retag the image; promote a matching digest/revision tuple.

Where to look next

• API Reference: full error code table.
• Configuration: every YAML/env knob.
• OIDC Issuers: per-provider issuer/JWKS setup.
• Architecture: exact order of checks.
• Open an issue: https://github.com/Depthmark/github-sts/issues