If you use AWS CodeCommit as your source control provider, or want to, this doc will guide you through the process of:

Creating a repository to use with Gearset (for instructions on populating it see this doc).
Setting up users on AWS CodeCommit to use with Gearset
- for a Pipelines service user
- for individual admins and devs
Connecting your CodeCommit repository to Gearset. There are 3 ways you can connect the repository to Gearset, (OAuth, HTTPS or SSH). If you're setting up a Pipeline you will need to use OAuth.

Completing this setup will allow you to start using Gearset Pipelines for your Salesforce DevOps, and to maintain your AWS CodeCommit repository as your source of truth.

Important information about legacy CodeCommit connections in Gearset

Previously, connecting CodeCommit to Gearset via OAuth was done by creating IAM users with the appropriate permissions, creating an access key for each user and using that access key ID and secret to allow Gearset to perform actions on the user’s behalf.

However, this type of CodeCommit connection will soon be deprecated in Gearset. Existing connections that were created using an access key and secret will continue to work, but all new OAuth connections should be role-based. Setting up this new type of connection in Gearset will require the repository URL (as before) and the ARN of your IAM role as outlined further down.

Transitioning to a role-based CodeCommit connection from a legacy connection

In Gearset, all you will have to do is delete your existing CodeCommit connection on the Source control and services page and then follow the steps further down to create a new one. Once the new connection is set up and your role ARN has been manually approved by Gearset, any jobs set up with the old connection will continue to work.

However, you may also want to clean up your IAM user that was set up for this purpose in AWS.

Navigate to Identity and Access Management (IAM).
Click Users.
Select the user you want to remove. Be absolutely sure that you’ve selected the correct user before deleting, and that you’re not using it for anything else!
Click Delete.
Type the user name to confirm deletion and click Delete user.

Creating a new CodeCommit repository

Note: We recommend setting up a new repository (you can seed it with metadata later) as part of your implementation, but this isn't compulsory.

Open the AWS console, and navigate to CodeCommit. Bookmark this resource.
Click Create repository.
Choose a repository name and click Create.
Add a Readme file if there isn't one already present.
In the Clone URL menu, choose Clone HTTPS and save the URL of the repository, you'll use this later.

Setting up AWS CodeCommit roles to connect with Gearset

Note: you'll notice many of these screenshots refer to a service role, this is because to set up a team shared Pipeline you will need:

A service role with broad access to CodeCommit resources
Individual roles for the admins and devs to contribute their changes to the teams' Pipeline.

These instructions will take you through the process to create both of these role types, make sure to assign the correct access policy to your service role so they have sufficient access to set up the Pipeline.

First, go to Source control and services in the Gearset app.
Click on + Connect to AWS CodeCommit.
Click on the button to generate an External ID. You will need this when setting up your IAM role's trust policy.
Copy the Gearset IAM Role ARN and the generated External ID and keep them safe for later.
Navigate to Identity and Access Management (IAM) , bookmark this for the future.
Click Roles.
Click the Create role button to start creating a new IAM role.
Select AWS Account as the Trusted entity type, then click Next.
In the Add permissions step, scroll to the bottom and click Next.
Give the role an appropriate name and description and click Create role.
Select your new role.
Click the dropdown for Add permissions and select Create inline policy.
Choose the JSON option.

You have a choice of two policies, which you can copy and paste into the policy editor.

The first policy grants the user broad access to your AWS CodeCommit repository, so as Gearset implements new features you won't need to modify this policy - this is the policy you need to use if you are setting up a Pipeline, for the team shared source control connection.

The other policy contains the minimum set of actions that Gearset uses at the time of writing, but this could change as new versions of Gearset are released, so you may need to update the policy from time to time.

In both policies you need to find and replace the following values, to make sure that this user has access to the correct resources.

$aws_repo_region - region where AWS CodeCommit repository created (i.e. eu-west-1)
$aws_account_number - AWS account identifier number
$aws_codecommit_repository_name - name of AWS CodeCommit repository

Broad policy (use for setting up your Pipeline service user):

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Effect": "Allow",
			"Action": [
				"codecommit:Merge*",
				"codecommit:Post*",
				"codecommit:Update*",
				"codecommit:Get*",
				"codecommit:Test*",
				"codecommit:BatchGet*",
				"codecommit:GitPull",
				"codecommit:Create*",
				"codecommit:Put*",
				"codecommit:GitPush",
				"codecommit:DeleteBranch",
				"codecommit:List*",
				"codecommit:Describe*"
			],
			"Resource": [
				"arn:aws:codecommit:$aws_repo_region:$aws_account_number:$aws_codecommit_repository_name"
			]
		},
		{
			"Effect": "Allow",
			"Action": [
				"codecommit:ListRepositories"
			],
			"Resource": [
				"*"
			]
		}
	]
}

