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

Migrate Local or Unversioned Content to AWS CodeCommit

The procedures in this topic show you how to migrate an existing project or local content on your computer to a CodeCommit repository. As part of this process, you:

  • Complete the initial setup required for CodeCommit.

  • Create a CodeCommit repository.

  • Place a local folder under Git version control and push the contents of that folder to the CodeCommit repository.

  • View files in the CodeCommit repository.

  • Share the CodeCommit repository with your team.


            Migrating a local project to CodeCommit

Step 0: Setup Required for Access to CodeCommit

Before you can migrate local content to CodeCommit, you must create and configure an IAM user for CodeCommit and configure your local computer for access. You should also install the AWS CLI to manage CodeCommit. Although you can perform most CodeCommit tasks without it, the AWS CLI offers flexibility when working with Git.

If you are already set up for CodeCommit, you can skip ahead to Step 1: Create a CodeCommit Repository.

To create and configure an IAM user for accessing 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.

    Note

    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 CodeCommit. For more information, see AWS KMS and Encryption.

  3. Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.

  4. In the IAM console, in the navigation pane, choose Users, and then choose the IAM user you want to configure for CodeCommit access.

  5. On the Permissions tab, choose Add Permissions.

  6. In Grant permissions, choose Attach existing policies directly.

  7. From the list of policies, select AWSCodeCommitFullAccess or another managed policy for CodeCommit access. For more information, see AWS Managed (Predefined) Policies for CodeCommit.

    After you have selected the policy you want to attach, choose Next: Review to review the list of policies that will be attached to the IAM user. If the list is correct, choose Add permissions.

    For more information about CodeCommit managed policies and sharing access to repositories with other groups and users, see Share a Repository and Authentication and Access Control for AWS CodeCommit.

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 CodeCommit from the command line. For more information, see Getting Set Up with the AWS Command Line Interface.

    Note

    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, see Installing the AWS Command Line Interface.

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

    aws codecommit help

    This command should return a list of CodeCommit commands.

  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 to use with CodeCommit. Also, be sure to specify the AWS Region where the repository exists, such as us-east-2. 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 a supported region for CodeCommit here, and then press Enter Default output format [None]: Type json here, and then press Enter

    To connect to a repository or a resource in another AWS Region, you must reconfigure the AWS CLI with the default Region name. Supported default Region names for CodeCommit include:

    • us-east-2

    • us-east-1

    • eu-west-1

    • us-west-2

    • ap-northeast-1

    • ap-southeast-1

    • ap-southeast-2

    • eu-central-1

    • ap-northeast-2

    • sa-east-1

    • us-west-1

    • eu-west-2

    • ap-south-1

    • ca-central-1

    • us-gov-west-1

    • us-gov-east-1

    • eu-north-1

    For more information about CodeCommit and AWS Regions, see Regions and Git Connection Endpoints. For more information about IAM, access keys, and secret keys, see How Do I Get Credentials? and Managing Access Keys for IAM Users.

Next, you must install Git.

  • For Linux, macOS, or Unix:

    To work with files, commits, and other information in CodeCommit repositories, you must install Git on your local machine. 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 CodeCommit. If you encounter issues with a specific version of Git and CodeCommit, review the information in Troubleshooting.

  • For Windows:

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

    To install Git, we recommend websites such as Git for Windows. If you use this link to install Git, you can accept all of the installation default settings except for the following:

    Note

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

CodeCommit supports both HTTPS and SSH authentication. To complete setup, you must configure Git credentials for CodeCommit (HTTPS, recommended for most users), an SSH key pair (SSH) to use when accessing CodeCommit, or the credential helper included in the AWS CLI.

Step 1: Create a CodeCommit Repository

In this section, you use the CodeCommit console to create the CodeCommit repository you use for the rest of this tutorial. To use the AWS CLI to create the repository, see Create a Repository (AWS CLI).

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

  2. In the region selector, choose the AWS Region where you want to create the repository. For more information, see Regions and Git Connection Endpoints.

  3. On the Repositories page, choose Create repository.

  4. On the Create repository page, in Repository name, enter a name for the repository.

    Note

    Repository names are case sensitive. The name must be unique in the AWS Region for your AWS account.

  5. (Optional) In Description, enter a description for the repository. This can help you and other users identify the purpose of the repository.

    Note

    The description field displays Markdown in the console and accepts all HTML characters and valid Unicode characters. If you are an application developer who is using the GetRepository or BatchGetRepositories APIs and you plan to display the repository description field in a web browser, see the CodeCommit API Reference.

  6. (Optional) Choose Add tag to add one or more repository tags (a custom attribute label that helps you organize and manage your AWS resources) to your repository. For more information, see Tagging Repositories in AWS CodeCommit.

  7. Choose Create.


                Creating a repository for migrating local content to CodeCommit

After it is created, the repository appears in the Repositories list. In the URL column, choose the copy icon, and then choose the protocol (HTTPS or SSH) to be used to connect to CodeCommit. Copy the URL.

For example, if you named your repository MyFirstRepo and you are using HTTPS, the URL would look like the following:

