Secrets Reference - AL-Go for GitHub

AL-Go for GitHub uses secrets for authentication to various services. This guide covers all secret types, authentication methods, and best practices.

Secret Locations

Secrets can be defined at three levels in GitHub:

Organizational secrets

Defined at the GitHub organization level and shared with repositories.

For the free GitHub plan, organizational secrets can only be shared with public repositories.

Repository secrets

Defined on individual repositories. Repository secrets override organizational secrets with the same name.

Environment secrets

Defined under GitHub environments, only available during deployment to that environment.

For the free GitHub plan, environments are only available on public repositories.

Azure Key Vault

You can also store secrets in Azure Key Vault. To enable this, create an AZURE_CREDENTIALS secret in GitHub. See Azure_Credentials for details.

Important Warnings

Don’t create secrets that aren’t actually secretAll secrets are masked in workflow logs with ***. Creating secrets with common values like “windows” will break AL-Go functionality by masking legitimate values in workflow outputs.

Use compressed JSON for structured secretsAL-Go uses JSON structures for some secrets. Always use compressed JSON (single line, no formatting). Multi-line JSON causes GitHub to mask individual lines, including curly brackets, breaking AL-Go functionality.Correct:

{"prop":"value","prop2":"value2"}

Incorrect:

{
  "prop": "value",
  "prop2": "value2"
}

Only expose necessary secretsOnly grant repository access to secrets it actually uses. Unnecessary secrets with problematic values can break AL-Go core functionality.

Core Secrets

Azure_Credentials

Connect AL-Go to Azure services for Key Vault access and app signing.

For app signing, the Key Vault must use Premium SKU. Upgrade with:

az keyvault update --set properties.sku.name=premium --name <KeyVaultName> --resource-group <ResourceGroupName>

Required Permissions

Security Model	Read Secrets	Sign Apps
Role Based Access Control (recommended)	Key Vault Secrets User	Key Vault Crypto User + Key Vault Certificate User
Vault Access Policy	Secret permissions: Get, List	Cryptographic Operations: Sign + Certificate permissions: Get

Authentication Methods

{
  "keyVaultName": "MyKeyVault",
  "clientId": "<clientId>",
  "tenantId": "<tenantId>"
}

Federated Credentials Setup:

For Managed Identity: Go to Settings → Federated Credentials
For App Registration: Go to Certificates & Secrets → Federated Credentials
Register your GitHub repository (organization, repository, branch/environment)
AL-Go will request an ID_TOKEN from GitHub as proof of authenticity

Federated credentials are more secure than client secrets - only workflows in the specified branch/environment can authenticate.

AuthContext

Deploy apps to Business Central environments.

For multiple environments, create environment-specific secrets: <EnvironmentName>_AUTHCONTEXT (e.g., QA_AUTHCONTEXT, PROD_AUTHCONTEXT).

Refresh Token (Impersonation)

Allows AL-Go to impersonate a user for 90 days.

{
  "tenantId": "<tenantId>",
  "scopes": "https://api.businesscentral.dynamics.com/",
  "RefreshToken": "<refreshToken>",
  "clientId": "<clientId>"
}

Refresh tokens typically expire after 90 days. You must update the secret with a new refresh token before expiration.

App Registration (Service to Service)

Requires the app to be registered in Business Central with permissions:

D365 AUTOMATION
EXTEN. MGT. - ADMIN

{
  "tenantId": "<tenantId>",
  "scopes": "https://api.businesscentral.dynamics.com/",
  "clientId": "<clientId>"
}

AppSourceContext

Deliver apps to AppSource for validation and publication.

The app registration must be registered in Partner Center with appropriate permissions.

{
  "clientId": "<clientId>",
  "tenantId": "<tenantId>",
  "scopes": "https://api.partner.microsoft.com/.default"
}

Anyone with access to the clientId and clientSecret can publish apps to AppSource on your behalf. Use federated credentials when possible.

