AAAA Stack

Angular, ASP.NET, AWS and Azure AD

Setting up GitHub Actions Build and Deploy Infrastructure

⚠️⚠️⚠️ Following this steps might incur costs in AWS ⚠️⚠️⚠️

Please ensure you delete the resources afterwards if they are not required.

Overview

As part of CI/CD infrastructure, we will setup

Prerequiste

Install and setup AWS CLI and configure the necesarry permissions to create/ update cloudformation stack and create IAM role and permissions.

Refer to AWS CLI Getting Started Guide for detailed instructions on installing and configuring the AWS Command Line Interface (CLI).

Alternarively you can sign into your AWS Console and use CloudShell. It comes pre-prepared with everything you need to run AWS CLI commands.

⚠️ For the below commands, If you are using PowerShell, replace the backslashes \ in the commands with backticks ` for line continuation.

Setup GitHub OIDC Provider

⚠️ This only needs to be created once per AWS account. If you already have this in your AWS account, you can skip this step.

OpenID Connect (OIDC) allows your GitHub Actions workflows to access resources in Amazon Web Services (AWS), without needing to store the AWS credentials as long-lived GitHub secrets.

1. Create OpenID Connect Provider Command

aws iam create-open-id-connect-provider \
  --url https://token.actions.githubusercontent.com \
  --client-id-list sts.amazonaws.com

Sample Output

{
  "OpenIDConnectProviderArn": "arn:aws:iam::111111111111:oidc-provider/token.actions.githubusercontent.com"
}

Note the output arn. This will be required as input for the next step.

List Existing OpenID Connect Providers

To view an existing OpenID Connect Provider for GitHub, use the following command:

aws iam list-open-id-connect-providers

2. Setup ECR Repository and IAM Roles for the Build and Deploy workflows

In this step, we will be creating:

ECR Repository (AWS::ECR::Repository)

IAM Role for GitHub Actions Build (AWS::IAM::Role)

IAM Role for GitHub Actions Deploy (AWS::IAM::Role)

We will create the above resoures using a cloudformation yaml file.

❓ Why use CloudFormation instead of CDK?

This setup is needed only once or rarely. It’s a manual step to bootstrap the CI/CD workflows.

Using CloudFormation YAML keeps it simple and allows execution in AWS CloudShell without extra dependencies.

Replace Placeholders with values in the below commands

Before running the commands to create or update the CloudFormation stack, replace the placeholders with your actual values.

⚠️ If you are using PowerShell, replace the backslashes \ in the commands with backticks ` for line continuation.

CloudFormation File

The CloudFormation file can be found here, aws/github-actions-infrastructure.yaml

ℹ️ If you are using AWS CloudShell, upload this file using the CloudShell -> Actions -> Upload File menu.

Create Stack

aws cloudformation create-stack \
  --stack-name <your stack name> \
  --template-body file://github-actions-infrastructure.yaml \
  --capabilities CAPABILITY_NAMED_IAM \
  --parameters \
    ParameterKey=GitHubActionsOIDCProviderArn,ParameterValue=<your OpenID Connect Provider Arn>
    ParameterKey=GitHubOrg,ParameterValue=<your github org name> \
    ParameterKey=GitHubRepo,ParameterValue=<your github repository name>

Wait for the stack to be created. You can check the status of the stack with,

aws cloudformation describe-stacks --stack-name <your stack name> --query "Stacks[0].StackStatus"

ℹ️ To update an existing stack, you can use the above command replacing create-stack with update-stack.

View Stack

aws cloudformation describe-stacks --stack-name <your stack name> --query "Stacks[0].Outputs"

Sample CloudFormation Output

[
    {
        "OutputKey": "GitHubActionsBuildRoleArn",
        "OutputValue": "arn:aws:iam::111111111111:role/aaaa-stack-GitHubActions-Build-Role",
        "Description": "Build Role ARN used in GitHub Actions Secret, AWS_BUILD_ROLE_ARN_TO_ASSUME"
    },
    {
        "OutputKey": "GitHubActionsDeployRoleArn",
        "OutputValue": "arn:aws:iam::111111111111:role/aaaa-stack-GitHubActions-Deploy-Role",
        "Description": "Deploy Role ARN used in GitHub Actions Secret, AWS_DEPLOY_ROLE_ARN_TO_ASSUME"
    },
    {
        "OutputKey": "ECRRepositoryUri",
        "OutputValue": "111111111111.dkr.ecr.ap-southeast-2.amazonaws.com/aaaa-stack",
        "Description": "URI of the ECR Repository"
    }
]

CloudFormation Outputs

The CloudFormation template provides the following outputs that can be used in your GitHub Actions workflows:

To delete the stack

aws cloudformation delete-stack --stack-name <your stack name>

3. Setup secrets in your Github Repository

ℹ️ You can login into your GitHub account and manually setup the secrets in your UI or you can use the GitHub CLI.

4. Build

You can trigger the GitHub Actions Build Workflow either manually or by pushing your commit.

4. Deploy

The application deployment uses AWS CDK V2 for defining cloud infrastructure in code and provisioning it through AWS CloudFormation.

This stack uses TypeScript.

4.1 CDK Bootstrap

Before deploying your app in an AWS Account, We need to bootstrap the CDK Environment. This only needs to be the the very first time we deploy to an AWS Account.

Refer to Bootstrap your environment for use with the AWS CDK for more details and customisation options.

One of the most important aspect of this process is deciding how you want to configure your deploy role and permissions. Refer to Setting Up Deploy Roles and Permissions for a more detailed discussion on this topic.

4.2 GitHub Workflow

You can trigger the GitHub Actions Deploy Workflow manually either through the GitHub Web or CLI.

Deploy workflow file is located at https://github.com/sravimohan/aaaa-stack/blob/main/.github/workflows/deploy.yml

Further Reading