How to set up the AWS CodeCommit integration

The AWS CodeCommit integration connects the CodeCommit repositories of your AWS account to LingoHub, so you can import your resource files and push the translations back to your repository. This guide covers giving LingoHub access to your AWS account, creating an AWS CodeCommit project, and what works differently from other Git providers.

Please note: CodeCommit has no app to install. You give LingoHub access through AWS Identity and Access Management (IAM), either with an IAM role that LingoHub assumes (recommended) or with the access key of an IAM user.

Before you start

In LingoHub, you need permission to manage Plugins & Integrations in your workspace.
In AWS, you need permission to create IAM policies and roles (or users) in the AWS account your repositories belong to.
Know the AWS region of your repositories, for example eu-central-1. An authentication works with the repositories of one region. For repositories in several regions, add one authentication per region.

Step 1: Create a permissions policy in AWS

In the IAM console, create a policy that allows exactly what LingoHub does in your repositories. Replace the region, the account ID, and the repository name with your own:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ListRepositories",
      "Effect": "Allow",
      "Action": "codecommit:ListRepositories",
      "Resource": "*"
    },
    {
      "Sid": "SynchronizeRepository",
      "Effect": "Allow",
      "Action": [
        "codecommit:GetRepository",
        "codecommit:ListBranches",
        "codecommit:GetBranch",
        "codecommit:CreateBranch",
        "codecommit:DeleteBranch",
        "codecommit:MergeBranchesByFastForward",
        "codecommit:GetFolder",
        "codecommit:GetFile",
        "codecommit:GetDifferences",
        "codecommit:CreateCommit",
        "codecommit:ListPullRequests",
        "codecommit:GetPullRequest",
        "codecommit:CreatePullRequest"
      ],
      "Resource": "arn:aws:codecommit:eu-central-1:123456789012:my-repository"
    }
  ]
}

To allow several repositories, list each repository ARN under Resource, or use arn:aws:codecommit:eu-central-1:123456789012:* for all repositories of the region. codecommit:ListRepositories cannot be limited to a repository: LingoHub needs it to list your repositories when you create a project.

Step 2: Connect AWS CodeCommit with an IAM role (recommended)

With a role, LingoHub never holds a long-lived secret of your AWS account. It asks AWS for temporary credentials that last one hour, keeps them in memory only, and requests new ones when they run out.

Open LingoHub, click your workspace name in the top-left corner, and choose Plugins & Integrations from the Administration menu.
Locate the AWS CodeCommit card and click Manage.
Click Add new authentication.
Enter a Name and the AWS region of your repositories, and choose IAM role as the Authentication method. LingoHub shows LingoHub’s AWS account ID and the External ID of your workspace. Keep the dialog open.
In the IAM console, create a role. Choose AWS account as the trusted entity type, select Another AWS account, and enter LingoHub’s AWS account ID. Select Require external ID and enter the external ID from LingoHub.
Attach the policy from step 1, give the role a name, for example LingoHubCodeCommit, and create it.
Copy the ARN of the role, paste it into Role ARN in LingoHub, and click Create.

The trust policy of the role then looks like this, with LingoHub’s AWS account ID and your external ID filled in:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "AWS": "arn:aws:iam::LINGOHUB_ACCOUNT_ID:root" },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": { "sts:ExternalId": "YOUR_EXTERNAL_ID" }
      }
    }
  ]
}

Please note: The trust policy has to require exactly your workspace’s external ID with StringEquals. A role ARN is not a secret, and the external ID is what keeps other LingoHub workspaces out of your role. LingoHub therefore refuses a role whose trust policy also accepts other external IDs, for example a policy without the external ID condition, with StringEqualsIfExists, or with a wildcard such as space_*.

What LingoHub checks when you add a role

When you click Create, or change the role of an existing authentication, LingoHub assumes the role five times:

once with your workspace’s external ID, which has to succeed, and
four times with external IDs that are not yours: none at all, the ID of another workspace, and two IDs that differ from yours in one character. All four have to be refused.

In your AWS CloudTrail, you see the successful AssumeRole call from LingoHub’s AWS account. The four refused attempts are recorded in LingoHub’s AWS account, which makes the calls, so they do not appear as failed calls in yours.

Alternative: Connect with an access key

In the IAM console, create an IAM user for LingoHub, attach the policy from step 1, and create an access key for the user.
In LingoHub, open Plugins & Integrations, click Manage on the AWS CodeCommit card, and click Add new authentication.
Enter a Name and the AWS region, choose Access key as the Authentication method, enter the Access key ID and the Secret access key, and click Create.

LingoHub stores the access key encrypted. When you rotate the key in AWS, update the authentication in LingoHub with the new key.

Create an AWS CodeCommit project in LingoHub

Go to Projects and click Create.
Enter a Project name, select AWS CodeCommit under Select project category, and click Continue.
Select your authentication, then the Repository and the Branch you want to synchronize. If you have not connected AWS CodeCommit yet, click Create new authentication to do it from here.
Complete the remaining steps and create the project.

To change the settings of the integration later, see How to manage project repository integration.

How LingoHub notices changes in your repository

CodeCommit cannot notify LingoHub when something changes, the way GitHub or GitLab do with webhooks. Instead, LingoHub checks your connected CodeCommit repositories about every two minutes:

With Pull when commits arrive on a connected branch, a push to a connected branch is imported within a few minutes, not immediately.
With Enable branching, branches created or deleted in the repository are created or removed in LingoHub, like with other Git providers.

For these settings, see How to configure automatic Pull and Push settings for Git integrations.

Pushing translations to AWS CodeCommit

You push translations with a Direct push or a Pull request, as with other Git providers. CodeCommit has a few limits of its own:

A file larger than 6 MB cannot be pushed. The sync reports which file is too large.
CodeCommit accepts at most 100 files and about 6 MB of changes in one commit. A push that changes more is committed in several commits on a temporary branch named lingohub/push-…, and your branch is then moved to the last of them in one step. Your branch receives either all files or none, and its history shows one commit per batch. LingoHub deletes the temporary branch afterwards, and never imports branches whose names start with lingohub/.
If someone pushes to the branch while LingoHub is pushing, LingoHub does not overwrite their commits: the push fails, or LingoHub repeats it on top of the new commits.

Please note: CodeCommit cannot move a branch only if it still points to the commit LingoHub expects. For a push that needs several commits, LingoHub checks the branch right before it moves it. If someone resets the branch to an older commit in the fraction of a second between that check and the move, the move brings back the commits the reset removed. Avoid force-resetting a branch while LingoHub pushes a large update to it. Pushes that fit into one commit are not affected.

Troubleshooting

LingoHub could not assume this role. Check that the trust policy of the role names LingoHub’s AWS account ID and requires your workspace’s external ID, exactly as shown in the dialog.
This role’s trust policy also lets LingoHub in with other external IDs. Change the condition to StringEquals with exactly your workspace’s external ID, without wildcards.
The IAM role has to belong to your own AWS account. The ARN points to a role in LingoHub’s AWS account. Enter the ARN of the role you created in your own account.
IAM roles cannot be checked at the moment. AWS did not answer in time. Try again a little later.
Your repository is missing from the list. Check that the authentication uses the region the repository is in, and that the policy allows codecommit:ListRepositories.

Need more help?

Couldn't find what you were looking for? Reach out to our team at [email protected], and we will gladly assist you.