docs: Document AUTHCONTEXT secret lookup chain and Key Vault underscore limitation

[Copilot]

❔What, Why & How

AUTHCONTEXT secret resolution had several undocumented behaviors that could cause silent wrong-credential deployments with no log evidence: the dash variant was never mentioned, Key Vault silently dropped underscore secrets, and the generic fallback gave no warning.

Code change

• Actions/ReadSecrets/ReadSecretsHelper.psm1: Emit a warning when a Key Vault lookup is skipped because the secret name contains _. Previously returned $null with zero log output. The warning is now emitted via OutputWarning from Actions/.Modules/DebugLogHelper.psm1 instead of a raw Write-Host call.

# Before: silent null return
if ($secret.Contains('_')) {
    return $null
}

# After: warning emitted via OutputWarning
if ($secret.Contains('_')) {
    OutputWarning "Secret name '$secret' contains an underscore ('_'), which is not supported in Azure Key Vault. ..."
    return $null
}

Documentation changes

• Scenarios/secrets.md — Rewrote the AuthContext section to document:
  • Full three-step lookup chain in explicit precedence order: {envName}-AuthContext → {envName}_AuthContext → AuthContext
  • Azure Key Vault rejects underscore names → use the dash variant for KV-stored secrets
  • Generic AuthContext fallback is silent; in multi-tenant repos this can deploy with the wrong credentials
• Scenarios/RegisterSandboxEnvironment.md and Scenarios/RegisterProductionEnvironment.md — Removed inaccurate notes about GitHub Environment secret scope at the Initialization auth-check step; the auth check only runs for unknown environment names (not found as a GitHub Environment or in settings), so properly configured GitHub Environments are unaffected.

✅ Checklist

• Add tests (E2E, unit tests)
• Update RELEASENOTES.md
• Update documentation (e.g. for new settings or scenarios)
• Add telemetry

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Bug]: AUTHCONTEXT secret resolution undocumented -- silent Key Vault underscore failure, undocumented dash variant, silent org-level fallback trap, GitHub Environment secrets invisible at auth-check step</issue_title>
<issue_description>## AL-Go version

v8.2

Describe the issue

There are five related problems with AUTHCONTEXT secret resolution that together create silent wrong-environment deployments with no errors and no warnings. Each problem is individually confusing; together they are a reliability and security hazard in multi-environment and multi-tenant repos. I am documenting all five here as a single issue because fixing any one of them in isolation without fixing the others would still leave users in a broken state.

---

Finding 1: The full lookup chain is undocumented -- the dash variant is never mentioned

Both Templates/Per Tenant Extension/.github/workflows/CICD.yaml (line 351) and Templates/Per Tenant Extension/.github/workflows/PublishToEnvironment.yaml (line 90) declare:

getSecrets: '{envName}-AuthContext,{envName}_AuthContext,AuthContext'

The PowerShell resolution logic in PublishToEnvironment.yaml lines 100-106 then evaluates them in this exact order:

"$($envName)-AuthContext", "$($envName)_AuthContext", "AuthContext" | ForEach-Object {
    if (!($authContext)) {
        if ($secrets."$_") {
            Write-Host "Using $_ secret as AuthContext"
            $authContext = $secrets."$_"
            $secretName = $_
        }
    }
}

The dash variant {envName}-AuthContext is tried first and is the highest-priority lookup. It is never mentioned anywhere in the documentation. Scenarios/secrets.md documents only <EnvironmentName>_AuthContext (underscore). A user reading the documentation has no way to know the dash variant exists, let alone that it takes precedence.

This matters practically because the dash variant is the only one of the three that works correctly with Azure Key Vault (see Finding 2 below).

---

Finding 2: Azure Key Vault silently skips all underscore secrets -- {env}_AuthContext silently returns null

Actions/ReadSecrets/ReadSecretsHelper.psm1 lines 158-161:

if ($secret.Contains('_')) {
    # Secret name contains a '_', which is not allowed in Key Vault secret names
    return $null
}

When Azure Key Vault is configured as the secrets provider, any requested secret name containing an underscore is immediately returned as $null. No error is thrown. No warning is written to the log. No indication is given that the lookup was skipped.

The consequence: the documented pattern <EnvironmentName>_AuthContext is silently non-functional when Azure Key Vault is in use. A user who reads Scenarios/secrets.md, creates a Key Vault secret named MY-UAT_AuthContext, and triggers a deployment to MY-UAT will get no error. The workflow log will not mention that the Key Vault lookup was skipped. The workflow silently falls through to the generic AuthContext fallback.

