Summary

Resolves PREQ-4481 — when hashicorp/vault-action fails with a 403 Forbidden, the logs show all requested secrets but don't indicate which one caused the failure. This forces users to debug by trial-and-error.

This PR adds a diagnostic step that runs only when the Vault secrets step fails. It:

1. Authenticates to Vault using a fresh OIDC token
2. Checks per-path capabilities via sys/capabilities-self (no side effects — does not read actual secrets or generate dynamic credentials)
3. Reports which specific secret path(s) are DENIED vs OK
4. Points the user to the Vault orders repository to fix permissions

Example output

=== Diagnosing Vault secret access failure ===
Role: github-SonarSource-my-repo

  OK      development/kv/data/repox (read)
  DENIED  development/kv/data/slack
  DENIED  development/artifactory/token/SonarSource-my-repo-promoter

To fix, update the Vault policy for this repository:
https://github.com/SonarSource/re-terraform-aws-vault/tree/master/orders

Design decisions

• Zero overhead on success: The diagnostic step only runs when the Vault secrets step fails (continue-on-error: true + if: steps.secrets.outcome == 'failure')
• sys/capabilities-self instead of direct reads: Avoids generating dynamic secrets (Artifactory tokens, GitHub tokens, etc.) as a side effect. Only checks permissions.
• Graceful degradation: If the diagnostic authentication itself fails (e.g., role doesn't exist), the step reports that clearly and still fails the action
• No new dependencies: Reuses actions/github-script (already used in the replace step) and Node.js built-in fetch

Related

• PREQ-4482 — sibling ticket, concrete 403 case from the same reporter that motivated this improvement
• Past tickets with the same debugging pain: PREQ-3261, PREQ-385, PREQ-1145, PREQ-1208, PREQ-248

Test plan

What we tested

• The diagnostic step correctly identifies which secret path(s) cause the 403
• Allowed secrets show OK with their capability (e.g. read)
• Denied secrets show DENIED
• The fix message and link to re-terraform-aws-vault are displayed
• The action still fails with a clear summary (e.g. Vault secrets retrieval failed — 1 path(s) denied: operations/team/re/kv/data/digicert)

How we tested

1. Test repo: sonar-dummy — a repo with known Vault permissions defined in re-terraform-aws-vault/orders/platform-eng-xp-squad.yaml
2. Allowed secret: development/kv/data/slack — sonar-dummy has access
3. Denied secret: operations/team/re/kv/data/digicert — RE team only, sonar-dummy has no access
4. Test workflow: .github/workflows/test-vault-403-diagnostics.yml — requests both secrets to trigger a 403, then runs the diagnostic step

Test workflow run

• sonar-dummy PR #563 — draft PR with the test workflow

• Workflow run 22661709735 — validates batched sys/capabilities-self API and OIDC fix:

  === Diagnosing Vault secret access failure ===
  Role: github-SonarSource-sonar-dummy
  
    OK      development/kv/data/slack (read)
    DENIED  operations/team/re/kv/data/digicert
  
  To fix, update the Vault policy for this repository:
  https://github.com/SonarSource/re-terraform-aws-vault/tree/master/orders
  
  Vault secrets retrieval failed — 1 path(s) denied: operations/team/re/kv/data/digicert
  

Checklist

• Verify the diagnostic output correctly identifies denied vs allowed paths
• Test with a repo that has a known missing secret (sonar-dummy + digicert)
• Verify the action still fails properly (the diagnostic step calls core.setFailed())
• Verify the existing test workflow passes (happy path — valid secrets still work with continue-on-error: true)
• Verify the outputs.vault is still available on success