Back to notes
• 3 min read

GitHub Connection with CloudFormation

Git Sync and CodePipeline both need a way to reach your GitHub repositories. A CodeConnection handles that. It authorizes AWS to access your GitHub account so CloudFormation can watch for changes and pipelines can pull source code.

The Resource

The entire template is one resource: an AWS::CodeConnections::Connection.

AWSTemplateFormatVersion: '2010-09-09'
Description: GitHub CodeConnection for CI/CD pipelines.

Resources:
  SharedGitHubConnection:
    Type: AWS::CodeConnections::Connection
    Properties:
      ConnectionName: github-org-connection
      ProviderType: GitHub

ConnectionName is a label that shows up in the AWS console. Pick something descriptive.

ProviderType: GitHub tells AWS this connection targets GitHub. Other providers exist (Bitbucket, GitLab), but this series uses GitHub.

One connection covers all your repos. You do not need a separate connection per stack or per pipeline.

Deploying the Stack

This is the one stack you deploy manually. Every other stack in this series uses Sync from Git, but Sync from Git itself needs a connection to function. You cannot use it to deploy the connection it depends on.

  1. Go to CloudFormation > Stacks > Create stack > With new resources (standard).
  2. Select Choose an existing template, then Upload a template file, and upload infra.yaml.
  3. Enter a stack name (e.g. connection-stack).
  4. On the Configure stack options page, leave the Permissions / IAM role field blank. This is a manual deployment, so CloudFormation uses your own IAM permissions. No service role is needed.
  5. Review and submit.

CloudFormation creates the connection in Pending status. The stack reaches CREATE_COMPLETE, but the connection is not usable yet. You need to complete the handshake with GitHub.

Completing the Connection

After the stack finishes:

  1. Go to Developer Tools > Settings > Connections in the AWS console.
  2. Select the pending connection (github-org-connection).
  3. Click Update pending connection.
  4. A popup asks you to install the AWS Connector for GitHub app on your GitHub account. Install it and grant access to the repos you want to deploy.
  5. Authorize the connection.
  6. The connection status changes to Available.

Once available, Git Sync and CodePipeline can both use this connection to access your repositories.

The Export

The template exports the connection ARN so other stacks can import it without passing it as a parameter.

Outputs:
  ExportedConnectionArn:
    Value: !Ref SharedGitHubConnection
    Export:
      Name: Example-GitHubConnectionArn

Site stacks reference the connection with !ImportValue Example-GitHubConnectionArn. This keeps stacks loosely coupled. No ARNs in deployment files, no parameters to maintain. If you ever recreate the connection, the export updates and dependent stacks pick up the new value on their next deployment.