Skip to main content

Integrating with AWS CodeCommit

Set up a repository and users on AWS CodeCommit to use with Gearset Pipelines

Valerio Chang avatar
Written by Valerio Chang
Updated over 2 weeks ago

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:

  • 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

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.

  1. Navigate to Identity and Access Management (IAM).

  2. Click Users.

  3. 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!

  4. Click Delete.

  5. Type the user name to confirm deletion and click Delete user.

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.

  1. Open the AWS Console, and navigate to CodeCommit. Bookmark this resource.
    ​

  2. Click Create repository.
    ​

  3. Choose a repository name and click Create.
    ​

  4. Add a Readme file if there isn't one already present.

  5. In the Clone URL menu, choose Clone 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.

  1. First, go to Source control and services in the Gearset app.

  2. Click on + Connect to AWS CodeCommit.
    ​

  3. Click Generate External ID for AWS. You will need this when setting up your IAM role's trust policy.

  4. Copy the Gearset IAM Role ARN and the generated External ID for later.

  5. Navigate to Identity and Access Management (IAM) , bookmark this for the future.

  6. Click Roles.

  7. Click Create role to start creating a new IAM role.

  8. Select AWS Account as the Trusted entity type, then click Next.

  9. In the Add permissions step, scroll to the bottom and click Next.

  10. Give the role an appropriate name and description and click Create role.

  11. Select your new role.

  12. Click the dropdown for Add permissions and select Create inline policy.

  13. Choose the JSON option.

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

    1. 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.

    2. 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.

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

      1. $aws_repo_region - region where AWS CodeCommit repository created (i.e. eu-west-1)

      2. $aws_account_number - AWS account identifier number.

      3. $aws_codecommit_repository_name - name of AWS CodeCommit repository

      4. 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": [
        				"*"
        			]
        		}
        	]
        }

      5. 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": [
                        "*"
                    ]
                }
            ]
        }

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

  16. Name the policy and click Create policy.

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

  18. 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.

  19. 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.

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.

  1. Navigate to Identity and Access Management (IAM).
    ​

  2. Click Roles.
    ​

  3. Select the role you've created.
    ​

  4. Copy the role’s ARN.

  5. Now go back to Source control and services in the Gearset app.

  6. Click on + Connect to AWS CodeCommit.
    ​

  7. 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.

  8. 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

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)

  1. Navigate to Identity and Access Management (IAM) in AWS.

  2. Click Users.

  3. Create a new user using the Create user button.

  4. Give the user an appropriate name, then click Next.

  5. Click Next.

  6. Click Create user.

  7. Select your new user.

  8. Click the dropdown for Add permissions and select Create inline policy.

  9. Choose the JSON option.
    ​

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

    1. 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.

    2. 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.

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

      1. $aws_repo_region - region where AWS CodeCommit repository created (i.e. eu-west-1)

      2. $aws_account_number - AWS account identifier number

      3. $aws_codecommit_repository_name - name of AWS CodeCommit repository

      4. 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": [
        				"*"
        			]
        		}
        	]
        }

      5. 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 via HTTPS

  1. Go to Identity and Access Management (IAM) in AWS and select the user you created.

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

  3. Generate the credentials and keep them in a safe place.

  4. Go to Source control and services in the Gearset app.

  5. Select Add new custom Git repository...

  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.

    Note: 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 Integrating with AWS CodeCommit for more details.

  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 Integrating with AWS CodeCommit.

Connecting via SSH

  1. Go to Source control and services in the Gearset app.

  2. Select Add new custom Git repository...

  3. Select the SSH radio button and copy the Public key.

  4. Go to Identity and Access Management (IAM) in AWS and select the user created earlier.

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

  6. Paste the SSH key copied in step 3, and click Upload SSH public key.

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

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

  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:

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

      1. ¹ Enter the 20 character SSH ID copied in step 5

      2. ² The region stated in your SSH repo URL

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

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

  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 Integrating with AWS CodeCommit).

Related Articles
Managing source control connections in Gearset
Getting started with AWS CodeCommit webhooks
Troubleshooting Azure DevOps connection
How to set up a new source control repository
EventBridge configuration for AWS CodeCommit
Did this answer your question?