Policy containing minimum set of rights (correct as of July 2024):

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "codecommit:GetRepository",
                "codecommit:GetCommit",
                "codecommit:GetBranch",
                "codecommit:GitPull",
                "codecommit:GitPush",
                "codecommit:ListBranches",
                "codecommit:CreateBranch",
                "codecommit:CreatePullRequest",
                "codecommit:CreateCommit",
                "codecommit:PutRepositoryTriggers",
                "codecommit:TestRepositoryTriggers",
                "codecommit:ListPullRequests",
                "codecommit:GetPullRequestApprovalStates",
                "codecommit:GetPullRequest",
                "codecommit:UpdatePullRequestTitle",
                "codecommit:UpdatePullRequestDescription",
                "codecommit:UpdatePullRequestStatus",
                "codecommit:GetCommentsForPullRequest",
                "codecommit:PostCommentForPullRequest",
                "codecommit:MergePullRequestByThreeWay",
                "codecommit:MergePullRequestByFastForward",
                "codecommit:GetMergeOptions",
                "codecommit:GetDifferences",
                "codecommit:DescribePullRequestEvents"
            ],
            "Resource": [
      "arn:aws:codecommit:$aws_repo_region:$aws_account_number:$aws_codecommit_repository_name"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "codecommit:ListRepositories"
            ],
            "Resource": [
                "*"
            ]
        }
    ]
}

The end result will look like this. After you've checked the syntax, click Next.
Name the policy and click Create policy.
You can now see the permissions in your permission policies.
Now click on Trust relationships and then Edit trust policy.
1. Go to Add a principal in the bottom right corner of the policy editor and click Add.
2. Choose IAM Roles as the Principal type and in the ARN box enter the Gearset Role ARN that was copied from the Source control and services page in the Gearset app in Step 4.
  
  Then click Add principal.
3. Next, add a condition. The Condition key should be sts:ExternalId, the Qualifier should be Default and the Operator should be StringEquals. In the Value field, paste your External ID that was copied from the Source control and services page in the Gearset app in Step 4.

If your Gearset account's data storage location is in the USA region for example, the JSON representing your trust policy should look like this. If your Gearset team has a different storage location, then the gearset-code-commit role included in the Principal roles will have a different account ID.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": [
                    "arn:aws:iam::<your-aws-account-id>:root",
                    "arn:aws:iam::157764733222:role/gearset-code-commit"
                ]
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "sts:ExternalId": "<your-gearset-external-id>"
                }
            }
        }
    ]
}

Check the syntax and then click Update policy.

Connecting AWS CodeCommit to Gearset

Connect CodeCommit to Gearset via OAuth (recommended)

Note:

All team members need to connect their CodeCommit users to the Gearset team.

Navigate to Identity and Access Management (IAM).
Click Roles.
Select the role you've created.
Copy the role’s ARN.
Now go back to Source control and services in the Gearset app.
Click on + Connect to AWS CodeCommit.
In the connection modal, paste the URL and role ARN from the previous steps, ensuring that in the URL field you paste the complete link to your git repository, found here. Make sure that this is the repository URL and not the page address from your web browser.
Press Connect - you should now see your CodeCommit connection listed in Source control and services.

At this point, your connection has been created but will not work immediately. Because this type of OAuth connection uses inter-organization STS, your IAM role will need to be included in Gearset’s role assumption policy before the connection will work.

The Gearset team will be automatically notified when you establish your connection in the app and we will get in touch about completing the connection set up as soon as possible.

If you are setting up a Pipeline: one of the team owners will need to repeat these steps for the team owned connection, make sure that you use your service user with the broad access policy to create this connection.

Connect CodeCommit to Gearset as a custom git repository via HTTPS or SSH

CodeCommit connections via OAuth in Gearset now use IAM role acquisition rather than IAM user credentials. However, if you would like to create a custom git connection to a CodeCommit repository, then you will need to create a user in AWS instead of a role for this purpose.

The instructions below give details on how to create an IAM user as a required step for setting up a custom git connection and also on the specific steps for HTTPS setup and SSH setup, depending on your preference.

Create an IAM user for custom git setup (HTTPS or SSH)

Navigate to Identity and Access Management (IAM) in AWS.
Click Users.
Create a new user using the Create user button.
Give the user an appropriate name, then click Next.
Click Next.
Click Create user.
Select your new user.
Click the dropdown for Add permissions and select Create inline policy.
Choose the JSON option.

You have a choice of two policies, which you can copy and paste into the policy editor.

The first policy grants the user broad access to your AWS CodeCommit repository, so as Gearset implements new features you won't need to modify this policy.

