AWS CloudFormation Git sync concepts and terminology

This section introduces fundamental Git sync concepts and terms.

Git sync overview

The following brief overview explains how Git sync works and how to use it. For a complete tutorial, see the AWS CloudFormation Git sync walkthrough.

• Use CodeConnections to connect a Git provider to CloudFormation. In this guide, the connection is created this through the Connections console. You can alternatively create the connection with the AWS CLI. Git sync supports GitHub, GitHub Enterprise, GitLab, and Bitbucket.

• Provide a CloudFormation template that defines your stack and add it to your repository. This template file is monitored. CloudFormation updates the stack automatically when changes are committed to it.

• In the CloudFormation console, create a new stack and choose Sync from Git to configure your stack with Git sync support. You'll specify the repository and branch you want CloudFormation to monitor, and specify the CloudFormation template in your repository that defines the stack.

• During configuration, you can either provide your own stack deployment file from your repository, or have Git sync generate one for you. The stack deployment file contains parameters and values that configure the resources in your stack. This stack deployment file is monitored. CloudFormation updates the stack automatically when changes are committed to it.

• Git sync creates a pull request in your repository to sync your stack with the CloudFormation template file and stack deployment file. If Git sync generates the stack deployment file for you, it's submitted to your repository by Git sync.

• Merge the pull request to your repository so that CloudFormation provisions the stack, configures it with your deployment parameters, and begins monitoring your repository for changes.

• Because CloudFormation is monitoring your repository, the changes you commit to the template file and the stack deployment file are detected, and the stack is automatically updated.

• In the CloudFormation console, you can see information about the status of your Git sync configuration for the stack, and a history of commits applied to the stack. The console also provides tools for reconfiguring Git sync and troubleshooting issues.

Stack deployment file

A stack deployment file is a JavaScript Object Notation (JSON) or YAML standard formatted file that contains parameters and values that manage your CloudFormation stack. It is monitored for changes. When changes to the file are committed to the repository, the associated stack is automatically updated.

The stack deployment file contains a key-value pair and two dictionaries:

• template-file-path

  This is the full repository path for the CloudFormation template file. The template file declares the resources for the CloudFormation stack associated with this deployment file.

• parameters

  The parameters dictionary contains key-value pairs that configure the resources in the stack. A stack deployment file can have up to 50 parameters.

• tags

  The tags dictionary contains optional key-value pairs that you can use to identify and categorize resources in the stack. A stack deployment file can have up to 50 tags.

You can provide your own stack deployment file, or have Git sync create one for you and automatically submit a pull request to your repository. You can manage the parameters and tags by editing the stack deployment file and committing changes to the repository.

The following is an example of a Git sync stack deployment file:

template-file-path: ./fargate-srvc/my-stack-template.yaml

parameters: 
    image: public.ecr.aws/lts/nginx:latest
    task_size: x-small
    max_capacity: 5
    port: 8080
    env: production
tags:
    cost-center: '123456'
    org: 'AWS'

CloudFormation template file

A template file contains a declaration of the AWS resources that make up a CloudFormation stack. The template is stored as a JavaScript Object Notation (JSON) or YAML standard formatted file. You can create and edit templates with Application Composer, or in any text editor. With Git sync, the template file is stored in your Git repository and referenced by the stack deployment file. You can manage the stack by editing the template file and committing changes to the repository.

For more information, see Working with CloudFormation templates.

Template definition repository

The template definition repository is the Git repository that is linked to CloudFormation through Git sync. The repository is monitored for changes to the CloudFormation template and stack deployment file. When you commit changes to the file, the associated stack is updated automatically.

Important

When you configure the template definition repository in the Git sync console, select the correct repository and branch from the Git connection. Git sync only monitors the configured repository and branch for changes to the CloudFormation template and the stack deployment file.

Git sync supports GitHub, GitHub Enterprise, GitLab, and Bitbucket repositories.