Skip to main content

​
Why GitHub Environments?

GitHub Environments allow you to securely separate deployments between staging and production.

Security

Store environment-specific secrets and variables

Protection

Require approvals for sensitive environments

Isolation

Clearly separate staging and production deployments

Flexibility

Update settings without changing code

​
Required Environments

Set up your environments in your GitHub repository, we will use two in this guide:
  • Branch: staging
  • Protection: Optional (review recommended)
  • Purpose: Pre-production testing
  • Branch: production
  • Protection: Required reviewers + branch protection
  • Purpose: Live production environment

​
Variable Hierarchy

Understanding GitHub Actions variable precedence:
  1. Repository Variables (lowest precedence) - Shared across all environments
  2. Environment Variables (highest precedence) - Override repository variables
  3. AWS Secrets Manager - Environment variables fetched dynamically during build
# Repository variable:
APP_NAME: your-app-name  # Used in all environments

# Environment variable (if set):
APP_NAME: your-app-name-dev  # Would override repository variable for this environment

# Environment-specific secret ARN:
ENV_VARS_SECRET_ARN: arn:aws:secretsmanager:us-east-1:123456789:secret:staging/your-app-name/cicd-env-ABC123

​
Step-by-Step Setup

​
1. Create GitHub Environments

  1. Open your repository in GitHub
  2. Go to Settings → Environments
  3. Click New environment
  4. Create: staging and production

​
2. Configure Repository Variables

Go to Settings → Secrets and variables → Actions → Variables and add: 
# Application Configuration
APP_NAME: your-app-name

# Manifests Repository (shared across environments)
MANIFEST_REPO_PK_SSM_NAME: /infrastructure/development/deployKey/deployer/repo/manifests/private_key
MANIFEST_REPO_SSH_URL: [email protected]:your-org/manifests.git
MANIFEST_REPO_ROOT_FOLDER: manifests

​
3. Configure Environment-Specific Variables

For each environment, go to Environment → Variables and add: 
# AWS Configuration
AWS_DEPLOYER_ROLE_ARN: arn:aws:iam::ACCOUNT_ID:role/deployer_staging_your-app-name

# ECR Repository
ECR_REPOSITORY: staging/frontend/your-app-name

# Environment Variables Secret
ENV_VARS_SECRET_ARN: arn:aws:secretsmanager:us-east-1:ACCOUNT_ID:secret:staging/your-app-name/cicd-env-ABC123

​
4. Configure Environment Secrets

For each environment, at Environment → Secrets, add: 
# Notifications
SLACK_HOOK: https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK

​
5. Set Up Protection Rules

​
Staging Environment

  • Deployment branches: staging
  • Required reviewers: 1 (optional)
  • Wait timer: None

​
Production Environment

  • Branches: production
  • Required reviewers: 2+ (recommended)
  • Wait timer: 5 minutes (optional)

​
AWS Secrets Manager Configuration

Environment variables are stored in AWS Secrets Manager.

​
Secret Name Pattern

{environment}/{application}/cicd-env

​
Example Secret Values

VITE_ENV=staging
VITE_SENTRY_ENABLED=true
VITE_STICKY_SUB_DOMAIN=your-app-staging
# ... other staging-specific values

​
Deployment Flow

  • Automatic Deployments
    • Push to staging → Deploys to staging environment
    • Push to production → Deploys to production (with approvals)
  • Manual Deployments
    • Trigger deployments via GitHub Actions UI
    • Useful for hotfixes or rollbacks

​
Required AWS Resources

The CI/CD pipeline needs to update your manifests repository during deployments.
To enable this, it fetches an SSH private key stored as an AWS SSM (Systems Manager) parameter.
  • /infrastructure/development/deployKey/deployer/repo/manifests/private_key → SSH key used by the pipeline to push changes into the manifests repo
If you are using Fast Foundation, all of the resources below will be created automatically and will already be available in AWS.
  • deployer_staging_your-app-name
  • deployer_production_your-app-name
Required Permissions: Each role needs access to:
  • ECR (push/pull images)
  • Secrets Manager (read environment variables)
  • SSM (read SSH keys)
  • staging/frontend/your-app-name
  • production/frontend/your-app-name
  • staging/your-app-name/cicd-env (Staging environment variables)
  • production/your-app-name/cicd-env (Production environment variables)

​
Security Best Practices

CI/CD Best Practices
  • Use least privilege IAM roles for each environment
  • Store environment variables in AWS Secrets Manager (encrypted)
  • Require approvals for production deployments
  • Protect the production branch from direct pushes

​
Next Steps

Once CI/CD is configured, continue to Monitor Deployment to track and verify rollouts.

​
Troubleshooting

  • Verify AWS deployer role ARN
  • Ensure the role has required permissions
  • Confirm trust policy allows GitHub OIDC federation
  • Check ARN in environment variables
  • Verify secret exists in AWS Secrets Manager
  • Confirm role permissions allow secret read
  • Verify ECR repository URL and region
  • Ensure role has ECR permissions
  • Confirm repository exists
  • Validate SSH URL and SSM key parameter
  • Check role can access SSM key
  • Ensure repo is accessible via SSH