Etapas de configuração para conexões HTTPS a repositórios do AWS CodeCommit no Windows com o assistente de credenciais da AWS CLI.

Antes de você se conectar ao AWS CodeCommit pela primeira vez, deve concluir as etapas de configuração inicial. Para a maioria dos usuários, isso pode ser feito mais facilmente seguindo as etapas em Para usuários de HTTPS usando credenciais do Git. Contudo, se você deseja se conectar ao CodeCommit usando uma conta raiz, acesso federado ou credenciais temporárias, deverá usar o assistente de credenciais incluído na AWS CLI.

nota

Embora o assistente de credenciais seja um método compatível para se conectar ao CodeCommit usando acesso federado, provedor de identidade ou credenciais temporárias, o método recomendado é instalar e usar o utilitário git-remote-codecommit. Para obter mais informações, consulte Etapas de configuração para conexões HTTPS com o AWS CodeCommit com git-remote-codecommit.

Este tópico ensina as etapas para instalar a AWS CLI, configurar seu computador e perfil da AWS, conectar-se a um repositório do CodeCommit e clonar esse repositório no seu computador, também conhecido como criar um repositório local. Se não estiver familiarizado com o Git, revise as informações em Como posso saber mais sobre o Git?.

Etapa 1: configuração inicial do CodeCommit

Siga estas etapas para configurar uma conta da Amazon Web Services, criar e configurar um usuário do IAM e instalar a AWS CLI. A AWS CLI inclui um assistente de credenciais que você configura para conexões HTTPS nos repositórios do CodeCommit.

Para criar e configurar um usuário do IAM para acessar o CodeCommit

1. Crie uma conta da Amazon Web Services acessando http://aws.amazon.com e escolhendo Cadastrar-se.

2. Crie um usuário do IAM ou use um existente na sua conta da Amazon Web Services. Confirme se você tem um ID de chave de acesso e uma chave de acesso secreta associados ao usuário do IAM. Para obter mais informações, consulte Criar um usuário do IAM na conta da Amazon Web Services.

   nota

   O CodeCommit exige o AWS Key Management Service. Se você estiver usando um usuário do IAM existente, verifique se não há políticas anexadas ao usuário que neguem expressamente as ações do AWS KMS exigidas pelo CodeCommit. Para obter mais informações, consulte AWS KMS e criptografia.

3. Faça login no AWS Management Console e abra o console do IAM em https://console.aws.amazon.com/iam/.

4. No console do IAM, no painel de navegação, selecione Usuários e, em seguida, escolha o usuário do IAM que deseja configurar para acessar o CodeCommit.

5. Na guia Permissions, escolha Add Permissions.

6. Em Grant permissions, escolha Attach existing policies directly.

7. Na lista de políticas, selecione AWSCodeCommitPowerUser ou outra política gerenciada para acessar o CodeCommit. Para obter mais informações, consulte AWS políticas gerenciadas para CodeCommit.

   Depois de selecionar a política que deseja anexar, escolha Próximo: Revisar para revisar a lista de políticas a serem anexadas ao usuário do IAM. Se a lista estiver correta, selecione Add permissions.

   Para obter mais informações sobre políticas gerenciadas do CodeCommit e o compartilhamento de acesso a repositórios com outros grupos e usuários, consulte Compartilhar um repositório e Autenticação e controle de acesso para o AWS CodeCommit.

Como instalar e configurar o AWS CLI

1. Na sua máquina local, baixe e instale o AWS CLI. Esse é um pré-requisito para interagir com o CodeCommit a partir da linha de comando. Recomendamos instalar a AWS CLI versão 2. É a versão principal mais recente da AWS CLI e é compatível com todos os atributos mais recentes. É a única versão da AWS CLI compatível com uma conta raiz, acesso federado ou credenciais temporárias com git-remote-codecommit.

   Para obter mais informações, consulte Configurar com a interface da linha de comando da AWS.

   nota

   O CodeCommit funciona somente com as versões 1.7.38 e posteriores da AWS CLI. Como prática recomendada, instale ou atualize a AWS CLI para a versão mais recente disponível. Para determinar qual versão da AWS CLI você tem instalada, execute o comando aws --version.

   Para atualizar uma versão mais antiga da AWS CLI para a versão mais recente, consulte Instalação da AWS Command Line Interface.

2. Execute esse comando para verificar se os comandos do CodeCommit para a AWS CLI estão instalados.

   aws codecommit help

   Esse comando retorna uma lista de comandos do CodeCommit.