The other policy contains the minimum set of actions that Gearset uses at the time of writing, but this could change as new versions of Gearset are released, so you may need to update the policy from time to time.

Broad policy:

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Effect": "Allow",
			"Action": [
				"codecommit:Merge*",
				"codecommit:Post*",
				"codecommit:Update*",
				"codecommit:Get*",
				"codecommit:Test*",
				"codecommit:BatchGet*",
				"codecommit:GitPull",
				"codecommit:Create*",
				"codecommit:Put*",
				"codecommit:GitPush",
				"codecommit:DeleteBranch",
				"codecommit:List*",
				"codecommit:Describe*"
			],
			"Resource": [
				"arn:aws:codecommit:$aws_repo_region:$aws_account_number:$aws_codecommit_repository_name"
			]
		},
		{
			"Effect": "Allow",
			"Action": [
				"codecommit:ListRepositories"
			],
			"Resource": [
				"*"
			]
		}
	]
}

Policy containing minimum set of rights (correct as of July 2024):

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "codecommit:GetRepository",
                "codecommit:GetCommit",
                "codecommit:GetBranch",
                "codecommit:GitPull",
                "codecommit:GitPush",
                "codecommit:ListBranches",
                "codecommit:CreateBranch",
                "codecommit:CreatePullRequest",
                "codecommit:CreateCommit",
                "codecommit:PutRepositoryTriggers",
                "codecommit:TestRepositoryTriggers",
                "codecommit:ListPullRequests",
                "codecommit:GetPullRequestApprovalStates",
                "codecommit:GetPullRequest",
                "codecommit:UpdatePullRequestTitle",
                "codecommit:UpdatePullRequestDescription",
                "codecommit:UpdatePullRequestStatus",
                "codecommit:GetCommentsForPullRequest",
                "codecommit:PostCommentForPullRequest",
                "codecommit:MergePullRequestByThreeWay",
                "codecommit:MergePullRequestByFastForward",
                "codecommit:GetMergeOptions",
                "codecommit:GetDifferences",
                "codecommit:DescribePullRequestEvents"
            ],
            "Resource": [
      "arn:aws:codecommit:$aws_repo_region:$aws_account_number:$aws_codecommit_repository_name"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "codecommit:ListRepositories"
            ],
            "Resource": [
                "*"
            ]
        }
    ]
}

The end result will look like this. After you've checked the syntax, click Next.
Name the policy and click Create policy.
You can now see the permissions in your permission policies.

Connecting via HTTPS

Step 1

Go to Identity and Access Management (IAM) in AWS.

Select the user you created.

Step 2

Select Security Credentials and scroll down until you find HTTPS Git Credentials

Step 3

Generate the credentials and keep them in a safe place

Step 4

Go to Source control and services in the Gearset app

Step 5

Select ADD NEW CUSTOM GIT REPOSITORY...

Step 6

In the Add new linked Git repository modal, enter the required information and select Test connection, and you should then see this change to show that the connection has succeeded

For Repo URL in the AWS code commit console, select Repositories, you'll then be able to copy the repo URL - ensure you copy the HTTPS URL. See here for more details

Step 7

Select Add repository and your new repository will then be listed as a Custom git repository

Note: If you intend to use Pipelines make sure you create your connection using Oauth, see details here.

Connecting via SSH

Step 1

Go to Source control and services in the Gearset app

Step 2

Select ADD NEW CUSTOM GIT REPOSITORY...

Step 3

Select the SSH radio button and copy the Public key

Step 4

Go to Identity and Access Management (IAM) in AWS

Select the user created earlier.

Step 5

Select Security Credentials and scroll down until you find SSH public keys

Step 6

Paste the SSH key copied in Step 3 and click Upload SSH public key.

Step 7

Copy the 20-digit code from the SSH public key list to keep in a safe place.

Step 8

In AWS go to CodeCommit, select the git repository you are connecting to, and then copy the Clone SSH URL.

Step 9

In Gearset, in the Add new linked Git repository modal paste the repo address that was copied in CodeCommit. Then make the following changes:

¹ssh_keyID@git-codecommit.²us-region.amazonaws.com³:/v1/repos/your_git_repo

¹ Enter the 20 character SSH ID copied in step 5

² The region stated in your SSH repo URL

³ A colon needs to be added after .com in the URL

Click test connection to check to see if it is all set up correctly

Step 10

Select Add repository and your new repository will then be listed as a Custom git repository

Note: If you intend to use Pipelines make sure you create your connection using Oauth, see details here.

Managing source control connections in Gearset

Getting started with AWS CodeCommit webhooks

How to set up a new source control repository

EventBridge configuration for the users using AWS CodeCommit

Creating webhooks for AWS CodeCommit