docs: Document AUTHCONTEXT secret lookup chain, Key Vault underscore limitation, and GitHub Environment secret scope

[Copilot]

AUTHCONTEXT secret resolution had several undocumented behaviors that caused 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 ::warning:: when a Key Vault lookup is skipped because the secret name contains _. Previously returned $null with zero log output.

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

# After: warning emitted
if ($secret.Contains('_')) {
    Write-Host "::warning::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
  • GitHub Environment secrets are only injected into jobs declaring environment: — the Initialization auth-check job does not have this, so environment-scoped AUTHCONTEXT is invisible there

• Scenarios/RegisterSandboxEnvironment.md and Scenarios/RegisterProductionEnvironment.md — Added notes after the AUTHCONTEXT environment secret setup step clarifying the scope limitation and pointing to the repo-level per-environment naming convention as the alternative.

✅ 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.