Skip to main content

​
GitHub Workflows Required Secrets and Variables

This document lists all secrets and repository variables required for GitHub Actions workflows to function correctly.

​
Table of Contents

​
Required Secrets

​
GCP Authentication (Required for Deployments)

​
GCP_WIF_PROVIDER

  • Purpose: Workload Identity Federation provider for keyless GCP authentication
  • Format: projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL/providers/PROVIDER
  • Used By:
    • deploy-gke-staging.yaml
    • deploy-gke-production.yaml
    • release.yaml
  • Setup: 
    # Get your project number
gcloud projects describe YOUR_PROJECT_ID --format="value(projectNumber)"

# Create Workload Identity Pool
gcloud iam workload-identity-pools create github-actions \
  --location=global \
  --display-name="GitHub Actions Pool"

# Create provider
gcloud iam workload-identity-pools providers create-oidc github \
  --location=global \
  --workload-identity-pool=github-actions \
  --display-name="GitHub Provider" \
  --attribute-mapping="google.subject=assertion.sub,attribute.actor=assertion.actor,attribute.repository=assertion.repository" \
  --issuer-uri="https://token.actions.githubusercontent.com"

​
GCP_STAGING_SA_EMAIL

  • Purpose: Service account email for staging deployments
  • Format: staging-deploy@PROJECT_ID.iam.gserviceaccount.com
  • Used By: deploy-gke-staging.yaml
  • Permissions Required:
    • roles/container.developer (GKE deployments)
    • roles/artifactregistry.writer (Docker image push)
    • roles/logging.logWriter (Cloud Logging)
    • roles/monitoring.metricWriter (Cloud Monitoring)
  • Setup: 
    # Create service account
gcloud iam service-accounts create staging-deploy \
  --display-name="Staging Deployment Service Account"

# Grant permissions
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:staging-deploy@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/container.developer"

# Bind to Workload Identity
gcloud iam service-accounts add-iam-policy-binding \
  staging-deploy@YOUR_PROJECT_ID.iam.gserviceaccount.com \
  --role="roles/iam.workloadIdentityUser" \
  --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/github-actions/attribute.repository/YOUR_REPO"

​
GCP_PRODUCTION_SA_EMAIL

  • Purpose: Service account email for production deployments
  • Format: prod-deploy@PROJECT_ID.iam.gserviceaccount.com
  • Used By: deploy-gke-production.yaml, release.yaml
  • Permissions Required: Same as staging SA
  • Setup: Similar to staging SA

​
PyPI Publishing (Required for Releases)

​
PYPI_TOKEN

  • Purpose: API token for publishing packages to PyPI
  • Format: pypi-AgEIcHlwaS5vcmc... (starts with pypi-)
  • Used By: release.yaml
  • Scopes Required: Upload packages
  • Setup:
    1. Go to https://pypi.org/manage/account/token/
    2. Click “Add API token”
    3. Name: “GitHub Actions Release”
    4. Scope: “Entire account” or specific project
    5. Copy token and add to GitHub secrets

​
Required Repository Variables

Configure in: Settings → Secrets and variables → Actions → Variables

​
GCP_PROJECT_ID

  • Purpose: GCP project ID for deployments
  • Example: vishnu-sandbox-20250310
  • Used By: All GCP-related workflows
  • Note: Not a secret, safe to expose in logs

​
GCP_REGION

  • Purpose: GCP region for resources
  • Default: us-central1
  • Used By: Deployment workflows

​
ENABLE_STAGING_AUTODEPLOY

  • Purpose: Enable/disable automatic staging deployments on main push
  • Values: true or false
  • Default: false
  • Used By: deploy-gke-staging.yaml

​
ENABLE_DEV_AUTODEPLOY

  • Purpose: Enable/disable automatic dev deployments
  • Values: true or false
  • Default: false
  • Used By: deploy-gke-dev.yaml (if exists)

​
Optional Secrets

​
Observability and Alerting

​
SLACK_WEBHOOK_URL

  • Purpose: Slack webhook for deployment and failure notifications
  • Format: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXX
  • Used By:
    • observability-alerts.yaml
    • dora-metrics.yaml
  • Setup:
    1. Create Slack app at https://api.slack.com/apps
    2. Enable “Incoming Webhooks”
    3. Add webhook to workspace
    4. Copy webhook URL

​
PAGERDUTY_INTEGRATION_KEY

  • Purpose: PagerDuty integration key for critical alerts
  • Format: 32-character alphanumeric key
  • Used By: observability-alerts.yaml
  • Setup:
    1. Go to Services → your service → Integrations
    2. Add “Events API V2” integration
    3. Copy integration key