https://git-codecommit.us-east-2.amazonaws.com/v1/repos/MyFirstRepo

You need this URL later in Step 2: Migrate Local Content to the CodeCommit Repository.

Step 2: Migrate Local Content to the CodeCommit Repository

Now that you have a CodeCommit repository, you can choose a directory on your local computer to convert into a local Git repository. The git init command can be used to either convert existing, unversioned content to a Git repository or, if you do not yet have files or content, to initialize a new, empty repository.

  1. From the terminal or command line on your local computer, change directories to the directory you want to use as the source for your repository.

  2. Run the git init command to initialize Git version control in the directory. This creates a .git subdirectory in the root of the directory that enables version control tracking. The .git folder also contains all of the required metadata for the repository.

    git init
  3. Add the files you want to add to version control. In this tutorial, you run the git add command with the . specifier to add all of the files in this directory. For other options, consult your Git documentation.

    git add .
  4. Create a commit for the added files with a commit message.

    git commit –m "Initial commit"
  5. Run the git push command, specifying the URL and name of the destination CodeCommit repository and the --all option. (This is the URL you copied in Step 1: Create a CodeCommit Repository.)

    For example, if you named your repository MyFirstRepo and you are set up to use HTTPS, you would run the following command:

    git push https://git-codecommit.us-east-2.amazonaws.com/v1/repos/MyFirstRepo --all

Step 3: View Files in CodeCommit

After you have pushed the contents of your directory, you can use the CodeCommit console to quickly view all of the files in the repository.

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

  2. In Repositories, choose the name of the repository (for example, MyFirstRepository) from the list.

  3. View the files in the repository for the branches, clone URLs, settings, and more.

Step 4: Share the CodeCommit Repository

When you create a repository in CodeCommit, two endpoints are generated: one for HTTPS connections and one for SSH connections. Both provide secure connections over a network. Your users can use either protocol. Both endpoints remain active no matter which protocol you recommend to your users. Before you can share your repository with others, you must create IAM policies that allow other users access to your repository. Provide those access instructions to your users.

Create a customer managed policy for your repository

  1. Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the Dashboard navigation area, choose Policies, and then choose Create Policy.

  3. On the Create Policy page, next to Copy an AWS Managed Policy, choose Select.

  4. On the Copy an AWS Managed Policy page, in Search Policies, enter AWSCodeCommitPowerUser. Choose Select next to the policy name.

  5. On the Review Policy page, in Policy Name, enter a new name for the policy (for example, AWSCodeCommitPowerUser-MyDemoRepo).

    In Policy Document, replace the "*" portion of the Resource line with the Amazon Resource Name (ARN) of the CodeCommit repository, as shown here:

    "Resource": [ "arn:aws:codecommit:us-east-2:111111111111:MyDemoRepo" ]

    Tip

    To find the ARN for the CodeCommit repository, go to the CodeCommit console and choose the repository name from the list. For more information, see View Repository Details.

    If you want this policy to apply to more than one repository, add each repository as a resource by specifying its ARN. Include a comma between each resource statement, as shown here:

    "Resource": [ "arn:aws:codecommit:us-east-2:111111111111:MyDemoRepo", "arn:aws:codecommit:us-east-2:111111111111:MyOtherDemoRepo" ]
  6. Choose Validate Policy. After the policy is validated, choose Create Policy.

To manage access to your repository, create an IAM group for its users, add IAM users to that group, and then attach the customer managed policy you created in the previous step. Attach any other policies required for access, such as IAMSelfManageServiceSpecificCredentials or IAMUserSSHKeys.

  1. Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the Dashboard navigation area, choose Groups, and then choose Create New Group.

  3. On the Set Group Name page, in Group Name, enter a name for the group (for example, MyDemoRepoGroup), and then choose Next Step. Consider including the repository name as part of the group name.

    Note

    This name must be unique across an AWS account.

  4. Select the box next to the customer managed policy you created in the previous section (for example, AWSCodeCommitPowerUser-MyDemoRepo).

  5. On the Review page, choose Create Group. IAM creates this group with the specified policies already attached. The group appears in the list of groups associated with your AWS account.

  6. Choose your group from the list.

  7. On the group summary page, choose the Users tab, and then choose Add Users to Group. On the list that shows all users associated with your AWS account, select the boxes next to the users to whom you want to allow access to the CodeCommit repository, and then choose Add Users.

    Tip

    You can use the Search box to quickly find users by name.

  8. When you have added your users, close the IAM console.

After you have created an IAM user to be used to access CodeCommit using the policy group and policies you configured, send that user the information required to connect to the repository.

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

  2. In the region selector, choose the AWS Region where the repository was created. Repositories are specific to an AWS Region. For more information, see Regions and Git Connection Endpoints.

  3. On the Repositories page, find the name of the repository you want to share.

  4. In Clone URL, choose the protocol (HTTPS or SSH) that you want your users to use. This copies the clone URL for the connection protocol.

  5. Send your users the clone URL along with any other instructions, such as installing the AWS CLI, configuring a profile, or installing Git. Make sure to include the configuration information for the connection protocol (for example, for HTTPS, configuring the credential helper for Git).