Menu
AWS CodeCommit
User Guide (API Version 2015-04-13)

Setup Steps for HTTPS Connections to AWS CodeCommit Repositories on Linux, OS X, or Unix

Before you can connect to AWS CodeCommit for the first time, you must complete the initial configuration steps. This topic walks you through the steps to set up your computer and AWS profile, connect to an AWS CodeCommit repository, and clone that repository to your computer, also known as creating a local repo. If you're new to Git, you might also want to review the information in Where Can I Learn More About Git?.

Step 1: Initial Configuration for AWS CodeCommit

Follow these steps to set up an AWS account, create and configure an IAM user, and install the AWS CLI.

To create and configure an IAM user for accessing AWS CodeCommit

  1. Create an AWS account by going to http://aws.amazon.com and choosing Sign Up.

  2. Create an IAM user, or use an existing one, in your AWS account. Make sure you have an access key ID and a secret access key associated with that IAM user. For more information, see Creating an IAM User in Your AWS Account.

    Tip

    AWS CodeCommit requires AWS Key Management Service. If you are using an existing IAM user, make sure there are no policies attached to the user that expressly deny the AWS KMS actions required by AWS CodeCommit. For more information, see Encryption.

  3. Sign in to the Identity and Access Management (IAM) console at https://console.aws.amazon.com/iam/.

  4. In the IAM console, in the navigation pane, choose Policies, and from the list of policies, choose AWSCodeCommitFullAccess.

  5. On the Policy Details page, choose the Attached Entities tab, and then choose Attach.

  6. On the Attach Policy page, select the check box next to the IAM user you just created, and then choose Attach Policy.

    Tip

    You can attach this policy to any IAM user who requires full access to all AWS CodeCommit features or any IAM group whose users require full access. To learn more about sharing access to repositories with other groups and users, see Share an AWS CodeCommit Repository.

To install and configure the AWS CLI

  1. On your local machine, download and install the AWS CLI. This is a prerequisite for interacting with AWS CodeCommit from the command line. For more information, see Getting Set Up with the AWS Command Line Interface.

    Note

    AWS CodeCommit works only with AWS CLI versions 1.7.38 and later. To determine which version of the AWS CLI you have installed, run the aws --version command.

    To upgrade an older version of the AWS CLI to the latest version, follow the instructions in Uninstalling the AWS CLI, and then follow the instructions in Installing the AWS Command Line Interface.

  2. Run this command to verify the AWS CodeCommit commands for the AWS CLI are installed:

    aws codecommit help

    This command should return a list of AWS CodeCommit commands similar to the following:

    . . .
    AVAILABLE COMMANDS
    
           o create-branch
    
           o create-repository
    
           o credential-helper
    . . .        
  3. Configure the AWS CLI with the configure command, as follows:

    aws configure

    When prompted, specify the AWS access key and AWS secret access key of the IAM user you will use with AWS CodeCommit. Also, be sure to specify the us-east-1 region when prompted for the default region name. AWS CodeCommit works with this region only. When prompted for the default output format, specify json. For example:

    AWS Access Key ID [None]: Type your target AWS access key ID here, and then press Enter
    AWS Secret Access Key [None]: Type your target AWS secret access key here, and then press Enter
    Default region name [None]: Type us-east-1 here, and then press Enter
    Default output format [None]: Type json here, and then press Enter

    For more information about IAM, access keys, and secret keys, see How Do I Get Credentials? and Managing Access Keys for IAM Users.

Step 2: Install Git

To work with files, commits, and other information in AWS CodeCommit repositories, you must install Git on your local machine. AWS CodeCommit supports Git versions 1.7.9 and later.

To install Git, we recommend websites such as Git Downloads.

Note

Git is an evolving, regularly updated platform. Occasionally, a feature change might affect the way it works with AWS CodeCommit. If you encounter issues with a specific version of Git and AWS CodeCommit, review the information in Troubleshooting.