StorageContext

Deliver build artifacts to Azure Storage.

Placeholder Variables

Use these placeholders in containerName and blobName:

{project} - Project or repository name
{version} - Version number (with -preview for continuous delivery)
{branch} - Branch name
{type} - Artifact type: apps, testapps, or dependencies

Container names must:

Start and end with lowercase letter or number
Contain only lowercase letters, numbers, or dashes
Have no consecutive dashes
Be 3-63 characters long

Authentication Methods

{
  "storageAccountName": "MyStorageName",
  "clientId": "<clientId>",
  "tenantId": "<tenantId>",
  "containerName": "{project}",
  "blobName": "{version}/{project}-{type}.zip"
}

Security Ranking (Most to Least Secure):

Managed Identity
App Registration (Federated)
App Registration (Client Secret)
SAS Token
Storage Account Key

GitHubPackagesContext

Deliver apps to GitHub Packages and enable automatic dependency resolution.

{
  "token": "<gitHubToken>",
  "serverUrl": "https://nuget.pkg.github.com/mygithuborg/index.json"
}

GitHub App authentication doesn’t support packages. Use a Personal Access Token (Classic or Fine-Grained).

AL-Go automatically uses this feed for dependency resolution across all repositories sharing this secret.

NuGetContext

Deliver apps to custom NuGet feeds (e.g., Azure Artifacts).

{
  "token": "<nuGetToken>",
  "serverUrl": "https://pkgs.dev.azure.com/myorg/apps/_packaging/myrepo/nuget/v3/index.json"
}

Unlike GitHubPackagesContext, this feed is not automatically used for dependency resolution. Add it to trustedNuGetFeeds setting if needed.

GhTokenWorkflow

Personal Access Token for updating AL-Go system files. Required Permissions:

Modify workflows

See the Update AL-Go System Files documentation for detailed setup.

GitSubmodulesToken

Access private Git submodules during build. Required Permissions:

Read access to submodule repositories

Alternatively, use the gitSubmodulesTokenSecretName setting to reference a different secret (e.g., GhTokenWorkflow).

Code Signing Secrets

Certificate URL Method (Legacy)

{
  "CodeSignCertificateUrl": "https://example.com/cert.pfx",
  "CodeSignCertificatePassword": "password123"
}

Custom secret names via settings indirection:

{
  "codeSignCertificateUrlSecretName": "MY_CERT_URL",
  "codeSignCertificatePasswordSecretName": "MY_CERT_PASSWORD"
}

Azure Key Vault Certificate

Store certificate in Azure Key Vault (requires Premium SKU):

Settings in .AL-Go/settings.json

{
  "keyVaultCodesignCertificateName": "my-certificate"
}

Azure Trusted Signing

Configure in settings (no separate secret needed if using Azure_Credentials):

Settings in .AL-Go/settings.json

{
  "trustedSigning": {
    "Account": "my-signing-account",
    "Endpoint": "https://weu.codesigning.azure.net",
    "CertificateProfile": "my-cert-profile"
  }
}

See the Code Signing documentation for detailed setup instructions.

Additional Secrets

LicenseFileUrl

URL to a Business Central license file for builds.

Business Central 22+: The CRONUS demo license is sufficient for most scenarios.Prior to BC 22: Required for AppSource apps or apps with custom object ranges.

Custom secret name via settings:

{
  "licenseFileUrlSecretName": "MY_LICENSE"
}

Admin Center API Credentials

Create online development environments using the Admin Center API.

{
  "tenantId": "<tenantId>",
  "clientId": "<clientId>",
  "clientSecret": "<clientSecret>"
}

Custom secret name:

{
  "adminCenterApiCredentialsSecretName": "MY_ADMIN_CREDS"
}

See Create Online Development Environment for setup details.

Application Insights Connection String

Embed Application Insights connection string in apps.

{
  "applicationInsightsConnectionString": "InstrumentationKey=...;IngestionEndpoint=..."
}