3. Configure a AWS CLI com um perfil usando o comando configure, da seguinte forma:

   aws configure

   Quando solicitado, especifique a chave de acesso da AWS e a chave de acesso secreta da AWS do usuário do IAM que será usado com o CodeCommit. Além disso, lembre-se de especificar a Região da AWS onde está o repositório, como us-east-2. Quando solicitado pelo formato de saída padrão, especifique json. Por exemplo, se você estiver configurando um perfil para um usuário do IAM:

   AWS Access Key ID [None]: Type your IAM user AWS access key ID here, and then press Enter
   AWS Secret Access Key [None]: Type your IAM user 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

   Para obter mais informações sobre como criar e configurar perfis para usar com a AWS CLI, consulte o seguinte:

   • Perfis nomeados

   • Usar um perfil do IAM na AWS CLI

   • Comando set

   • Conectar-se a repositórios do AWS CodeCommit com credenciais rotativas

   Para se conectar a um repositório ou recurso em outra Região da AWS, é necessário reconfigurar a AWS CLI com o nome da região padrão. Os nomes das regiões padrão compatíveis com o CodeCommit incluem:

   • us-east-2

   • us-east-1

   • eu-west-1

   • us-west-2

   • ap-northeast-1

   • ap-southeast-1

   • ap-southeast-2

   • ap-southeast-3

   • me-central-1

   • eu-central-1

   • ap-northeast-2

   • sa-east-1

   • us-west-1

   • eu-west-2

   • ap-south-1

   • ap-south-1

   • ca-central-1

   • us-gov-west-1

   • us-gov-east-1

   • eu-north-1

   • ap-east-1

   • me-south-1

   • cn-north-1

   • cn-northwest-1

   • eu-south-1

   • ap-northeast-3

   • af-south-1

   • il-central-1

   Para obter mais informações sobre o CodeCommit e Região da AWS, consulte Regiões e endpoints de conexão do Git. Para obter mais informações sobre o IAM, chaves de acesso e chaves secretas, consulte Como consigo credenciais? e Gerenciar chaves de acesso para usuário do IAM. Para obter mais informações sobre a AWS CLI e perfis, consulte Perfis nomeados.

Etapa 2: Instalar o Git

Para trabalhar com arquivos, confirmações e outras informações nos repositórios do CodeCommit, você deve instalar o Git na sua máquina local. O CodeCommit é compatível com o Git versões 1.7.9 e posteriores. A versão 2.28 do Git suporta a configuração do nome de ramificações para as confirmações iniciais. Recomendamos o uso de uma versão recente do Git.

Para instalar o Git, recomendamos sites como Git for Windows. Se você usar esse link para instalar o Git, poderá aceitar todas as configurações padrão da instalação, exceto as seguintes:

• Quando solicitado durante a etapa Ajustar o seu ambiente PATH, escolha a opção de usar o Git na linha de comando.

• (Opcional) Se você pretende usar HTTPS com o assistente de credenciais incluído na AWS CLI em vez de configurar as credenciais do Git para o CodeCommit, verifique se a opção Habilitar o Git Credential Manager na página Configurar opções extras está desmarcada. O Git Credential Manager só é compatível com o CodeCommit se os usuários do IAM configurarem as credenciais do Git. Para obter mais informações, consulte Para usuários de HTTPS usando credenciais do Git e Git para Windows: eu instalei o Git para Windows, mas o acesso ao meu repositório é negado (403).

nota

O Git é uma plataforma em constante evolução atualizada regularmente. Ocasionalmente, alguma alteração de atributo pode afetar a interação dele com o CodeCommit. Se você tiver problemas com uma versão específica do Git e CodeCommit, reveja as informações em Solução de problemas.

Etapa 3: Configurar o assistente de credenciais

A AWS CLI inclui um assistente de credenciais do Git que pode ser usado com o CodeCommit. O assistente de credenciais do Git requer um perfil de credencial da AWS, que armazena uma cópia do ID da chave de acesso da AWS e da chave de acesso secreta da AWS de um usuário do IAM (junto com um nome padrão da Região da AWS e formato de saída padrão). O assistente de credenciais do Git usa essas informações para a autenticação automática no CodeCommit, assim você não precisará inserir essas informações sempre que usar o Git para interagir com o CodeCommit.