Step 3: Set Up the Credential Helper

  1. From the terminal, use Git to run git config, specifying the use of the Git credential helper with the AWS credential profile, and enabling the Git credential helper to send the path to repositories:

    git config --global credential.helper '!aws codecommit credential-helper $@'
    git config --global credential.UseHttpPath true

    Tip

    The credential helper will use the default AWS credential profile or the Amazon EC2 instance role. You can specify a profile to use, such as CodeCommitProfile, if you have created a specific AWS credential profile to use with AWS CodeCommit:

    git config --global credential.helper '!aws --profile CodeCommitProfile codecommit credential-helper $@'    

    If your profile name contains spaces, make sure you enclose the name in quotation marks (").

    You can configure profiles per repository instead of globally by using --local instead of --global.

    The Git credential helper writes the following value to ~/.gitconfig:

    [credential]    
        helper = !aws --profile CodeCommitProfile codecommit credential-helper $@
        UseHttpPath = true

    Important

    If you want to use a different IAM user on the same local machine for AWS CodeCommit, you must run the git config command again and specify a different AWS credential profile.

  2. Run git config --global --edit to verify the preceding value has been written to ~/.gitconfig. If successful, you should see the preceding value (in addition to values that may already exist in the Git global configuration file). To exit, typically you would type :q, and then press Enter.

    If you experience problems after you configure your credential helper, see Troubleshooting AWS CodeCommit.

    Important

    If you are using OS X, use the following steps to ensure the credential helper is configured correctly.

  3. If you are using OS X, use HTTPS to connect to an AWS CodeCommit repository. After you connect to an AWS CodeCommit repository with HTTPS for the first time, subsequent access will fail after about fifteen minutes. The default Git version on OS X uses the Keychain Access utility to store credentials. For security measures, the password generated for access to your AWS CodeCommit repository is temporary, so the credentials stored in the keychain will stop working after about 15 minutes. To prevent these expired credentials from being used, you must either:

    • Install a version of Git that does not use the keychain by default.

    • Configure the Keychain Access utility to not provide credentials for AWS CodeCommit repositories.

    1. Open the Keychain Access utility. (You can use Finder to locate it.)

    2. Search for git-codecommit.us-east-1.amazonaws.com. Highlight the row, open the context menu or right-click it, and then choose Get Info.

    3. Choose the Access Control tab.

    4. In Always allow access by these applications, choose git-credential-osxkeychain, and then choose the minus sign to remove it from the list.

      Note

      After removing git-credential-osxkeychain from the list, you will see a pop-up dialog whenever you run a Git command. Choose Deny to continue. If you find the pop-ups too disruptive, here are some alternate options:

      • Connect to AWS CodeCommit using SSH instead of HTTPS. For more information, see For SSH Connections on Linux, OS X, or Unix.

      • In the Keychain Access utility, on the Access Control tab for git-codecommit.us-east-1.amazonaws.com, choose the Allow all applications to access this item (access to this item is not restricted) option. This will prevent the pop-ups, but the credentials will eventually expire (on average, this takes about 15 minutes) and you will see a 403 error message. When this happens, you must delete the keychain item in order to restore functionality.

      • Install a version of Git that does not use the keychain by default.

Step 4: Connect to the AWS CodeCommit Console and Clone the Repository

If an administrator has already sent you the name and connection details for the AWS CodeCommit repository, you can skip this step and clone the repository directly.

  1. Open the AWS CodeCommit console at https://console.aws.amazon.com/codecommit.

  2. Choose the repository you want to connect to from the list. This opens the Settings page for that repository.

    Note

    If you see a Welcome page instead of a list of repositories, there are no repositories associated with your AWS account. To create a repository, see Create an AWS CodeCommit Repository or follow the steps in the Git with AWS CodeCommit Tutorial tutorial.

  3. Copy the HTTPS URL to use when connecting to the repository.

  4. Open a terminal and from the /tmp directory, use the URL to clone the repository with the git clone command. For example, to clone a repository named MyDemoRepo to a local repo named my-demo-repo:

    git clone https://git-codecommit.us-east-1.amazonaws.com/v1/repos/MyDemoRepo my-demo-repo

    For more information about how to connect to repositories, see Connect to the AWS CodeCommit Repository by Cloning the Repository.

Next Steps

You have completed the prerequisites. Follow the steps in the Git with AWS CodeCommit Tutorial tutorial to start using AWS CodeCommit.