Custom secret name:

{
  "applicationInsightsConnectionStringSecretName": "MY_APPINSIGHTS"
}

AppSource-Specific Secrets

For AppSource apps with Key Vault integration:

{
  "keyVaultCertificateUrl": "https://myvault.vault.azure.net/certificates/mycert",
  "keyVaultCertificatePassword": "password",
  "keyVaultClientId": "<clientId>"
}

Custom secret names:

{
  "keyVaultCertificateUrlSecretName": "MY_KV_CERT_URL",
  "keyVaultCertificatePasswordSecretName": "MY_KV_CERT_PASSWORD",
  "keyVaultClientIdSecretName": "MY_KV_CLIENT_ID"
}

See Enable KeyVault for AppSource App for detailed setup.

Secret Management Best Practices

Use Federated Credentials

Prefer federated credentials over client secrets for better security

Rotate Secrets Regularly

Set expiration dates and rotate secrets before they expire

Limit Secret Scope

Only grant repository access to necessary secrets

Use Azure Key Vault

Centralize secret management with Azure Key Vault

Troubleshooting

Secrets Not Available in Workflows

Check secret scope

Verify the secret is accessible to the repository (organizational secrets need explicit access).

Verify secret name

Ensure the secret name matches exactly (case-sensitive).

Check environment secrets

Environment secrets are only available during deployment to that environment.

JSON Format Errors

If you see curly brackets ({, }) replaced with *** in logs, your JSON secret is not compressed. Recreate the secret as a single-line JSON string.

Refresh Token Expired

Refresh tokens typically expire after 90 days:

Generate a new refresh token
Update the AuthContext secret
Re-run the deployment workflow

Next Steps

Settings Reference

Configure AL-Go settings and behaviors

Workflows

Learn about available workflows

Azure Key Vault Setup

Set up Azure Key Vault integration

Environments

Configure deployment environments

Getting Started

Setup & Configuration

Core Workflows

Development

Deployment

AppSource Publishing

Advanced Topics

Migration

​Secret Locations

​Azure Key Vault

​Important Warnings

​Core Secrets

​Azure_Credentials

​Required Permissions

​Authentication Methods

​AuthContext

​Refresh Token (Impersonation)

​App Registration (Service to Service)

​AppSourceContext

​StorageContext

​Placeholder Variables

​Authentication Methods

​GitHubPackagesContext

​NuGetContext

​GhTokenWorkflow

​GitSubmodulesToken

​Code Signing Secrets

​Certificate URL Method (Legacy)

​Azure Key Vault Certificate

​Azure Trusted Signing

​Additional Secrets

​LicenseFileUrl

​Admin Center API Credentials

​Application Insights Connection String

​AppSource-Specific Secrets

​Secret Management Best Practices

Use Federated Credentials

Rotate Secrets Regularly

Limit Secret Scope

Use Azure Key Vault

​Troubleshooting

​Secrets Not Available in Workflows

​JSON Format Errors

​Refresh Token Expired

​Next Steps

Settings Reference

Workflows

Azure Key Vault Setup

Environments

Build docs developers (and LLMs) love

Secret Locations

Azure Key Vault

Important Warnings

Core Secrets

Azure_Credentials

Required Permissions

Authentication Methods

AuthContext

Refresh Token (Impersonation)

App Registration (Service to Service)

AppSourceContext

StorageContext

Placeholder Variables

Authentication Methods

GitHubPackagesContext

NuGetContext

GhTokenWorkflow

GitSubmodulesToken

Code Signing Secrets

Certificate URL Method (Legacy)

Azure Key Vault Certificate

Azure Trusted Signing

Additional Secrets

LicenseFileUrl

Admin Center API Credentials

Application Insights Connection String

AppSource-Specific Secrets

Secret Management Best Practices

Troubleshooting

Secrets Not Available in Workflows

JSON Format Errors

Refresh Token Expired

Next Steps