Configure Github Actions

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:

Staging

Branch: staging
Protection: Optional (review recommended)
Purpose: Pre-production testing

Production

Branch: production
Protection: Required reviewers + branch protection
Purpose: Live production environment

Variable Hierarchy

Understanding GitHub Actions variable precedence:

Repository Variables (lowest precedence) - Shared across all environments
Environment Variables (highest precedence) - Override repository variables
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

Open your repository in GitHub
Go to Settings → Environments
Click New environment
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: git@github.com: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

# AWS Configuration
AWS_DEPLOYER_ROLE_ARN: arn:aws:iam::ACCOUNT_ID:role/deployer_production_your-app-name

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

# Environment Variables Secret
ENV_VARS_SECRET_ARN: arn:aws:secretsmanager:us-east-1:ACCOUNT_ID:secret:production/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

VITE_ENV=production
VITE_SENTRY_ENABLED=true
VITE_STICKY_SUB_DOMAIN=your-app
# ... other production 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

SSM Parameters

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.

IAM Roles

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)

ECR Repositories

staging/frontend/your-app-name
production/frontend/your-app-name

AWS Secrets Manager

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

Permission Denied in GitHub Actions

Verify AWS deployer role ARN
Ensure the role has required permissions
Confirm trust policy allows GitHub OIDC federation

Secret Not Found

Check ARN in environment variables
Verify secret exists in AWS Secrets Manager
Confirm role permissions allow secret read

ECR Push/Pull Errors

Verify ECR repository URL and region
Ensure role has ECR permissions
Confirm repository exists

Manifest Repository Access Issues

Validate SSH URL and SSM key parameter
Check role can access SSM key
Ensure repo is accessible via SSH

Introduction & Key Concepts

AWS SSO Setup

IaC Management

User Management

Application Creation

ArgoCD UI

Workshops

Why GitHub Environments?

Security

Protection

Isolation

Flexibility

Required Environments

Variable Hierarchy

Step-by-Step Setup

1. Create GitHub Environments

2. Configure Repository Variables

3. Configure Environment-Specific Variables

4. Configure Environment Secrets

5. Set Up Protection Rules

Staging Environment

Production Environment

AWS Secrets Manager Configuration

Secret Name Pattern

Example Secret Values

Deployment Flow

Required AWS Resources

Security Best Practices

Next Steps

Troubleshooting

​Why GitHub Environments?

Security

Protection

Isolation

Flexibility

​Required Environments

​Variable Hierarchy

​Step-by-Step Setup

​1. Create GitHub Environments

​2. Configure Repository Variables

​3. Configure Environment-Specific Variables

​4. Configure Environment Secrets

​5. Set Up Protection Rules

​Staging Environment

​Production Environment

​AWS Secrets Manager Configuration

​Secret Name Pattern

​Example Secret Values

​Deployment Flow

​Required AWS Resources

​Security Best Practices

​Next Steps

​Troubleshooting

Why GitHub Environments?

Required Environments

Variable Hierarchy

Step-by-Step Setup

1. Create GitHub Environments

2. Configure Repository Variables

3. Configure Environment-Specific Variables

4. Configure Environment Secrets

5. Set Up Protection Rules

Staging Environment

Production Environment

AWS Secrets Manager Configuration

Secret Name Pattern

Example Secret Values

Deployment Flow

Required AWS Resources

Security Best Practices

Next Steps

Troubleshooting