While AWS CodeStar is being deprecated in favor of Amazon CodeCatalyst, AWS CodeCommit is seemingly alive and well. It doesn’t have a ton of features and isn’t seeing much development, but it does the job if all you want to do is host a Git repository inside of AWS (with all the typical goodies this entails such as high availability, integration with IAM, etc.).

Properly configuring these CodeCommit repositories locally can be a bit of a pain, though. So, for my own sake (and maybe someone else’s), I figured I’d document some of my learnings.

Authenticating to CodeCommit

There are three different types of credentials that a CodeCommit repository supports for authentication:

  1. IAM credentials
  2. CodeCommit Git credentials
  3. SSH keys

You can use IAM credentials either with the built-in CodeCommit credential helper that comes with the AWS CLI, or an AWS-managed plugin for Git called git-remote-codecommit. The latter requires you to install a new tool, and it’s not clear to me how well it plays with aws-vault and similar tools. The CodeCommit credential helper, on the other hand, is part of the AWS CLI, is easy to set up and requires little maintenance.

Using CodeCommit Git credentials or SSH keys both entail the creation of entirely new credentials and associating them with a specific IAM user. This introduces more long-lived credentials in your life, increases maintenance and is generally more challenging across multiple AWS accounts 1.

I’ve settled on IAM credentials and the CodeCommit credential helper available through the AWS CLI. Everything works as expected without any additional credentials or dependencies, and you can use IAM roles and temporary credentials as long as the IAM principal you’ve configured your shell to use has the necessary privileges.

Local configuration

I configure my local CodeCommit repositories on a per-repository basis because I’m not particularly keen on messing with global settings. I only have a few repositories, so this is currently the approach with the least overhead for my workflow.

Assuming that you already have a CodeCommit repository set up, as well as the AWS CLI installed and configured, this is how you can configure your local repository to use IAM credentials through the CodeCommit credential helper:

  1. Create a new folder to store your CodeCommit Git repository in (e.g., mkdir my-repository)
  2. Initialize the repository (e.g., cd my-repository && git init .)
  3. Configure the local Git repository
    git config --replace-all credential.helper ''
    git config --add credential.helper '!aws codecommit credential-helper $@'
    git config credential.UseHttpPath true
    git remote add origin https://git-codecommit.<region>.amazonaws.com/v1/repos/<repository>

    And you’re off to the races!

A note about macOS

If you’re using macOS you’ll want to make a special note of this line:

git config --replace-all credential.helper ''

The default version of Git on macOS caches credentials in the Keychain Access utility. The temporary credentials created by the CodeCommit helper expires after 15 minutes, and caching these naturally lead to issues when Git tries to retrieve them from the keychain after expiration. By setting this to an empty string we’re overriding any other credential helpers that may have been configured in system or global Git configuration files. The Git configuration command above essentially explicitly turns off Keychain Access, and any other credentials helpers, for the current Git repository without having to modify any global settings. Neat.