​
DATADOG_API_KEY

  • Purpose: Datadog API key for metrics and traces
  • Format: 32-character alphanumeric key
  • Used By: observability-alerts.yaml
  • Setup:
    1. Go to Organization Settings → API Keys
    2. Create new API key: “GitHub Actions”
    3. Copy key

​
Code Coverage

​
CODECOV_TOKEN

  • Purpose: Codecov upload token for private repositories
  • Format: UUID format
  • Used By: ci.yaml
  • Note: Not required for public repositories
  • Setup:
    1. Go to https://codecov.io
    2. Add repository
    3. Copy upload token from repository settings

​
Setup Instructions

​
Quick Setup Checklist

For a new repository or organization:
  • GCP Authentication
    • Create Workload Identity Pool and provider
    • Create staging and production service accounts
    • Bind service accounts to Workload Identity
    • Add GCP_WIF_PROVIDER, GCP_STAGING_SA_EMAIL, GCP_PRODUCTION_SA_EMAIL secrets
    • Add GCP_PROJECT_ID, GCP_REGION variables
  • PyPI Publishing (if releasing packages)
    • Create PyPI API token
    • Add PYPI_TOKEN secret
  • Observability (optional)
    • Create Slack webhook
    • Add SLACK_WEBHOOK_URL secret
    • Set up PagerDuty integration
    • Add PAGERDUTY_INTEGRATION_KEY secret
    • Set up Datadog
    • Add DATADOG_API_KEY secret
  • Deployment Automation (optional)
    • Set ENABLE_STAGING_AUTODEPLOY variable to true
    • Set ENABLE_DEV_AUTODEPLOY variable to true

​
Adding Secrets to GitHub

  1. Navigate to your repository on GitHub
  2. Go to Settings → Secrets and variables → Actions
  3. Click New repository secret
  4. Enter secret name (exactly as shown above)
  5. Paste secret value
  6. Click Add secret
For Organization-level Secrets:
  1. Go to Organization Settings → Secrets and variables → Actions
  2. Click New organization secret
  3. Select repository access (All repositories / Selected repositories)
  4. Add secret

​
Security Best Practices

​
Secret Rotation

Rotate secrets regularly:
  • GCP Service Account Keys: Not applicable (using Workload Identity)
  • PyPI Tokens: Every 6 months or after personnel changes
  • Webhook URLs: After security incidents only
  • API Keys: Every 3-6 months

​
Least Privilege

Service accounts should have minimal permissions: 
# Example: Staging SA only needs GKE and Artifact Registry access
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:staging-deploy@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/container.developer"

# Do NOT grant owner or editor roles

​
Secret Scope

Prefer repository-specific secrets over organization-wide secrets:
  • Easier to track usage
  • Reduced blast radius if compromised
  • Better access control

​
Audit Logging

Monitor secret usage: 
# Check GCP service account activity
gcloud logging read "protoPayload.authenticationInfo.principalEmail:staging-deploy@" \
  --limit=50 \
  --format=json

​
Emergency Response

If a secret is compromised:
  1. Immediately rotate/revoke the secret
  2. Review audit logs for unauthorized usage
  3. Update in GitHub with new value
  4. Document incident for post-mortem
  5. Check for data exposure from unauthorized access

​
Troubleshooting

​
Common Issues

​
”Error: failed to load secret”

Cause: Secret not configured or incorrect name Solution:
  1. Verify secret name matches exactly (case-sensitive)
  2. Check secret is added at repository or organization level
  3. Ensure workflow has correct permissions

​
”Error: Workload Identity authentication failed”

Cause: Misconfigured Workload Identity bindings Solution: 
# Verify binding
gcloud iam service-accounts get-iam-policy \
  staging-deploy@YOUR_PROJECT_ID.iam.gserviceaccount.com \
  --format=json

# Should see principalSet with your repository
# If not, add binding again (see setup instructions above)

​
“Error: Invalid PyPI token”

Cause: Token expired, revoked, or incorrect scope Solution:
  1. Generate new token at https://pypi.org/manage/account/token/
  2. Ensure scope is “Entire account” or includes your package
  3. Update PYPI_TOKEN secret in GitHub

​
Workflow skipped due to missing secret

Cause: Workflow checks if: secrets.X != '' and secret is not set Solution: This is expected behavior for optional secrets. Either:
  1. Add the secret to enable the feature
  2. Leave as-is if feature not needed

​
References

Last Updated: 2025-11-07 Maintained By: DevOps Team Questions: Open an issue or contact the maintainers