The dash variant {env}-AuthContext does work with Key Vault because dashes are permitted in Key Vault secret names. This is never documented.

---

Finding 3: The generic AuthContext fallback is a silent cross-environment credential trap

When neither {env}-AuthContext nor {env}_AuthContext resolves to a value, AL-Go silently falls back to the generic AuthContext secret. The only log evidence of this is the message Using AuthContext secret as AuthContext. There is no warning that this is a fallback, no indication that a per-environment secret was expected but not found, and no indication that the credentials being used may not correspond to the target environment.

In organizations that define AUTHCONTEXT at the org level and share it with all repositories (a common pattern for product repos), every environment in every repo that lacks a per-environment secret will silently deploy using the org-level credential.

In a multi-tenant PTE scenario this creates a security isolation failure:

• A TenantApps repo has environments CUSTOMER-A-UAT and CUSTOMER-B-UAT
• Neither has a per-environment AuthContext secret defined
• The org-level AUTHCONTEXT belongs to Customer A's BC service account
• A developer triggers Publish To Environment targeting CUSTOMER-B-UAT
• AL-Go resolves to the org-level AUTHCONTEXT (Customer A's credentials) with no warning
• The workflow reports success; the log says "Using AuthContext secret as AuthContext"
• No error is thrown and no credential mismatch is flagged

In regulated industries where BC tenant isolation is a compliance requirement, this silent fallback is particularly dangerous.

---

Finding 4: GitHub Environment secrets are invisible at the auth-check initialization step

In both CICD.yaml and...

• Fixes [Bug]: AUTHCONTEXT secret resolution undocumented -- silent Key Vault underscore failure, undocumented dash variant, silent org-level fallback trap, GitHub Environment secrets invisible at auth-check step #2153

---

📍 Connect Copilot coding agent with Jira, Azure Boards or Linear to delegate work to Copilot in one click without leaving your project management tool.

[spetersenms]

There is a pre-commit failure. Make sure all required checks pass.

[Copilot]

There is a pre-commit failure. Make sure all required checks pass.

Fixed in a6dcd29. The pre-commit failure was an mdformat violation — the ordered list items 2. and 3. in secrets.md needed to be written as 1. per the spec. Also removed the remaining incorrect GitHub Environment secret note from RegisterProductionEnvironment.md while at it.

[spetersenms]

@copilot take a look at the 2 ai review comments. If you agree, fix accordingly.

[Copilot]

@copilot take a look at the 2 ai review comments. If you agree, fix accordingly.

Addressed in 3bf917f. I agreed with both AI review points and updated:

• ReadSecretsHelper.psm1 warning text to say the requested secret must be renamed or mapped (instead of implying the example name alone is enough).
• Scenarios/secrets.md to document the underscore-in-environment-name Key Vault limitation and mapping requirement in the relevant AuthContext guidance.

[spetersenms]

@copilot seems pre-commit failed. Fix it.

[Copilot]

@copilot seems pre-commit failed. Fix it.

Fixed in 2ae21b5. The pre-commit failure was caused by an accidentally committed testResults.xml artifact that hooks kept rewriting (EOF/line-ending). I removed it from the branch.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

Suppressed comments (2)

Scenarios/secrets.md:125

• GitHub repository and organization secret names cannot contain - (only alphanumeric characters and underscores are accepted), so users cannot create the documented <EnvironmentName>-AuthContext secret in either scope. Reserve the dash variant for Azure Key Vault/mapped secrets and document the underscore variant for GitHub secrets.

- As a **repository or organization secret** named `<EnvironmentName>-AuthContext` or `<EnvironmentName>_AuthContext` (recommended for per-environment isolation; for Azure Key Vault, use names without underscores or configure secret-name mappings)

testResults.xml:1

• This is a machine-generated Pester run artifact, containing runner-specific absolute paths, runtime versions, timestamps, and timings. Committing it does not add test coverage and will leave stale/churning output in source control; delete the file and add assertions to a *.Test.ps1 file if the new warning needs verification.

<?xml version="1.0" encoding="utf-8" standalone="no"?>

[spetersenms]

@copilot pre-commit still fails.

[Copilot]

@copilot pre-commit still fails.

Fixed in e6def6a. The end-of-file-fixer hook was failing because testResults.xml was still tracked in git (the previous "remove" commit only modified its content rather than removing it). Removed the file from git tracking with git rm --cached and added testResults.xml to .gitignore so it won't be re-committed.