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
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.
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, chooseClone 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 theTrusted entity type
, then clickNext
.In the
Add permissions
step, scroll to the bottom and clickNext
.Give the role an appropriate name and description and click
Create role
.Select your new role.
Click the dropdown for
Add permissions
and selectCreate 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 repositoryBroad 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 thenEdit trust policy
.Go to
Add a principal
in the bottom right corner of the policy editor and clickAdd
.Choose
IAM Roles
as thePrincipal type
and in theARN
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
.Next, add a condition. The
Condition key
should bests:ExternalId
, theQualifier
should beDefault
and theOperator
should beStringEquals
. In theValue
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 thePrincipal
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 inSource 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
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)
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 selectCreate 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.
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 repositoryBroad 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
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
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.