BUILD-10632 Improve Vault diagnostic error messages with actionable guidance#72
Merged
jayadeep-km-sonarsource merged 1 commit intomasterfrom Mar 17, 2026
Conversation
…uidance - Extract repeated strings (support channel, repo URLs, debug hint) into constants for maintainability - Add consistent escalation path across all error branches: specific fix → debug-github-actions skill → #ask-squad-eng-xp - Split denied paths into KV (Port self-service portal) vs infrastructure secrets (terraform repo) with plain-language descriptions listing the actual affected paths - Add debug hint with awesome-ai repo link to 4xx auth and denied-paths errors where it was previously missing - Add 5xx server error branch suggesting rerun and status page check Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Contributor
Author
There was a problem hiding this comment.
Pull request overview
Improves the “Diagnose secret access failures” step in the composite Vault action to provide more actionable, user-oriented failure messages and clearer remediation paths when Vault authentication or secret access checks fail.
Changes:
- Extracted reusable message/link constants (support channel, infra repo, self-service portal, debug hint) and added workflow run URL context.
- Refined Vault login failure handling (separate 5xx vs 4xx) with expanded guidance and debug instructions.
- Enhanced denied-path reporting by splitting KV vs non-KV paths and directing users to the appropriate remediation route.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
tomverin
approved these changes
Mar 17, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
BUILD-10632
Why
Error messages in the Vault diagnostic step are terse and developer-facing. Users hitting failures get no remediation steps, no links, and jargon like "KV" or "dynamic secrets" — leading to avoidable support requests in
#ask-squad-eng-xp.What changed
All changes are in
action.yaml, in the "Diagnose secret access failures" step. No changes to the diagnostic logic itself (capability checks, login flow, path parsing).Constants extracted
Repeated strings (
SUPPORT_CHANNEL,TERRAFORM_REPO,PORT_SELF_SERVICE,DEBUG_HINT) are now defined once at the top of the script block for easy maintenance.Error branches — before vs after
#ask-squad-eng-xpCannot diagnose individual secrets — Vault login failed (status). The role "..." may not exist or is misconfigured.Cannot diagnose individual secrets: <error>Vault secrets retrieval failed — N path(s) denied: path1, path2+ a genericcore.infolink to the terraform repo/kv/heuristic. KV paths → Port self-service portal link (user can fix themselves). Non-KV paths → terraform repo link. Lists the actual denied paths under each category.Vault secrets retrieval failed but all paths appear individually accessible. The error may be transient or caused by a different issue.Consistent escalation path
Every error branch now follows: specific remediation action → Claude Code
debug-github-actionsskill (with workflow run URL) →#ask-squad-eng-xpas last resort.Code reordering
secretPathsparsing moved after the auth block — it's not needed if auth fails, and this avoids a confusing "could not parse secret paths" error when the real problem is auth.Behavioral notes
/kv/path heuristic matches all current Vault mount conventions at SonarSource.