1. Abra um prompt de comando e use o Git para executar git config, especificando o uso do assistente de credenciais do Git com o perfil de credencial da AWS, o que permite que o assistente de credenciais do Git envie o caminho para os repositórios:

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

   O assistente de credenciais do Git grava o seguinte no arquivo .gitconfig:

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

   Importante

   • Se você estiver usando um emulador de Bash em vez da linha de comando do Windows, deve usar aspas simples em vez de aspas duplas.

   • O assistente de credenciais usa o perfil de credencial padrão da AWS ou um perfil de instância do Amazon EC2. Se você tiver um perfil de credencial da AWS para usar, como CodeCommitProfile, você poderá modificar o comando da seguinte maneira para usá-lo:

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

     Isso grava o seguinte no arquivo .gitconfig:

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

   • Se o nome do seu perfil tiver espaços, será necessário editar o arquivo .gitconfig depois de executar esse comando para inseri-lo em aspas simples ('). Caso contrário, o assistente de credenciais não funcionará.

   • Se a instalação do Git para Windows incluir o utilitário Git Credential Manager, você verá erros 403 ou solicitações para fornecer credenciais no utilitário Credential Manager após as primeiras tentativas de conexão. A maneira mais confiável de resolver esse problema é desinstalar e reinstalar o Git para Windows sem a opção do utilitário Git Credential Manager, pois ele não é compatível com o CodeCommit. Para manter o utilitário Git Credential Manager, você deve executar algumas etapas adicionais de configuração para usar também o CodeCommit, incluindo a modificação manual do arquivo .gitconfig para especificar o uso do assistente de credenciais no AWS CodeCommit ao se conectar ao CodeCommit. Exclua todas as credenciais armazenadas do utilitário Credential Manager (o utilitário pode ser encontrado no Painel de Controle). Depois de remover todas as credenciais armazenadas, adicione o seguinte ao seu arquivo .gitconfig, salve-o e tente se conectar novamente a partir de uma nova janela do prompt de comando:

     [credential "https://git-codecommit.us-east-2.amazonaws.com"]
         helper = !aws codecommit credential-helper $@ 
         UseHttpPath = true
     
     [credential "https://git-codecommit.us-east-1.amazonaws.com"]
         helper = !aws codecommit credential-helper $@ 
         UseHttpPath = true
     

     Além disso, talvez seja necessário redefinir as configurações de git config especificando --system em vez de --global ou --local para que todas as conexões funcionem como esperado.

   • Para usar usuários do IAM diferentes na mesma máquina local do CodeCommit, você deve especificar git config --local em vez de git config --global e executar a configuração para cada perfil de credencial da AWS.

2. Execute git config --global --edit para verificar se os valores anteriores foram gravados no arquivo .gitconfig para seu perfil de usuário (por padrão, %HOME%\.gitconfig ou drive:\Users\UserName\.gitconfig). Se houver êxito, você verá os valores anterior (além de valores que já possam existir no arquivo de configuração global do Git). Para sair, normalmente, você digita :q e pressiona Enter.

Etapa 4: conectar-se ao console do CodeCommit e clonar o repositório

Se um administrador já enviou para você o nome e os detalhes de conexão para o repositório do CodeCommit, pule esta etapa e clone o repositório diretamente.

Para se conectar a um repositório do CodeCommit

1. Abra o console do CodeCommit em https://console.aws.amazon.com/codesuite/codecommit/home.

2. No seletor de região, escolha a Região da AWS onde o repositório foi criado. Os repositórios são específicos de uma Região da AWS. Para obter mais informações, consulte Regiões e endpoints de conexão do Git.

3. Escolha na lista o repositório ao qual deseja se conectar. Escolha Clone URL (Clonar URL) e escolha o protocolo que você deseja usar ao clonar ou se conectar ao repositório. Isso copia a URL do clone.

   • Copie a URL HTTPS se você estiver usando credenciais do Git com seu usuário do IAM ou o assistente de credenciais incluído na AWS CLI.

   • Copie o URL HTTPS (GRC) se estiver usando o comando git-remote-codecommit no computador local.

   • Copie a URL SSH se você estiver usando um par de chaves SSH pública/privada com seu usuário do IAM.

   nota

   Se você visualizar uma página Boas-vindas em vez de uma lista de repositórios, não há repositórios associados à sua conta da AWS na Região da AWS onde você está conectado. Para criar um repositório, consulte Crie um AWS CodeCommit repositório ou siga as etapas no tutorial Conceitos básicos do Git e CodeCommit.

4. Abra um prompt de comando e execute o comando git clone com a URL HTTPS que você copiou. O repositório local é criado em um subdiretório do diretório onde o comando é executado. Por exemplo, para clonar um repositório denominado MyDemoRepo em um repositório local denominado my-demo-repo na região Leste dos EUA (Ohio):

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

   Em algumas versões do Windows, poderá ser exibida uma mensagem pop-up solicitando seu nome de usuário e sua senha. Esse é o sistema de gerenciamento de credenciais interno do Windows, mas ele não é compatível com o assistente de credenciais do AWS CodeCommit. Escolha Cancelar.

Próximas etapas

Você concluiu os pré-requisitos. Siga as etapas em Começando com CodeCommit para começar a usar o CodeCommit.