|
| 1 | +# GitHub Actions Environment Variables Setup |
| 2 | + |
| 3 | +This is a quick reference guide. For complete setup instructions, see [`OPS.md`](../OPS.md#github-actions-aws-oidc-setup). |
| 4 | + |
| 5 | +## Required Secret |
| 6 | + |
| 7 | +The workflow requires one GitHub repository secret: |
| 8 | + |
| 9 | +- **`AWS_ROLE_ARN`**: The ARN of the IAM role that GitHub Actions will assume to push Docker images to ECR |
| 10 | + |
| 11 | +## Setup Steps |
| 12 | + |
| 13 | +### 1. Create AWS IAM Role |
| 14 | + |
| 15 | +**Follow the complete instructions in [`OPS.md`](../OPS.md#github-actions-aws-oidc-setup)** which includes: |
| 16 | +- Creating the OIDC identity provider |
| 17 | +- Creating the IAM role with trust policy |
| 18 | +- Attaching ECR permissions policy |
| 19 | + |
| 20 | +After completing the AWS setup, you'll have an IAM role ARN (typically: `arn:aws:iam::633607774026:role/GitHubActions-ECR-Push`) |
| 21 | + |
| 22 | +### 2. Add GitHub Secret |
| 23 | + |
| 24 | +Add the IAM role ARN as a GitHub repository secret using the GitHub CLI: |
| 25 | + |
| 26 | +```bash |
| 27 | +# Ensure you're authenticated with GitHub CLI |
| 28 | +# If not already authenticated, run: gh auth login |
| 29 | + |
| 30 | +# Set the secret (replace with your actual role ARN if different) |
| 31 | +gh secret set AWS_ROLE_ARN --body "arn:aws:iam::633607774026:role/GitHubActions-ECR-Push" |
| 32 | +``` |
| 33 | + |
| 34 | +**Note**: Make sure you're in the repository directory or specify the repo with `--repo operationcode/back-end`. |
| 35 | + |
| 36 | +### 3. Verify Setup |
| 37 | + |
| 38 | +After adding the secret, the workflow will automatically: |
| 39 | +- Authenticate to AWS using OIDC (no credentials stored) |
| 40 | +- Build Docker images for ARM64 platform |
| 41 | +- Push to ECR with appropriate tags: |
| 42 | + - `:staging` for non-master branches |
| 43 | + - `:prod` for master branch (after CI passes) |
| 44 | + |
| 45 | +## Testing |
| 46 | + |
| 47 | +To test the setup: |
| 48 | + |
| 49 | +1. **Test staging build**: Push to any branch except `master` |
| 50 | + - Should trigger Docker build and push to `:staging` tag |
| 51 | + - Check ECR repository to verify image was pushed |
| 52 | + |
| 53 | +2. **Test production build**: Merge to `master` branch |
| 54 | + - Should run lint, test, security checks first |
| 55 | + - If all pass, should build and push to `:prod` tag |
| 56 | + - Check ECR repository to verify image was pushed |
| 57 | + |
| 58 | +## Troubleshooting |
| 59 | + |
| 60 | +### Build fails with "Error assuming role" |
| 61 | +- Verify the `AWS_ROLE_ARN` secret is set correctly |
| 62 | +- Check that the IAM role exists and has the correct trust policy |
| 63 | +- Ensure the OIDC identity provider is configured |
| 64 | + |
| 65 | +### Build fails with "AccessDenied" to ECR |
| 66 | +- Verify the IAM role has the ECR push policy attached |
| 67 | +- Check that the policy allows access to the correct ECR repository |
| 68 | +- Ensure the repository path matches: `633607774026.dkr.ecr.us-east-2.amazonaws.com/back-end` |
| 69 | + |
| 70 | +### Production build runs even when tests fail |
| 71 | +- This shouldn't happen - production builds depend on `ci-success` job |
| 72 | +- Check that `ci-success` job is properly failing when tests fail |
| 73 | +- Verify branch protection rules if using them |
| 74 | + |
| 75 | +## Additional Resources |
| 76 | + |
| 77 | +- Full AWS OIDC setup: See [`OPS.md`](../OPS.md#github-actions-aws-oidc-setup) |
| 78 | +- GitHub Actions secrets: https://docs.github.com/en/actions/security-guides/encrypted-secrets |
| 79 | +- AWS OIDC with GitHub: https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services |
0 commit comments