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

Actions/ReadSecrets/ReadSecretsHelper.psm1

@@ -157,6 +157,7 @@ function GetKeyVaultSecret {
     }
     if ($secret.Contains('_')) {
         # Secret name contains a '_', which is not allowed in Key Vault secret names
+        Write-Host "::warning::Secret name '$secret' contains an underscore ('_'), which is not supported in Azure Key Vault. The Key Vault lookup will be skipped for this secret. Consider using a dash ('-') instead (e.g., '$($secret.Replace('_','-'))') when storing secrets in Azure Key Vault."
         return $null
     }
 

Scenarios/RegisterProductionEnvironment.md

@@ -9,6 +9,9 @@
 
    ![Publish to MYPROD](https://github.com/user-attachments/assets/fdb05510-2785-483a-b2f3-98a2fe36bfc4)
 
+> [!NOTE]
+> **GitHub Environment secrets** (defined under the environment in GitHub) are only injected into jobs that explicitly declare an `environment:` property. The AL-Go Initialization job that performs the auth check does **not** have this property, so environment-scoped `AUTHCONTEXT` secrets are **not** available at that step. The secret **is** available in the downstream deploy job. If you prefer the secret to be resolved during the initialization auth check as well, define it as a **repository secret** using the naming convention `<EnvironmentName>-AuthContext` (e.g., `MYPROD-AuthContext`) instead of as an environment secret named `AUTHCONTEXT`. See [secrets documentation](secrets.md#AuthContext) for the full lookup order.
+
 1. When running the **Publish to Environment** workflow, you should see that the app is deployed to the **MYPROD** environment only.
 
    ![MYPROD](https://github.com/user-attachments/assets/04dab8af-57b4-4bc3-a0c2-6e6869d8df34)

Scenarios/secrets.md

@@ -58,7 +58,7 @@ If your GitHub organization might have many organizational secrets, please only
 The following is a list of secrets and a brief description:
 
 - [Azure_Credentials](#Azure_Credentials) - Connect to Azure
-- [AuthContext or \<EnvironmentName>\_AuthContext](#AuthContext) - Deploy to an environment
+- [AuthContext, \<EnvironmentName>-AuthContext, or \<EnvironmentName>\_AuthContext](#AuthContext) - Deploy to an environment
 - [AppSourceContext](#AppSourceContext) - Deliver to AppSource
 - [StorageContext](#StorageContext) - Deliver to storage
 - [GitHubPackagesContext](#GitHubPackagesContext) - Deliver to GitHub Packages
@@ -107,7 +107,25 @@ With this setup, you can create a setting called `keyVaultCodesignCertificateNam
 
 ## **AuthContext** -> Deploy to an environment
 
-Whenever AL-Go for GitHub is doing to deploy to an environment, it will need an AuthContext secret. The AuthContext secret can be provided underneath the environment in GitHub. If you are using a private repository in the free GitHub plan, you do not have environments. Then you can create an AuthContext secret in the repository. If you have multiple environments, you can create different AuthContext secrets by using the environment name followed by an underscore and AuthContext (f.ex. **QA_AuthContext**).
+Whenever AL-Go for GitHub deploys to an environment, it needs an AuthContext secret. AL-Go resolves the AuthContext secret by looking up the following secret names **in order**, using the first one that resolves to a non-empty value:
+
+1. **`<EnvironmentName>-AuthContext`** (dash variant, e.g. `QA-AuthContext`) – checked first
+2. **`<EnvironmentName>_AuthContext`** (underscore variant, e.g. `QA_AuthContext`) – checked second
+3. **`AuthContext`** (generic fallback) – checked last
+
+> [!IMPORTANT]
+> **Azure Key Vault users:** Azure Key Vault does not allow underscores (`_`) in secret names. If Azure Key Vault is configured as your secrets provider, any secret whose name contains an underscore will be **skipped** during Key Vault lookup (a warning will be emitted in the workflow log). This means the underscore variant `<EnvironmentName>_AuthContext` will not be found in Azure Key Vault. Use the **dash variant** `<EnvironmentName>-AuthContext` when storing per-environment AuthContext secrets in Azure Key Vault, as dashes are permitted in Key Vault secret names.
+
+> [!WARNING]
+> **Multi-environment and multi-tenant repos:** If neither `<EnvironmentName>-AuthContext` nor `<EnvironmentName>_AuthContext` resolves to a value, AL-Go **silently falls back** to the generic `AuthContext` secret. The workflow log will only show `Using AuthContext secret as AuthContext` — no warning is emitted that a per-environment secret was expected but not found. In repositories with multiple environments (for example, different customer tenants), this means a missing per-environment secret will cause all environments to deploy using the same shared credentials, which may not be the intended behavior. Ensure all environments that require credential isolation have a per-environment `<EnvironmentName>-AuthContext` or `<EnvironmentName>_AuthContext` secret defined.
+
+The AuthContext secret can be provided in the following ways:
+
+- As a **GitHub Environment secret** named `AUTHCONTEXT` under the environment (available in the deploy job when targeting that GitHub Environment)
+- As a **repository or organization secret** named `<EnvironmentName>-AuthContext` or `<EnvironmentName>_AuthContext` (recommended for per-environment isolation)
+- As a **repository or organization secret** named `AuthContext` (generic fallback for all environments)
+
+If you are using a private repository with the free GitHub plan and do not have access to GitHub Environments, use the per-environment naming convention as a repository secret.
 
 ### Managed identity