feat: add helpful error handling for OIDC token failures (#1171)

* feat: add helpful error handling for OIDC token failures

- Catch getIDToken failures specifically and provide actionable solutions
- Display clear instructions for adding required permissions
- Include links to GitHub documentation for OIDC setup

Co-Authored-By: Claude <[email protected]>

* fix: apply pre-commit formatting fixes

- Remove trailing whitespace from action.yaml

Co-Authored-By: Claude <[email protected]>

* Update action.yaml

---------

Co-authored-by: Claude <[email protected]>

Author: korniltsev

actions/get-vault-secrets/action.yaml

@@ -64,7 +64,43 @@ runs:
         VAULT_INSTANCE: ${{ inputs.vault_instance }}
       with:
         script: |
-          const jwt = await core.getIDToken(`vault-github-actions-grafana-${process.env.VAULT_INSTANCE}`);
+          let jwt;
+          try {
+            jwt = await core.getIDToken(`vault-github-actions-grafana-${process.env.VAULT_INSTANCE}`);
+          } catch (error) {
+            core.setFailed(`❌ Failed to get OIDC token: ${error.message}`);
+
+            // Provide helpful suggestions
+            core.error(`
+          🔧 OIDC Token Error - How to Fix:
+
+          This error typically occurs when your workflow lacks proper permissions for OIDC token generation.
+
+          ✅ Solution 1 - Add workflow-level permissions:
+          Add this to the top of your workflow YAML file:
+
+          permissions:
+            id-token: write
+            contents: read
+
+          ✅ Solution 2 - Add job-level permissions:
+          Add this to your specific job:
+
+          jobs:
+            your-job-name:
+              permissions:
+                id-token: write
+                contents: read
+
+          ✅ Solution 3 - Verify repository configuration:
+          - Ensure your repository has OIDC enabled
+          - Check that the Vault OIDC provider is configured for your repository
+
+          📚 More info: https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect
+            `);
+            return;
+          }
+
           core.setSecret(jwt);
           core.setOutput("github-jwt",jwt);