GitHub Secrets Configuration Guide

This document outlines all required GitHub secrets for CI/CD deployment of the Engram platform.

Required Secrets

Azure Authentication

Secret Name	Description	How to Get
`AZURE_CREDENTIALS`	Service principal JSON for Azure authentication	See Creating Service Principal

Azure Resources

Secret Name	Description	How to Get
`AZURE_KEY_VAULT_URL`	Key Vault URI (e.g., `https://engram-env-kv.vault.azure.net/`)	From Azure Portal or Bicep output
`AZURE_STATIC_WEB_APPS_API_TOKEN`	Static Web Apps deployment token	From Azure Portal → Static Web App → Manage deployment token
`API_URL`	Backend API URL (e.g., `https://engram-api.azurecontainerapps.io`)	From Container App FQDN
`WS_URL`	WebSocket URL (same as API_URL but `ws://` or `wss://`)	From Container App FQDN
`TEMPORAL_HOST`	Temporal gRPC endpoint (e.g., `temporal-server.engram-env-aca.region.azurecontainerapps.io:7233`)	From Temporal Container App

Optional Notifications

Secret Name	Description	How to Get
`SLACK_WEBHOOK_URL`	Slack webhook for deployment notifications	Create Slack Incoming Webhook

Creating Service Principal

Using Azure CLI

# Login to Azure
az login

# Set variables
SUBSCRIPTION_ID=$(az account show --query id -o tsv)
RESOURCE_GROUP="engram-rg"
SP_NAME="engram-github-actions"

# Create service principal with contributor role
az ad sp create-for-rbac \
  --name $SP_NAME \
  --role contributor \
  --scopes /subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP \
  --sdk-auth

# Output will be JSON like:
# {
#   "clientId": "...",
#   "clientSecret": "...",
#   "subscriptionId": "...",
#   "tenantId": "...",
#   ...
# }

Using Azure Portal

Go to Azure Active Directory → App registrations
Click New registration
Name: engram-github-actions
Click Register
Go to Certificates & secrets → New client secret
Copy the Value (this is your clientSecret)
Copy the Application (client) ID (this is your clientId)
Go to Subscriptions → Select your subscription → Access control (IAM)
Click Add → Add role assignment
Role: Contributor
Assign access to: Service principal
Select your app registration

Format for GitHub Secret

The AZURE_CREDENTIALS secret should be the entire JSON output from az ad sp create-for-rbac:

{
  "clientId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "clientSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "subscriptionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "activeDirectoryEndpointUrl": "https://login.microsoftonline.com",
  "resourceManagerEndpointUrl": "https://management.azure.com/",
  "activeDirectoryGraphResourceId": "https://graph.windows.net/",
  "sqlManagementEndpointUrl": "https://management.core.windows.net:8443/",
  "galleryEndpointUrl": "https://gallery.azure.com/",
  "managementEndpointUrl": "https://management.core.windows.net/"
}

Setting Secrets in GitHub

Via GitHub Web UI

Go to your repository: https://github.com/zimaxnet/engram
Click Settings → Secrets and variables → Actions
Click New repository secret
Enter the secret name and value
Click Add secret

Via GitHub CLI

# Install GitHub CLI if needed
# brew install gh (macOS)
# or download from https://cli.github.com

# Login
gh auth login

# Set secrets
gh secret set AZURE_CREDENTIALS --body "$(cat azure-credentials.json)"
gh secret set AZURE_KEY_VAULT_URL --body "https://engram-env-kv.vault.azure.net/"
gh secret set API_URL --body "https://engram-api.azurecontainerapps.io"
gh secret set WS_URL --body "wss://engram-api.azurecontainerapps.io"
gh secret set TEMPORAL_HOST --body "temporal-server.engram-env-aca.eastus.azurecontainerapps.io:7233"

Environment-Specific Secrets

For staging/production environments, you can set secrets at the environment level:

Go to Settings → Environments
Create environments: staging, production
Add secrets to each environment
The workflow will use environment-specific secrets when environment: staging or environment: production is specified

Verifying Secrets

After setting secrets, verify they’re accessible:

# Check if secrets are set (names only, not values)
gh secret list

Security Best Practices

Never commit secrets to code - Always use GitHub Secrets
Rotate secrets regularly - Update service principal passwords quarterly
Use least privilege - Service principal should only have access to required resources
Use environment-specific secrets - Separate staging and production credentials
Audit access - Regularly review who has access to secrets

Troubleshooting

“Resource not accessible by integration”

Ensure service principal has Contributor role on the resource group
Check that AZURE_CREDENTIALS JSON is valid
Verify subscription ID matches

“Key Vault access denied”

Ensure service principal has “Key Vault Secrets User” role on Key Vault
Check Key Vault access policies (if using access policies instead of RBAC)

“Container App deployment failed”

Verify Container Apps Environment exists
Check that image is pushed to container registry
Ensure service principal has “Contributor” role on Container Apps

Next Steps

After setting all secrets:

Run the deployment workflow manually via GitHub Actions
Monitor the workflow logs for any errors
Verify resources are created in Azure Portal
Test the deployed endpoints