AWS CloudFormation Git Sync

Table of Contents

• Overview
• Implementation
• Video Walkthrough of Configuration
• GitHub CodeStar Connection for GitHub.com
• Conclusion
• Resources

Overview

During AWS re:Invent 2023, there were a number of exciting announcements. I am a member of AWS Community Builders and they had a useful list of key announcements for members to reference. One of the items on the list was a new AWS CloudFormation Git Sync feature. Since one of my favorite topics is GitOps, I was intrigued that you could now manage CloudFormation stacks directly from Git. At the time of writing, this feature supports GitHub, GitHub Enterprise, GitLab, and Bitbucket repositories (oddly, AWS CodeCommit is not supported). My initial reaction to this announcement was that, depending on how it was implemented, this could really simplify Infrastructure as Code (IaC) management. I decided that I would create a simple open-source repository on GitHub that I would use to test out the new feature.

The following is a screenshot of what an implementation of this feature currently looks like in the AWS Console:

Implementation

As I started working with the new AWS CloudFormation Git Sync feature, I realized one limiting factor is that there are a number of steps required to set up each stack to be managed by Git. This setup overhead limits the usefulness of this feature. However, if you have just a few key stacks that you want to manage directly from Git, this feature is really nice.

For more complex CloudFormation deployments, I would still recommend using something like AWS CodePipeline to help create and manage stacks, but this new feature is a nice complement to what CodePipeline can do, and I could see the two features working well together. For instance, you could set up Git to manage an initial stack that sets up your main CodePipeline, and then the CodePipeline could do complex stack management from there. Having this feature would have made some of my past IaC implementations a bit less complex.

I prefer to minimize ClickOps as much as possible, so when I developed my solution for this project, I put as much of it as I could into CloudFormation templates. When working through the AWS Console, there are a lot of steps required to set up each stack to be managed by Git. By replacing some of these manual steps with CloudFormation templates, I reduced the chance of human error.

Video Walkthrough of Configuration

I realized that going through how everything worked with AWS CloudFormation Git Sync would be easier in video format versus a long blog post, so I went ahead and recorded a video on YouTube which gives a good overview of how things work with the "cfn-git-sync-boilerplate" repository that I created.

The following is the video that I have posted:

This is my first YouTube overview video, but I do plan to create more. Please feel free to provide constructive feedback in the comments of the YouTube video.

GitHub CodeStar Connection for GitHub.com

One part of the process where it is difficult to avoid ClickOps is with setting up the AWS CodeStar connection with GitHub. Look at this documentation for details on AWS CodeStar Connections.

If you watched the above YouTube video, you will note that you can create a CodeStar connection using a CloudFormation stack, but the connection is only created in a Pending state. In the following steps, I will go over how to complete this connection.

1. You need to navigate to the CodeSuite connections in the AWS Console so that you can see the pending connection:

2. Click on the name of the pending connection in order to get to details about the connection:

3. Click on the button that says Update pending connection. This causes a pop-up window to be launched from GitHub.com which askes you to authorize permissions for the AWS Connector for GitHub:

4. You will then be brought to the AWS Console, you will want to click on the Install a new app button:

5. It will then ask you which repositories the connector should have access to and what are the permissions:

6. In my case, I selected a single repository:

7. Once selected, I had to click on the Install button:

8. I then had to fully authenticate my GitHub account:

9. At this point I was returned to the Connect to GitHub page in the AWS Console:

10. I then clicked the Connect button in the above image, on the main console page, the connection status now changed from Pending to Available:

Conclusion

As the first iteration of a new feature, AWS CloudFormation Git Sync is a step in the right direction. For people who want an easy way to manage their CloudFormation stacks via simple GitOps, this solution allows for clean stack management directly from Git (after the mildly cumbersome initial setup).

For the next iteration of this feature, it would be nice if there would be a way for the Stack Deployment Files to be automatically detected when added to the repository (so that you don’t have to go through the manual configuration steps to link each CloudFormation template to a stack). Regardless, this is a welcome feature which could have a number of practical applications.

Resources

1. Example Git Repository: https://github.com/ngamradt/cfn-git-sync-boilerplate
2. Related YouTube Video: https://youtu.be/u9xsfUCoFS8?si=eZT-oxPOnuSKf49b&t=0
3. Original AWS Announcement: https://aws.amazon.com/about-aws/whats-new/2023/11/aws-cloudformation-git-management-stacks/