If you use AWS CodeCommit as your source control provider, this doc will help you:
Create a repository to use with Gearset (to populate your repo, see How to set up a source control repository).
Set up the following users on AWS CodeCommit to use Gearset:
A pipelines service user (see An Introduction to Gearset Pipelines).
Individual admins and devs.
Connect your CodeCommit repository to Gearset. There are 3 ways you can connect the repository to Gearset—OAuth, HTTPS or SSH.
Note: Pipelines using a CodeCommit repo must use OAuth.
Completing this guide will result in your team's ability to begin using Gearset Pipelines for Salesforce deployments, while maintaining your AWS CodeCommit repository as your source of truth.
Important note on legacy CodeCommit connections
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 connections using IAM users have been deprecated in Gearset. Existing connections that were created using an access key and secret will continue to work. All new OAuth connections must 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
Optional note: We recommend setting up a new repository (you can seed it with metadata later) as part of your implementation, but this is not required.
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 for 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 for setting up your first Gearset Pipeline.
First, go to Source control and services in the Gearset app.
Click on
+ Connect to AWS CodeCommit
.
Click
Generate External ID for AWS
. You will need this when setting up your IAM role's trust policy.Copy
the GearsetIAM Role ARN
and the generatedExternal ID
for later.Navigate to
Identity and Access Management (IAM)
, bookmark this for the future.Click
Roles
.Click
Create role
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
andpaste
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 to use 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
.
Planning on using the same IAM role for multiple Gearset users?
Then you'll need to include the external ID of each of those users' connections in the trust policy. This includes team-shared connections which have their own external ID (only one per team, though).
You can do this by making the sts:ExternalId
object an array instead.
Before:
"sts:ExternalId": "<gearset-external-id-for-user-1>"
After:
"sts:ExternalId": ["<gearset-external-id-for-user-1>", "<gearset-external-id-for-user-2>", "<gearset-external-id-for-team-shared-connection>"]
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 the Gearset Source control and services page
Note: 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 setting up a Pipeline: A team owner must repeat these steps for the team-owned source control connection, using the service user which has the broad access policy required 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
Go to
Identity and Access Management (IAM)
in AWS and select the user you created.Select
Security Credentials
and scroll down until you findHTTPS Git Credentials
.Generate the credentials and keep them in a safe place.
Go to Source control and services in the Gearset app.
Select
Add new custom Git repository...
In the
Add new linked Git repository
modal, enter the required information and selectTest connection
, and you should then see this change to show that the connection has succeeded.Note: For
Repo URL
in the AWS code commit console, selectRepositories
, you'll then be able to copy the repo URL - ensure you copy the HTTPS URL. See Integrating with AWS CodeCommit for more details.Select
Add repository
and your new repository will then be listed as aCustom git repository
.Note: If you intend to use Pipelines, make sure you create your connection using OAuth, see Integrating with AWS CodeCommit.
Connecting via SSH
Connecting via SSH
Go to Source control and services in the Gearset app.
Select
Add new custom Git repository...
Select the SSH radio button and copy the
Public key
.Go to
Identity and Access Management (IAM)
in AWS and select the user created earlier.Select
Security Credentials
and scroll down until you findSSH public keys
.Paste
the SSH key copied in step 3, and clickUpload SSH public key
.Copy
the 20-digit code from the SSH public key list to keep in a safe place.In AWS go to CodeCommit, select the git repository you are connecting to, and then copy the
Clone SSH
URL.In Gearset, in the
Add new linked Git repository
modalpaste
the repo address that was copied in CodeCommit. Then, make the following changes:Select
Add repository
and your new repository will then be listed as aCustom git repository
.Note: If you intend to use Pipelines, make sure you create your connection using Oauth (see Integrating with AWS CodeCommit).