AWS CloudFormation Git sync walkthrough

Learn to use Git sync with the following walkthrough. Before you begin, make sure to complete the Git sync prerequisites.

Step 1: Create stack

1. Access the CloudFormation console.

2. Choose Create stack.

3. In the Create stack dashboard, in the Prerequisite - Prepare template panel, confirm that Template is ready is selected.

4. In the Specify template panel, choose Sync from Git.

5. Choose Next to specify stack details.

Step 2: Specify stack details

1. In the Provide a stack name panel, enter a name for your stack. Stack names can include letters (A-Z and a-z), numbers (0-9), and dashes (-).

2. The Stack deployment file has two options:

   • Create the file using the following parameters and place it in my repository.

     Choose this option if you want Git sync to create the stack deployment file and place it in your repository.

   • I am providing my own file in my repository.

     Choose this option if you have created a stack deployment file and added it to your repository.

   For more information, see Stack deployment file.

3. The Template definition repository panel has two options:

   • Choose a linked Git repository

   • Link a Git repository

   If you've already linked a Git repository to CloudFormation, select Choose a linked Git repository and proceed to the next step. Otherwise, perform the following substeps to connect a Git repository:

   1. Choose Link a Git repository.

   2. Choose your Git repository provider from the following:

      • GitHub

      • GitHub Enterprise

      • GitLab

      • Bitbucket

   3. Choose a Connection from the list. If no options appear in the Connection list, go to the Connections console to create a connection to your repository.

4. In the Repository list, select the Git repository that contains your stack template file.

5. In the Branch list, select the branch you'd like Git sync to monitor.

   Note

   Git sync only monitors the selected branch for changes to the CloudFormation template and stack deployment files. Any changes you'd like to apply to your stack must be committed to this branch.

6. For the Deployment file path, specify the full path including the stack deployment file name from the root of your repository branch.

   If CloudFormation is generating the file for you, this is where the file will be committed in your repository. If you are providing the file, this is the location of the file in your repository.

7. Add an IAM role. The IAM role includes permissions that are required for CloudFormation to sync the stack from your Git repository. You can choose New IAM role to generate a new role, or choose Existing IAM role to select an existing role from your CloudFormation account. If you choose to generate a new role, the required permissions are included in the role.

   Note

   For important information about the required permissions and trust policy for Git sync, see Required permissions.

8. For the Template file path, specify the full path from the root of your repository for the stack template file.

9. Add parameters for your stack that you'd like to set from your stack deployment file. Parameters are key-value pairs. For example, to add the port parameter to your stack deployment file:

   1. Choose Add parameter.

   2. For Key, enter port.

   3. For Value, enter 8080.

   4. Repeat the previous steps for all the stack parameters that you want to make available in your stack deployment file.

10. (Optional) Add tags. Tags are key-value pairs that you can use to identify and categorize resources in the stack. To add tags to the stack deployment, follow the same process that you used for adding parameters.

11. Choose Next to continue to Configure stack options.

Step 3: Configure stack options

For information about configuring stack options, see Setting AWS CloudFormation stack options.

When you've completed configuration, choose Next to continue to review and deployment.

Step 4: Review and deploy

1. Review your stack settings and confirm the following:

   • The stack template is configured correctly and set to Sync from Git.

   • The deployment file is configured correctly.

   • The template definition repository is configured correctly, in particular, that the correct Repository and Branch name are selected.

   • The preview of the deployment file is correct and contains the expected parameters and values.

2. Choose Submit to create the stack.

   Important

   A pull request is automatically created in your Git repository when you choose Submit. You must merge this pull request into your Git repository to complete the process. When you merge the pull request, the stack is created and Git sync monitors the CloudFormation template and stack deployment file for changes to update the stack.

Modifying the stack

Having completed the preceding steps, a new stack is created, and CloudFormation is monitoring your Git repository for changes.

To modify the stack, make changes directly to the stack deployment file. Then, commit them to the repository and branch you have configured for the stack in Git sync.

In the CloudFormation dashboard, you can select the stack and choose the Git sync tab to view information about the status of the stack and sync events. For more information, see AWS CloudFormation Git sync status dashboard.