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.

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 Read.me 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 users to connect with Gearset

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

A service user with broad access to CodeCommit resources
Individual user accounts 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 user types, make sure to assign the correct access policy to your service user so they have sufficient access to set up the Pipeline.

Navigate to Identity and Access Management (IAM) , bookmark this for the future.
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 - 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": [
                "*"
            ]
        }
    ]
}

11. The end result will look like this. After you've checked the syntax, click Next.

12. Name the policy and click Create policy.

13. You can now see the permissions in your permission policies.

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 Users
Select the user.
Select Security credentials and then Create access key.
Select Third-party service, then create access key.
Copy the access key and secret access key to a temporary safe location.
Go to Source control and services in the Gearset app.
Click on + Connect to AWS CodeCommit.
In the connection modal, paste all values from 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 Test connection, and it should become Connection succeeded.
Press Connect - you should now see your CodeCommit connection listed in Source control and services.

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

Step 1:

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

Select the user created earlier here.

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.

Connect CodeCommit to Gearset as a custom git repository 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 your AWS code commit.

Select the user created earlier here.

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 clone the SSH URL. Similar to Step 4 here.

Step 9

In Gearset, in the Add new linked Git repository modal paste the repo address that was cloned 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

Edit or fix a user story in progress in pipelines