Apêndice A: Ações de origem do GitHub versão 1 - AWS CodePipeline

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Apêndice A: Ações de origem do GitHub versão 1

Este apêndice fornece informações sobre a versão 1 da ação GitHub no CodePipeline.

nota

Embora não seja recomendável usar a ação do GitHub versão 1, os pipelines existentes com a ação do GitHub versão 1 continuarão a funcionar sem qualquer impacto. Para um pipeline com uma ação do GitHub versão 1, o CodePipeline usa tokens baseados em OAuthh para se conectar ao repositório do GitHub. Por outro lado, a ação do GitHub (versão 2) usa um recurso de conexão para associarAWSRecursos do para o repositório do GitHub. O recurso de conexão usa tokens baseados em aplicativo para se conectar. Para obter mais informações sobre como atualizar seu pipeline para a ação recomendada do GitHub que usa uma conexão, consulteAtualizar uma ação de origem do GitHub versão 1 para uma ação de origem do GitHub versão 2. Para obter mais informações sobre o acesso GitHub baseado em OAuth em contraste com o acesso GitHub baseado em aplicativo, consultehttps://docs.github.com/en/developers/apps/differences-between-github-apps-and-oauth-apps.

Para integra-ser com o GitHub, o CodePipeline usa um aplicativo OAuth do GitHub para seu pipeline. O CodePipeline usa webhooks para gerenciar a detecção de alterações para seu pipeline com a ação de origem do GitHub versão 1.

nota

Quando você configura uma ação de origem do GitHub versão 2 noAWS CloudFormation, você não inclui nenhuma informação de token do GitHub ou adiciona um recurso do webhook. Você configura um recurso de conexões conforme mostrado emAWS::CodeStarConnections::Connectionno AWS CloudFormationGuia do usuário do .

Esta referência contém as seguintes seções para a ação GitHub versão 1:

Adicionando uma ação de origem do GitHub versão 1

Adicionar ações de origem do GitHub versão 1 ao CodePipeline:

Referência da estrutura de ação de origem do GitHub versão 1

nota

Embora não seja recomendável usar a ação do GitHub versão 1, os pipelines existentes com a ação do GitHub versão 1 continuarão a funcionar sem qualquer impacto. Para um pipeline com uma ação de origem GitHub versão 1 do GitHub, o CodePipeline usa tokens baseados em OAuthh para se conectar ao repositório do GitHub. Por outro lado, a nova ação do GitHub (versão 2) usa um recurso de conexão para associarAWSRecursos do para o repositório do GitHub. O recurso de conexão usa tokens baseados em aplicativo para se conectar. Para obter mais informações sobre como atualizar seu pipeline para a ação recomendada do GitHub que usa uma conexão, consulteAtualizar uma ação de origem do GitHub versão 1 para uma ação de origem do GitHub versão 2.

Aciona o pipeline quando uma nova confirmação é feita no repositório e ramificação do GitHub configurados.

Para integra-ser com o GitHub, o CodePipeline usa um aplicativo OAuth ou um token de acesso pessoal para seu pipeline. Se você usar o console para criar ou editar o pipeline, o CodePipeline criará um webhook do GitHub que iniciará o pipeline quando ocorrer uma alteração no repositório.

Você já deve ter criado uma conta e um repositório do GitHub antes de conectar o pipeline por meio de uma ação do GitHub.

Se você quiser limitar o acesso que o CodePipeline tem aos repositórios, crie uma conta do GitHub e conceda à conta acesso apenas aos repositórios que você deseja integrar ao CodePipeline. Use essa conta ao configurar o CodePipeline para usar repositórios do GitHub para estágios de origem em pipelines.

Para obter mais informações, consulte a documentação do desenvolvedor do GitHub no site do GitHub.

Tipo de ação

  • Categoria: Source

  • Proprietário: ThirdParty

  • Fornecedor: GitHub

  • Versão: 1

Parâmetros de configuração

Proprietário

: obrigatório:: Sim

O nome do usuário ou da organização do GitHub que possui o repositório do GitHub.

Repositório

: obrigatório:: Sim

O nome do repositório onde as alterações de origem devem ser detectadas.

Ramificação

: obrigatório:: Sim

O nome da ramificação onde as alterações de origem devem ser detectadas.

OAuthToken

: obrigatório:: Sim

Representa o token de autenticação do GitHub que permite que o CodePipeline execute operações em seu repositório do GitHub. A entrada é sempre exibida como uma máscara de quatro asteriscos. Representa um dos seguintes valores:

  • Quando você usa o console para criar o pipeline, o CodePipeline usa um token OAuth para registrar a conexão do GitHub.

  • Ao usar a AWS CLI para criar o pipeline, é possível transmitir um token de acesso pessoal do GitHub nesse campo. Substitua os asteriscos (****) pelo seu token de acesso pessoal copiado do GitHub. Quando get-pipeline é executado para visualizar a configuração da ação, a máscara de quatro asteriscos é exibida para esse valor.

  • Quando um modelo do AWS CloudFormation é usado para criar o pipeline, primeiro é necessário armazenar o token como um segredo no AWS Secrets Manager. Inclua o valor desse campo como uma referência dinâmica para o segredo armazenado no Secrets Manager, como{{resolve:secretsmanager:MyGitHubSecret:SecretString:token}}.

Para obter mais informações sobre os escopos do GitHub, consulte a Referência da API do desenvolvedor do GitHub no site do GitHub.

PollForSourceChanges

: obrigatório:: Não

PollForSourceChangesO controla se o CodePipeline faz pesquisas no repositório GitHub em busca de alterações na origem Recomendamos que você use webhooks para detectar alterações na origem. Para obter mais informações sobre como configurar webhooks, consulte Atualizar os pipelines para o envio de eventos (origem do GitHub versão 1) (CLI) ou Atualizar os pipelines para o envio de eventos (ações de origem do GitHub versão 1) (AWS CloudFormationTemplate).

Importante

Quando planejar configurar webhooks, você deve definir PollForSourceChanges como false para evitar execuções duplicadas do pipeline.

Os valores válidos para esse parâmetro:

  • True: se definido, o CodePipeline fará uma pesquisa no repositório para buscar alterações na origem.

    nota

    Se você omitirPollForSourceChangesO padrão do CodePipeline é pesquisar seu repositório para buscar alterações na origem. Esse comportamento é o mesmo de quando o PollForSourceChanges está definido como true.

  • False: se definido, o CodePipeline não fará uma pesquisa no repositório para buscar alterações na origem. Use essa configuração quando você planejar configurar um webhook para detectar alterações na origem.

Input artifacts (Artefatos de entrada)

  • Número de artefatos: 0

  • Descrição: Artefatos de entrada não se aplicam a esse tipo de ação.

Artefatos de saída

  • Número de artefatos: 1

  • Descrição: O artefato de saída desta ação é um arquivo ZIP que contém o conteúdo do repositório e ramificação configurados na confirmação especificada como a revisão de origem para a execução do pipeline. Os artefatos gerados no repositório são os artefatos de saída para a ação do GitHub. O ID de confirmação do código-fonte é exibido no CodePipeline como a revisão da origem para a execução acionada do pipeline.

Variáveis de saída

Quando configurada, essa ação produz variáveis que podem ser referenciadas pela configuração de ação de uma ação downstream no pipeline. Esta ação produz variáveis que podem ser visualizadas como variáveis de saída, mesmo que a ação não tenha um namespace. Configure uma ação com um namespace a fim de disponibilizar as variáveis para a configuração de ações downstream.

Para obter mais informações sobre variáveis no CodePipeline, consulteVariables.

CommitId

O ID de confirmação do GitHub que acionou a execução do pipeline. Os IDs de confirmação são o SHA completo da confirmação.

CommitMessage

A mensagem da descrição, se houver, associada à confirmação que acionou a execução do pipeline.

CommitUrl

O endereço URL da confirmação que acionou o pipeline.

RepositoryName

O nome do repositório do GitHub onde a confirmação que acionou o pipeline foi feita.

BranchName

O nome da ramificação do repositório do GitHub onde a alteração na origem foi feita.

AuthorDate

A data em que a confirmação foi criada, no formato de timestamp.

Para obter mais informações sobre a diferença entre um autor e um committer no Git, consulte Visualização do histórico de confirmação no Pro Git de Scott Chacon e Ben Straub.

CommitterDate

A data em que a confirmação foi confirmada, no formato de timestamp.

Para obter mais informações sobre a diferença entre um autor e um committer no Git, consulte Visualização do histórico de confirmação no Pro Git de Scott Chacon e Ben Straub.

Declaração de ação (exemplo do GitHub)

YAML
Name: Source Actions: - InputArtifacts: [] ActionTypeId: Version: '1' Owner: ThirdParty Category: Source Provider: GitHub OutputArtifacts: - Name: SourceArtifact RunOrder: 1 Configuration: Owner: MyGitHubAccountName Repo: MyGitHubRepositoryName PollForSourceChanges: 'false' Branch: main OAuthToken: '{{resolve:secretsmanager:MyGitHubSecret:SecretString:token}}' Name: ApplicationSource
JSON
{ "Name": "Source", "Actions": [ { "InputArtifacts": [], "ActionTypeId": { "Version": "1", "Owner": "ThirdParty", "Category": "Source", "Provider": "GitHub" }, "OutputArtifacts": [ { "Name": "SourceArtifact" } ], "RunOrder": 1, "Configuration": { "Owner": "MyGitHubAccountName", "Repo": "MyGitHubRepositoryName", "PollForSourceChanges": "false", "Branch": "main", "OAuthToken": "{{resolve:secretsmanager:MyGitHubSecret:SecretString:token}}" }, "Name": "ApplicationSource" } ] },

Conexão ao GitHub (OAuth)

A primeira vez que usar o console para adicionar um repositório GitHub a um pipeline, você será solicitado a autorizar o acesso do CodePipeline aos repositórios. O token requer os seguintes escopos do GitHub:

  • O escopo repo, que é usado para se obter o controle total para ler e efetuar pull de artefatos de repositórios públicos e privados para um pipeline.

  • O escopo admin:repo_hook, que é usado para se obter o controle total dos ganchos do repositório.

Ao usar a CLI ou um modelo do AWS CloudFormation, você deve fornecer o valor de um token de acesso pessoal que você já criou no GitHub.

Para visualizar os aplicativos OAuth do CodePipeline para seu pipeline, consulteVisualizar aplicativos OAuth autorizados.

Para criar e gerenciar tokens de acesso pessoal do GitHub, consulte Configurar o pipeline para usar um token de acesso pessoal (GitHub e CLI).

Os recursos relacionados a seguir podem ajudar você à medida que trabalha com esta ação.

Usar webhooks para iniciar um pipeline (ações de origem do GitHub versão 1)

Um webhook é uma notificação de HTTP que detecta eventos em outra ferramenta, como um repositório GitHub, e conecta tais eventos externos a um pipeline.

Quando você usa o console para criar ou editar um pipeline que tem uma origem do GitHub, o CodePipeline cria um webhook. O CodePipeline exclui seu webhook quando você exclui seu pipeline. Você não precisa gerenciá-lo no GitHub. Se usar a AWS CLI ou o AWS CloudFormation para criar ou editar um pipeline que tem uma origem do GitHub, você deverá usar as informações nestas seções para gerenciar webhooks por conta própria.

Criar um webhook para uma origem do GitHub

Depois de usar o AWS CLI para criar um webhook manualmente, é necessário registrar o webhook no GitHub. Um designado paraAWSO endpoint é usado para o webhook e fornecido peloput-webhookComando do.

Importante

Se você usar o console para criar ou editar o pipeline, o webhook será criado para você.

Para usar a AWS CLI para criar um webhook, chame o comando put-webhook e forneça o seguinte:

  • Um nome que identifique de forma exclusiva o webhook. Esse nome deve ser exclusivo na região da conta para o pipeline.

  • Uma chave secreta no arquivo JSON que será usada para autorização do GitHub.

    Osegredo de webhooké usado quando o GitHub faz uma solicitação de webhook para o CodePipeline para que o CodePipeline possa validar a solicitação webhook é autêntica e veio do GitHub. Recomenda-se fornecer um valor secreto gerado aleatoriamente longo para este campo. Quando o CodePipelineRegisterWebhookWithThirdPartyAPI é chamada, o segredo do webhook é passado para o GitHub através da API de criação do webhook do GitHub. Para obter mais informações, consultehttps://developer.github.com/v3/repos/hooks/#create-hook-config-params.

    O GitHub OAuth ou token pessoal não deve ser usado como um segredo do webhook.

Para criar e registrar seu webhook

nota

Ao usar a CLI ou o AWS CloudFormation para criar um pipeline e adicionar um webhook, é necessário desativar as verificações periódicas. Para desativar as verificações periódicas, é necessário adicionar explicitamente o parâmetro PollForSourceChanges e defini-lo como falso, conforme descrito no procedimento final abaixo. Caso contrário, o padrão para um pipeline da CLI ou do AWS CloudFormation é que PollForSourceChanges seja padronizado como verdadeiro e não seja exibido na saída da estrutura de pipeline. Para obter mais informações sobre os padrões de PollForSourceChanges, consulte Configurações padrão do parâmetro PollForSourceChanges.

  1. Em um editor de texto, crie e salve um arquivo JSON para o webhook que deseja criar. Use esse exemplo de arquivo para um webhook denominado my-webhook:

    {"webhook": {"name": "my-webhook", "targetPipeline": "pipeline_name", "targetAction": "source_action_name", "filters": [ { "jsonPath": "$.ref", "matchEquals": "refs/heads/{Branch}" } ], "authentication": "GITHUB_HMAC", "authenticationConfiguration": {"SecretToken":"secret"} } }
  2. Use o comando put-webhook e inclua os parâmetros --cli-input e --region.

    O exemplo de comando a seguir cria um webhook com o arquivo JSON webhook_json.

    aws codepipeline put-webhook --cli-input-json file://webhook_json.json --region "eu-central-1"
  3. Na saída mostrada neste exemplo, a URL e o ARN são retornados para um webhook denominado my-webhook.

    { "webhook": { "url": "https://webhooks.domain.com/trigger111111111EXAMPLE11111111111111111", "definition": { "authenticationConfiguration": { "SecretToken": "secret" }, "name": "my-webhook", "authentication": "GITHUB_HMAC", "targetPipeline": "pipeline_name", "targetAction": "Source", "filters": [ { "jsonPath": "$.ref", "matchEquals": "refs/heads/{Branch}" } ] }, "arn": "arn:aws:codepipeline:eu-central-1:ACCOUNT_ID:webhook:my-webhook" }, "tags": [{ "key": "Project", "value": "ProjectA" }] }

    Este exemplo adiciona tags ao webhook incluindo a chave de tag Project e o valor ProjectA no webhook. Para obter mais informações sobre a marcação de recursos no CodePipeline, consulteMarcar recursos do .

  4. Use o comando register-webhook-with-third-party e inclua o parâmetro --webhook-name.

    O exemplo de comando a seguir registra um webhook denominado my-webhook.

    aws codepipeline register-webhook-with-third-party --webhook-name my-webhook

Se você estiver atualizando um pipeline para utilizar webhooks, também é necessário seguir o procedimento a seguir para desativar as verificações periódicas.

Editar o parâmetro PollForSourceChanges do pipeline

Importante

Ao criar um pipeline com esse método, o parâmetro PollForSourceChanges é padronizado como verdadeiro se não for explicitamente definido como falso. Ao adicionar a detecção de alterações baseada em eventos, é necessário adicionar o parâmetro a sua saída e defini-lo como falso para desativar a sondagem. Caso contrário, o pipeline inicia duas vezes para uma única alteração de origem. Para obter mais detalhes, consulte Configurações padrão do parâmetro PollForSourceChanges.

  1. Execute o get-pipeline comando para copiar a estrutura do pipeline em um arquivo JSON. Por exemplo, para um pipeline chamado MyFirstPipeline, você deve digitar o seguinte comando:

    aws codepipeline get-pipeline --name MyFirstPipeline >pipeline.json

    Este comando retorna nada, mas o arquivo que você criou deve aparecer no diretório onde você executou o comando.

  2. Abra o arquivo JSON em qualquer editor de texto plano e altere ou adicione o parâmetro PollForSourceChanges para editar o estágio de origem. Neste exemplo, para um repositório denominado UserGitHubRepo, o parâmetro é definido como false.

    Por que estou fazendo essa alteração? A alteração deste parâmetro para desativa as verificações periódicas para que você possa utilizar apenas a detecção de alterações baseada em eventos.

    "configuration": { "Owner": "darlaker", "Repo": "UserGitHubRepo", "PollForSourceChanges": "false", "Branch": "main", "OAuthToken": "****" },
  3. Se você estiver trabalhando com a estrutura de pipeline recuperada por meio do comando get-pipeline, é necessário editar a estrutura no arquivo JSON por meio da remoção das linhas metadata do arquivo. Caso contrário, o comando update-pipeline não é capaz de utilizá-la. Remova a seção "metadata" da estrutura do pipeline no arquivo JSON, incluindo os campos: { }, "created", "pipelineARN" e "updated".

    Por exemplo, remova as seguintes linhas da estrutura:

    "metadata": { "pipelineArn": "arn:aws:codepipeline:region:account-ID:pipeline-name", "created": "date", "updated": "date" }

    Salve o arquivo.

  4. Para aplicar suas alterações, execute o comando update-pipeline, especificando o pipeline do arquivo JSON, de modo semelhante ao seguinte:

    Importante

    Não se esqueça de incluir file:// antes do nome de arquivo. Ele é obrigatório nesse comando.

    aws codepipeline update-pipeline --cli-input-json file://pipeline.json

    Este comando retorna toda a estrutura do pipeline editado.

    nota

    O comando update-pipeline interrompe o pipeline. Se uma revisão estiver sendo executada pelo pipeline quando você executar o comando update-pipeline, essa execução será interrompida. Você deve iniciar manualmente o pipeline para executar a revisão através do pipeline atualizado. Use o comando start-pipeline-execution para iniciar manualmente o pipeline.

Listar webhooks na conta

Você pode usar a AWS CLI para listar webhooks em sua conta.

Listar webhooks na conta

  1. Para listar os webhooks, use o comando list-webhooks e inclua os parâmetros --endpoint-url e --region.

    O exemplo de comando a seguir lista webhooks para o URL do endpoint "eu-central-1".

    aws codepipeline list-webhooks --endpoint-url "https://codepipeline.eu-central-1.amazonaws.com" --region "eu-central-1"
  2. Webhooks são listados, incluindo o nome e o ARN de cada webhook.

    { "webhooks": [ { "url": "https://webhooks.domain.com/trigger111111111EXAMPLE11111111111111111": { "authenticationConfiguration": { "SecretToken": "Secret" }, "name": "my-webhook", "authentication": "GITHUB_HMAC", "targetPipeline": "my-Pipeline", "targetAction": "Source", "filters": [ { "jsonPath": "$.ref", "matchEquals": "refs/heads/{Branch}" } ] }, "arn": "arn:aws:codepipeline:eu-central-1:ACCOUNT_ID:webhook:my-webhook" } ] }
  3. No GitHub, selecione seu repositório.

  4. Selecione Settings (Configurações) e clique em Webhooks.

    Visualize as informações de webhook do seu repositório.

Editar o webhook da origem do GitHub

Você pode usar a AWS CLI para editar o webhook do seu repositório.

  • Se você usar o console para editar a ação de origem do GitHub para seu pipeline, o webhook será atualizado para você (e, se necessário, registrado novamente).

  • Se não estiver atualizando o nome do webhook e alterando o repositório GitHub, é possível utilizar a AWS CLI para atualizar o webhook. Veja o exemplo 1.

  • Se estiver alterando o nome do webhook ou o nome do repositório do GitHub, você deverá editar a ação de origem no console ou excluir e recriar o webhook na CLI. Após a criação do webhook, você também deve registrá-lo. Veja o exemplo 2.

Exemplo 1: Atualizar um segredo de webhook

  1. Em um editor de texto, edite o arquivo JSON do webhook que deseja atualizar. Este exemplo modifica a amostra de arquivo usada para criar o webhook em Criar um webhook para uma origem do GitHub. Esse exemplo altera o token secreto do webhook denominado "my-webhook".

    {"webhook": {"name": "my-webhook", "targetPipeline": "pipeline_name", "targetAction": "source_action_name", "filters": [ { "jsonPath": "$.ref", "matchEquals": "refs/heads/{Branch}" } ], "authentication": "GITHUB_HMAC", "authenticationConfiguration": {"SecretToken":"new_secret"} } }
  2. Use o comando put-webhook e inclua os parâmetros --cli-input e --region.

    O exemplo de comando a seguir atualiza um webhook com o arquivo JSON "webhook_json" modificado.

    aws codepipeline put-webhook --cli-input-json file://webhook_json.json --region "eu-central-1"
  3. A saída retorna os detalhes do webhook e o novo segredo.

    nota

    Você pode editar a ação de origem do GitHub no console. Isso permite que o CodePipeline gerencie webhooks para você.

Exemplo 2: Para atualizar um nome de webhook ou um repositório GitHub

  1. Cancele o registro e exclua o webhook existente associado ao nome do webhook antigo ou repositório GitHub por meio das etapas em Excluir o webhook da origem do GitHub.

  2. Siga as etapas em Criar um webhook para uma origem do GitHub para criar o webhook novamente.

    nota

    Você pode editar a ação de origem do GitHub no console. Isso permite que o CodePipeline gerencie webhooks para você.

Excluir o webhook da origem do GitHub

Para usar a AWS CLI para excluir um webhook:

  1. É necessário cancelar o registro do webhook antes de excluí-lo. Use o comando deregister-webhook-with-third-party e inclua o parâmetro --webhook-name.

    O exemplo de comando a seguir cancela o registro do webhook denominado "my-webhook".

    aws codepipeline deregister-webhook-with-third-party --webhook-name my-webhook
  2. Use o comando delete-webhook e inclua o parâmetro --name.

    O exemplo de comando a seguir exclui o webhook denominado "my-webhook".

    aws codepipeline delete-webhook --name my-webhook

Marcar um webhook no CodePipeline

Você pode aplicar tags aos webhooks no CodePipeline. As tags são pares de chave-valor associados a recursos da AWS. Para obter informações sobre a marcação de tags do recurso do CodePipeline, casos de uso, restrições de chave e valor de tag e tipos de recursos compatíveis, consulteMarcar recursos do .

Você pode especificar tags ao criar um webhook. Você pode adicionar, remover e atualizar os valores de tags em um webhook. Você pode adicionar até 50 tags para cada webhook.

Adicionar tags a um webhook existente

Siga estas etapas para usar a AWS CLI para adicionar uma tag a um webhook. Para adicionar uma tag a um webhook ao criá-lo, consulte Criar um webhook para uma origem do GitHub.

Nestas etapas, partimos do princípio de que você já instalou uma versão recente da AWS CLI ou atualizou para a versão atual. Para obter mais informações, consulte Como instalar a AWS Command Line Interface.

No terminal ou na linha de comando, execute o comando tag-resource, especificando o nome de recurso da Amazon (ARN) do webhook no qual você deseja adicionar tags e a chave e o valor da tag que você deseja adicionar. Você pode adicionar mais de uma tag a um webhook. Por exemplo, para marcar um webhook chamado MyWebhook com duas tags, uma chave de tag chamada Project com valor de tag NewProject, e uma chave de tag chamada ApplicationName com valor da tag MyApplication:

aws codepipeline tag-resource --resource-arn arn:aws:codepipeline:us-west-2:account-id:webhook:MyWebhook --tags key=Project,value=NewProject key=ApplicationName,value=MyApplication

Se houver êxito, o comando não retorna nada.

Visualizar tags de um webhook

Siga estas etapas para usar a AWS CLI para visualizar as tags da AWS para um webhook. Se não foram adicionadas tags, a lista retornará vazia.

No terminal ou na linha de comando, execute o comando list-tags-for-resource. Por exemplo, para visualizar uma lista de chaves e valores de tag para um webhook chamado MyWebhook com o ARN arn:aws:codepipeline:us-west-2:account-id:webhook:MyWebhook:

aws codepipeline list-tags-for-resource --resource-arn arn:aws:codepipeline:us-west-2:account-id:webhook:MyWebhook

Se houver êxito, o comando retornará informações semelhantes às seguintes:

{ "tags": { "Project": "NewProject", "ApplicationName": "MyApplication" } }

Editar tags de um webhook

Siga estas etapas para usar a AWS CLI para atualizar uma tag para um webhook. Você pode alterar o valor para uma chave existente ou adicionar outra chave. Você também pode remover tags de um webhook, conforme mostrado na próxima seção.

No terminal ou na linha de comando, execute o comando tag-resource, especificando o ARN do webhook no qual deseja atualizar uma tag e especifique a chave e o valor da tag:

aws codepipeline tag-resource --resource-arn arn:aws:codepipeline:us-west-2:account-id:webhook:MyWebhook --tags key=Project,value=UpdatedProject

Remover tags de um webhook

Siga estas etapas para usar a AWS CLI para remover uma tag de um webhook. Ao remover tags do recurso associado, as tags são excluídas.

nota

Se você excluir um webhook, todas as associações de tag serão removidas do webhook. Você não precisa remover as tags antes de excluir um webhook.

No terminal ou na linha de comando, execute o comando untag-resource, especificando o ARN do webhook do qual você deseja remover tags e a chave da tag que você deseja remover. Por exemplo, para remover uma tag em um webhook chamado MyWebhook com a chave de tag Project:

aws codepipeline untag-resource --resource-arn arn:aws:codepipeline:us-west-2:account-id:webhook:MyWebhook --tag-keys Project

Se houver êxito, o comando não retorna nada. Para verificar as tags associadas ao webhook, execute o comando list-tags-for-resource.

Criar um webhook para uma origem do GitHub (modelo do AWS CloudFormation)

Para utilizar o AWS CloudFormation para criar um webhook, atualize seu modelo conforme descrito aqui.

Como adicionar parâmetros e criar um webhook em seu modelo

É altamente recomendável que você use o AWS Secrets Manager para armazenar suas credenciais. Se você usar o Secrets Manager, já terá configurado e armazenado seus parâmetros secretos no Secrets Manager. Este exemplo usa referências dinâmicas ao AWS Secrets Manager usando credenciais do GitHub para o webhook. Para obter mais informações, consulte Usar referências dinâmicas para especificar valores de modelo.

Importante

Ao transmitir parâmetros secretos, não insira o valor diretamente no modelo. O valor é renderizado como texto sem formatação e, portanto, é legível. Por motivos de segurança, não use texto sem formatação no modelo do AWS CloudFormation para armazenar suas credenciais.

Ao usar a CLI ou o AWS CloudFormation para criar um pipeline e adicionar um webhook, é necessário desativar as verificações periódicas.

nota

Para desativar as verificações periódicas, é necessário adicionar explicitamente o parâmetro PollForSourceChanges e defini-lo como falso, conforme descrito no procedimento final abaixo. Caso contrário, o padrão para um pipeline da CLI ou do AWS CloudFormation é que PollForSourceChanges seja padronizado como verdadeiro e não seja exibido na saída da estrutura de pipeline. Para obter mais informações sobre os padrões de PollForSourceChanges, consulte Configurações padrão do parâmetro PollForSourceChanges.

  1. No modelo, em Resources, adicione os parâmetros:

    YAML
    Parameters: GitHubOwner: Type: String ...
    JSON
    { "Parameters": { "BranchName": { "Description": "GitHub branch name", "Type": "String", "Default": "main" }, "GitHubOwner": { "Type": "String" }, ...
  2. Utilize o recurso AWS::CodePipeline::Webhook do AWS CloudFormation para adicionar um webhook.

    nota

    O TargetAction especificado deve corresponder à propriedade de Name da ação de origem definida no pipeline.

    Se RegisterWithThirdParty estiver definido como true, verifique se o usuário associado ao OAuthToken pode definir os escopos necessários no GitHub. O token e o webhook requerem os seguintes escopos do GitHub:

    • repo – usado para se obter o controle total para ler e efetuar pull de artefatos de repositórios públicos e privados para um pipeline.

    • admin:repo_hook – usado para se obter o controle total dos ganchos do repositório.

    Caso contrário, o GitHub retornará um 404. Para obter mais informações sobre o 404 retornado, consulte https://help.github.com/articles/about-webhooks.

    YAML
    AppPipelineWebhook: Type: AWS::CodePipeline::Webhook Properties: Authentication: GITHUB_HMAC AuthenticationConfiguration: SecretToken: {{resolve:secretsmanager:MyGitHubSecret:SecretString:token}} Filters: - JsonPath: "$.ref" MatchEquals: refs/heads/{Branch} TargetPipeline: !Ref AppPipeline TargetAction: SourceAction Name: AppPipelineWebhook TargetPipelineVersion: !GetAtt AppPipeline.Version RegisterWithThirdParty: true ...
    JSON
    "AppPipelineWebhook": { "Type": "AWS::CodePipeline::Webhook", "Properties": { "Authentication": "GITHUB_HMAC", "AuthenticationConfiguration": { "SecretToken": "{{resolve:secretsmanager:MyGitHubSecret:SecretString:token}}" }, "Filters": [ { "JsonPath": "$.ref", "MatchEquals": "refs/heads/{Branch}" } ], "TargetPipeline": { "Ref": "AppPipeline" }, "TargetAction": "SourceAction", "Name": "AppPipelineWebhook", "TargetPipelineVersion": { "Fn::GetAtt": [ "AppPipeline", "Version" ] }, "RegisterWithThirdParty": true } }, ...
  3. Salve o modelo atualizado em seu computador local e abra o console do AWS CloudFormation.

  4. Selecione sua pilha e clique em Create Change Set for Current Stack (Criar conjunto de alterações para a pilha atual).

  5. Carregue o modelo e visualize as alterações listadas no AWS CloudFormation. Essas são as alterações a serem feitas na pilha. Seus novos recursos devem ser exibidos na lista.

  6. Selecione Execute (Executar).

Editar o parâmetro PollForSourceChanges do pipeline

Importante

Ao criar um pipeline com esse método, o parâmetro PollForSourceChanges é padronizado como verdadeiro se não for explicitamente definido como falso. Ao adicionar a detecção de alterações baseada em eventos, é necessário adicionar o parâmetro a sua saída e defini-lo como falso para desativar a sondagem. Caso contrário, o pipeline inicia duas vezes para uma única alteração de origem. Para obter mais detalhes, consulte Configurações padrão do parâmetro PollForSourceChanges.

  • No modelo, altere PollForSourceChanges para false. Se você não incluir PollForSourceChanges na sua definição de pipeline, adicione-o e configure para falso.

    Por que estou fazendo essa alteração? A alteração deste parâmetro para false desativa as verificações periódicas para que você possa utilizar apenas a detecção de alterações baseada em eventos.

    YAML
    Name: Source Actions: - Name: SourceAction ActionTypeId: Category: Source Owner: ThirdParty Version: 1 Provider: GitHub OutputArtifacts: - Name: SourceOutput Configuration: Owner: !Ref GitHubOwner Repo: !Ref RepositoryName Branch: !Ref BranchName OAuthToken: {{resolve:secretsmanager:MyGitHubSecret:SecretString:token}} PollForSourceChanges: false RunOrder: 1
    JSON
    { "Name": "Source", "Actions": [ { "Name": "SourceAction", "ActionTypeId": { "Category": "Source", "Owner": "ThirdParty", "Version": 1, "Provider": "GitHub" }, "OutputArtifacts": [ { "Name": "SourceOutput" } ], "Configuration": { "Owner": { "Ref": "GitHubOwner" }, "Repo": { "Ref": "RepositoryName" }, "Branch": { "Ref": "BranchName" }, "OAuthToken": "{{resolve:secretsmanager:MyGitHubSecret:SecretString:token}}", "PollForSourceChanges": false }, "RunOrder": 1 }

Atualizar um pipeline de sondagem para uma ação de origem do GitHub versão 1

Atualizar um pipeline de sondagem para uma ação de origem do GitHub versão 1

Atualizar os pipelines para o envio de eventos (ações de origem do GitHub versão 1) (console)

Você pode usar o console do CodePipeline para atualizar seu pipeline para usar webhooks para detectar alterações em seu repositório de origem do CodeCommit.

Siga essas etapas para fazer com que um pipeline que conduz sondagem (verificações periódicas) passe a utilizar o Amazon CloudWatch Events. Se você deseja criar um pipeline, consulte Criar um pipeline no CodePipeline.

Ao utilizar o console, o parâmetro PollForSourceChanges para o seu pipeline é alterado. O webhook do GitHub será criado e registrado para você.

Para editar o estágio de origem do pipeline

  1. Faça login noAWS Management Consolee abra o console do CodePipeline emhttp://console.aws.amazon.com/codesuite/codepipeline/home.

    Os nomes de todos os pipelines associados à sua conta da AWS são exibidos.

  2. Em Nome, selecione o nome do pipeline que você deseja editar. Isso abrirá um visão detalhada do pipeline, incluindo o estado de cada uma das ações em cada estágio do pipeline.

  3. Na página de detalhes do pipeline, selecione Editar.

  4. Em Edit stage (Editar estágio), selecione o ícone de edição na ação de origem.

  5. Expanda Change detection options (Opções de detecção de alterações) e selecione Use Amazon CloudWatch Events to automatically start my pipeline when a change occurs (recommended) (Usar o Amazon CloudWatch Events para iniciar automaticamente o pipeline quando ocorrer uma alteração (recomendado)).

    É exibida uma mensagem para informar que o CodePipeline cria um webhook no GitHub para detectar alterações na origem:AWS O CodePipeline criará um webhook para você. Você pode optar por não participar nas opções abaixo. Escolha Update. Além do webhook, o CodePipeline cria o seguinte:

    • Um segredo, gerado aleatoriamente e utilizado para autorizar a conexão com o GitHub.

    • O URL do webhook, gerado por meio do uso do endpoint público da região.

    O CodePipeline registra o webhookcom o GitHub. Isso inscreve o URL para receber eventos de repositório.

  6. Quando terminar de editar seu pipeline, selecione Salvar alterações do pipeline para voltar à página de resumo.

    Uma mensagem exibe o nome do webhook a ser criado para o pipeline. Escolha Save and continue.

  7. Para testar a ação, utilize a AWS CLI para confirmar uma mudança à origem especificada no estágio de origem do pipeline para que seja possível liberar uma alteração.

Atualizar os pipelines para o envio de eventos (origem do GitHub versão 1) (CLI)

Siga essas etapas para fazer com que um pipeline que conduz sondagem (verificações periódicas) passe a utilizar um webhook. Se você deseja criar um pipeline, consulte Criar um pipeline no CodePipeline.

Para criar um pipeline baseado em eventos, edite o parâmetro PollForSourceChanges de seu pipeline e crie os seguintes recursos manualmente:

  • Parâmetros de autorização e webhook do GitHub

Para criar e registrar seu webhook

nota

Ao usar a CLI ou o AWS CloudFormation para criar um pipeline e adicionar um webhook, é necessário desativar as verificações periódicas. Para desativar as verificações periódicas, é necessário adicionar explicitamente o parâmetro PollForSourceChanges e defini-lo como falso, conforme descrito no procedimento final abaixo. Caso contrário, o padrão para um pipeline da CLI ou do AWS CloudFormation é que PollForSourceChanges seja padronizado como verdadeiro e não seja exibido na saída da estrutura de pipeline. Para obter mais informações sobre os padrões de PollForSourceChanges, consulte Configurações padrão do parâmetro PollForSourceChanges.

  1. Em um editor de texto, crie e salve um arquivo JSON para o webhook que deseja criar. Use esse exemplo de arquivo para um webhook denominado my-webhook:

    {"webhook": {"name": "my-webhook", "targetPipeline": "pipeline_name", "targetAction": "source_action_name", "filters": [ { "jsonPath": "$.ref", "matchEquals": "refs/heads/{Branch}" } ], "authentication": "GITHUB_HMAC", "authenticationConfiguration": {"SecretToken":"secret"} } }
  2. Use o comando put-webhook e inclua os parâmetros --cli-input e --region.

    O exemplo de comando a seguir cria um webhook com o arquivo JSON webhook_json.

    aws codepipeline put-webhook --cli-input-json file://webhook_json.json --region "eu-central-1"
  3. Na saída mostrada neste exemplo, a URL e o ARN são retornados para um webhook denominado my-webhook.

    { "webhook": { "url": "https://webhooks.domain.com/trigger111111111EXAMPLE11111111111111111", "definition": { "authenticationConfiguration": { "SecretToken": "secret" }, "name": "my-webhook", "authentication": "GITHUB_HMAC", "targetPipeline": "pipeline_name", "targetAction": "Source", "filters": [ { "jsonPath": "$.ref", "matchEquals": "refs/heads/{Branch}" } ] }, "arn": "arn:aws:codepipeline:eu-central-1:ACCOUNT_ID:webhook:my-webhook" }, "tags": [{ "key": "Project", "value": "ProjectA" }] }

    Este exemplo adiciona tags ao webhook incluindo a chave de tag Project e o valor ProjectA no webhook. Para obter mais informações sobre a marcação de recursos no CodePipeline, consulteMarcar recursos do .

  4. Use o comando register-webhook-with-third-party e inclua o parâmetro --webhook-name.

    O exemplo de comando a seguir registra um webhook denominado my-webhook.

    aws codepipeline register-webhook-with-third-party --webhook-name my-webhook

Editar o parâmetro PollForSourceChanges do pipeline

Importante

Ao criar um pipeline com esse método, o parâmetro PollForSourceChanges é padronizado como verdadeiro se não for explicitamente definido como falso. Ao adicionar a detecção de alterações baseada em eventos, é necessário adicionar o parâmetro a sua saída e defini-lo como falso para desativar a sondagem. Caso contrário, o pipeline inicia duas vezes para uma única alteração de origem. Para obter mais detalhes, consulte Configurações padrão do parâmetro PollForSourceChanges.

  1. Execute o get-pipeline comando para copiar a estrutura do pipeline em um arquivo JSON. Por exemplo, para um pipeline chamado MyFirstPipeline, você deve digitar o seguinte comando:

    aws codepipeline get-pipeline --name MyFirstPipeline >pipeline.json

    Este comando retorna nada, mas o arquivo que você criou deve aparecer no diretório onde você executou o comando.

  2. Abra o arquivo JSON em qualquer editor de texto plano e altere ou adicione o parâmetro PollForSourceChanges para editar o estágio de origem. Neste exemplo, para um repositório denominado UserGitHubRepo, o parâmetro é definido como false.

    Por que estou fazendo essa alteração? A alteração deste parâmetro para desativa as verificações periódicas para que você possa utilizar apenas a detecção de alterações baseada em eventos.

    "configuration": { "Owner": "darlaker", "Repo": "UserGitHubRepo", "PollForSourceChanges": "false", "Branch": "main", "OAuthToken": "****" },
  3. Se você estiver trabalhando com a estrutura de pipeline recuperada por meio do comando get-pipeline, é necessário editar a estrutura no arquivo JSON por meio da remoção das linhas metadata do arquivo. Caso contrário, o comando update-pipeline não é capaz de utilizá-la. Remova a seção "metadata" da estrutura do pipeline no arquivo JSON, incluindo os campos: { }, "created", "pipelineARN" e "updated".

    Por exemplo, remova as seguintes linhas da estrutura:

    "metadata": { "pipelineArn": "arn:aws:codepipeline:region:account-ID:pipeline-name", "created": "date", "updated": "date" }

    Salve o arquivo.

  4. Para aplicar suas alterações, execute o comando update-pipeline, especificando o pipeline do arquivo JSON, de modo semelhante ao seguinte:

    Importante

    Não se esqueça de incluir file:// antes do nome de arquivo. Ele é obrigatório nesse comando.

    aws codepipeline update-pipeline --cli-input-json file://pipeline.json

    Este comando retorna toda a estrutura do pipeline editado.

    nota

    O comando update-pipeline interrompe o pipeline. Se uma revisão estiver sendo executada pelo pipeline quando você executar o comando update-pipeline, essa execução será interrompida. Você deve iniciar manualmente o pipeline para executar a revisão através do pipeline atualizado. Use o comando start-pipeline-execution para iniciar manualmente o pipeline.

Atualizar os pipelines para o envio de eventos (ações de origem do GitHub versão 1) (AWS CloudFormationTemplate)

Siga estas etapas para atualizar o pipeline (com uma origem do GitHub) de verificações periódicas (sondagem) para detecção de alterações baseada em eventos usando webhooks.

Para criar um pipeline orientado por eventos comAWS CodeCommit, você edita oPollForSourceChangesdo seu pipeline e, em seguida, adicione um recurso GitHub webhook ao seu modelo.

Ao utilizar o AWS CloudFormation para criar e gerenciar seus pipelines, o modelo apresenta um conteúdo semelhante ao seguinte:

nota

Observe a propriedade de configuração PollForSourceChanges no estágio de origem. Se o seu modelo não inclui essa propriedade, PollForSourceChanges é definido como true por padrão.

YAML
Resources: AppPipeline: Type: AWS::CodePipeline::Pipeline Properties: Name: github-polling-pipeline RoleArn: !GetAtt CodePipelineServiceRole.Arn Stages: - Name: Source Actions: - Name: SourceAction ActionTypeId: Category: Source Owner: ThirdParty Version: 1 Provider: GitHub OutputArtifacts: - Name: SourceOutput Configuration: Owner: !Ref GitHubOwner Repo: !Ref RepositoryName Branch: !Ref BranchName OAuthToken: {{resolve:secretsmanager:MyGitHubSecret:SecretString:token}} PollForSourceChanges: true RunOrder: 1 ...
JSON
"AppPipeline": { "Type": "AWS::CodePipeline::Pipeline", "Properties": { "Name": "github-polling-pipeline", "RoleArn": { "Fn::GetAtt": [ "CodePipelineServiceRole", "Arn" ] }, "Stages": [ { "Name": "Source", "Actions": [ { "Name": "SourceAction", "ActionTypeId": { "Category": "Source", "Owner": "ThirdParty", "Version": 1, "Provider": "GitHub" }, "OutputArtifacts": [ { "Name": "SourceOutput" } ], "Configuration": { "Owner": { "Ref": "GitHubOwner" }, "Repo": { "Ref": "RepositoryName" }, "Branch": { "Ref": "BranchName" }, "OAuthToken": "{{resolve:secretsmanager:MyGitHubSecret:SecretString:token}}", "PollForSourceChanges": true }, "RunOrder": 1 } ] }, ...

Como adicionar parâmetros e criar um webhook em seu modelo

É altamente recomendável que você use o AWS Secrets Manager para armazenar suas credenciais. Se você usar o Secrets Manager, já terá configurado e armazenado seus parâmetros secretos no Secrets Manager. Este exemplo usa referências dinâmicas ao AWS Secrets Manager usando credenciais do GitHub para o webhook. Para obter mais informações, consulte Usar referências dinâmicas para especificar valores de modelo.

Importante

Ao transmitir parâmetros secretos, não insira o valor diretamente no modelo. O valor é renderizado como texto sem formatação e, portanto, é legível. Por motivos de segurança, não use texto sem formatação no modelo do AWS CloudFormation para armazenar suas credenciais.

Ao usar a CLI ou o AWS CloudFormation para criar um pipeline e adicionar um webhook, é necessário desativar as verificações periódicas.

nota

Para desativar as verificações periódicas, é necessário adicionar explicitamente o parâmetro PollForSourceChanges e defini-lo como falso, conforme descrito no procedimento final abaixo. Caso contrário, o padrão para um pipeline da CLI ou do AWS CloudFormation é que PollForSourceChanges seja padronizado como verdadeiro e não seja exibido na saída da estrutura de pipeline. Para obter mais informações sobre os padrões de PollForSourceChanges, consulte Configurações padrão do parâmetro PollForSourceChanges.

  1. No modelo, em Resources, adicione os parâmetros:

    YAML
    Parameters: GitHubOwner: Type: String ...
    JSON
    { "Parameters": { "BranchName": { "Description": "GitHub branch name", "Type": "String", "Default": "main" }, "GitHubOwner": { "Type": "String" }, ...
  2. Utilize o recurso AWS::CodePipeline::Webhook do AWS CloudFormation para adicionar um webhook.

    nota

    O TargetAction especificado deve corresponder à propriedade de Name da ação de origem definida no pipeline.

    Se RegisterWithThirdParty estiver definido como true, verifique se o usuário associado ao OAuthToken pode definir os escopos necessários no GitHub. O token e o webhook requerem os seguintes escopos do GitHub:

    • repo – usado para se obter o controle total para ler e efetuar pull de artefatos de repositórios públicos e privados para um pipeline.

    • admin:repo_hook – usado para se obter o controle total dos ganchos do repositório.

    Caso contrário, o GitHub retornará um 404. Para obter mais informações sobre o 404 retornado, consulte https://help.github.com/articles/about-webhooks.

    YAML
    AppPipelineWebhook: Type: AWS::CodePipeline::Webhook Properties: Authentication: GITHUB_HMAC AuthenticationConfiguration: SecretToken: {{resolve:secretsmanager:MyGitHubSecret:SecretString:token}} Filters: - JsonPath: "$.ref" MatchEquals: refs/heads/{Branch} TargetPipeline: !Ref AppPipeline TargetAction: SourceAction Name: AppPipelineWebhook TargetPipelineVersion: !GetAtt AppPipeline.Version RegisterWithThirdParty: true ...
    JSON
    "AppPipelineWebhook": { "Type": "AWS::CodePipeline::Webhook", "Properties": { "Authentication": "GITHUB_HMAC", "AuthenticationConfiguration": { "SecretToken": "{{resolve:secretsmanager:MyGitHubSecret:SecretString:token}}" }, "Filters": [ { "JsonPath": "$.ref", "MatchEquals": "refs/heads/{Branch}" } ], "TargetPipeline": { "Ref": "AppPipeline" }, "TargetAction": "SourceAction", "Name": "AppPipelineWebhook", "TargetPipelineVersion": { "Fn::GetAtt": [ "AppPipeline", "Version" ] }, "RegisterWithThirdParty": true } }, ...
  3. Salve o modelo atualizado em seu computador local e abra o console do AWS CloudFormation.

  4. Selecione sua pilha e clique em Create Change Set for Current Stack (Criar conjunto de alterações para a pilha atual).

  5. Carregue o modelo e visualize as alterações listadas no AWS CloudFormation. Essas são as alterações a serem feitas na pilha. Seus novos recursos devem ser exibidos na lista.

  6. Selecione Execute (Executar).

Editar o parâmetro PollForSourceChanges do pipeline

Importante

Ao criar um pipeline com esse método, o parâmetro PollForSourceChanges é padronizado como verdadeiro se não for explicitamente definido como falso. Ao adicionar a detecção de alterações baseada em eventos, é necessário adicionar o parâmetro a sua saída e defini-lo como falso para desativar a sondagem. Caso contrário, o pipeline inicia duas vezes para uma única alteração de origem. Para obter mais detalhes, consulte Configurações padrão do parâmetro PollForSourceChanges.

  • No modelo, altere PollForSourceChanges para false. Se você não incluir PollForSourceChanges na sua definição de pipeline, adicione-o e configure para falso.

    Por que estou fazendo essa alteração? A alteração deste parâmetro para false desativa as verificações periódicas para que você possa utilizar apenas a detecção de alterações baseada em eventos.

    YAML
    Name: Source Actions: - Name: SourceAction ActionTypeId: Category: Source Owner: ThirdParty Version: 1 Provider: GitHub OutputArtifacts: - Name: SourceOutput Configuration: Owner: !Ref GitHubOwner Repo: !Ref RepositoryName Branch: !Ref BranchName OAuthToken: {{resolve:secretsmanager:MyGitHubSecret:SecretString:token}} PollForSourceChanges: false RunOrder: 1
    JSON
    { "Name": "Source", "Actions": [ { "Name": "SourceAction", "ActionTypeId": { "Category": "Source", "Owner": "ThirdParty", "Version": 1, "Provider": "GitHub" }, "OutputArtifacts": [ { "Name": "SourceOutput" } ], "Configuration": { "Owner": { "Ref": "GitHubOwner" }, "Repo": { "Ref": "RepositoryName" }, "Branch": { "Ref": "BranchName" }, "OAuthToken": "{{resolve:secretsmanager:MyGitHubSecret:SecretString:token}}", "PollForSourceChanges": false }, "RunOrder": 1 }

Ao criar esses recursos com o AWS CloudFormation, o webhook definido é criado no repositório GitHub especificado. Seu pipeline é acionado durante a confirmação.

YAML
Parameters: GitHubOwner: Type: String Resources: AppPipelineWebhook: Type: AWS::CodePipeline::Webhook Properties: Authentication: GITHUB_HMAC AuthenticationConfiguration: SecretToken: {{resolve:secretsmanager:MyGitHubSecret:SecretString:token}} Filters: - JsonPath: "$.ref" MatchEquals: refs/heads/{Branch} TargetPipeline: !Ref AppPipeline TargetAction: SourceAction Name: AppPipelineWebhook TargetPipelineVersion: !GetAtt AppPipeline.Version RegisterWithThirdParty: true AppPipeline: Type: AWS::CodePipeline::Pipeline Properties: Name: github-events-pipeline RoleArn: !GetAtt CodePipelineServiceRole.Arn Stages: - Name: Source Actions: - Name: SourceAction ActionTypeId: Category: Source Owner: ThirdParty Version: 1 Provider: GitHub OutputArtifacts: - Name: SourceOutput Configuration: Owner: !Ref GitHubOwner Repo: !Ref RepositoryName Branch: !Ref BranchName OAuthToken: {{resolve:secretsmanager:MyGitHubSecret:SecretString:token}} PollForSourceChanges: false RunOrder: 1 ...
JSON
{ "Parameters": { "BranchName": { "Description": "GitHub branch name", "Type": "String", "Default": "main" }, "RepositoryName": { "Description": "GitHub repository name", "Type": "String", "Default": "test" }, "GitHubOwner": { "Type": "String" }, "ApplicationName": { "Description": "CodeDeploy application name", "Type": "String", "Default": "DemoApplication" }, "BetaFleet": { "Description": "Fleet configured in CodeDeploy", "Type": "String", "Default": "DemoFleet" } }, "Resources": { ... }, "AppPipelineWebhook": { "Type": "AWS::CodePipeline::Webhook", "Properties": { "Authentication": "GITHUB_HMAC", "AuthenticationConfiguration": { "SecretToken": { "{{resolve:secretsmanager:MyGitHubSecret:SecretString:token}}" } }, "Filters": [ { "JsonPath": "$.ref", "MatchEquals": "refs/heads/{Branch}" } ], "TargetPipeline": { "Ref": "AppPipeline" }, "TargetAction": "SourceAction", "Name": "AppPipelineWebhook", "TargetPipelineVersion": { "Fn::GetAtt": [ "AppPipeline", "Version" ] }, "RegisterWithThirdParty": true } }, "AppPipeline": { "Type": "AWS::CodePipeline::Pipeline", "Properties": { "Name": "github-events-pipeline", "RoleArn": { "Fn::GetAtt": [ "CodePipelineServiceRole", "Arn" ] }, "Stages": [ { "Name": "Source", "Actions": [ { "Name": "SourceAction", "ActionTypeId": { "Category": "Source", "Owner": "ThirdParty", "Version": 1, "Provider": "GitHub" }, "OutputArtifacts": [ { "Name": "SourceOutput" } ], "Configuration": { "Owner": { "Ref": "GitHubOwner" }, "Repo": { "Ref": "RepositoryName" }, "Branch": { "Ref": "BranchName" }, "OAuthToken": "{{resolve:secretsmanager:MyGitHubSecret:SecretString:token}}", "PollForSourceChanges": false }, "RunOrder": 1 ...

Configurar autenticação (ações de origem do GitHub versão 1)

O CodePipeline usa tokens OAuth do GitHub e tokens de acesso pessoal para acessar os repositórios do GitHub e recuperar as alterações mais recentes. Há duas maneiras de configurar a autenticação no GitHub:

  • AWSO cria um padrão doAWSGerenciou o token OAuth quando você usa o console para criar ou atualizar pipelines.

  • Você pode criar e gerenciar seus tokens de acesso pessoal gerados pelo cliente. Você precisa de tokens de acesso pessoal ao usar a CLI, SDK ou o AWS CloudFormation para criar ou atualizar o pipeline.

Visualizar aplicativos OAuth autorizados

O CodePipeline usa tokens OAuth para integração com o GitHub. O GitHub monitora as permissões do token OAuth para o CodePipeline.

Para visualizar suas integrações autorizadas no GitHub

  1. No GitHub, na opção suspensa em sua foto de perfil, escolha Settings.

  2. Escolha Applications (Aplicativos) e Authorized OAuth Apps (Aplicativos OAuth autorizados).

  3. Revise seus aplicativos autorizados.

Configurar o pipeline para usar um token de acesso pessoal (GitHub e CLI)

Você pode configurar o pipeline para usar um token de acesso pessoal para se conectar ao GitHub. A vantagem de usar tokens em vez de senhas em um script é que os tokens podem ser revogados ou alternados. Você pode ainda conceder privilégios e permissões específicos a um token de acesso pessoal. Cada token de acesso pessoal está associado no nível do pipeline, não no da conta.

nota

Talvez você precise atualizar outros aplicativos se eles estiverem usando o mesmo token de acesso pessoal. Uma prática de segurança recomendada é não compartilhar um único token entre vários aplicativos. Crie um token de acesso pessoal para cada aplicativo. Para obter mais informações, consulte Creating a personal access token for the command line no site do GitHub.

Para criar um token de acesso pessoal do GitHub e atualizar a estrutura do pipeline com o novo token

  1. No GitHub, na opção suspensa em sua foto de perfil, escolha Settings.

  2. Escolha Developer settings (Configurações do desenvolvedor) e selecione Personal access tokens (Tokens de acesso pessoal).

  3. Escolha Generate new token (Gerar novo token).

    ONovo token de acesso pessoal doA página é exibida.

  4. Em Select scopes (Selecionar escopos), selecione admin:repo_hook e repo.

  5. Escolha Generate token (Gerar token).

  6. Ao lado do token gerado, escolha o ícone de copiar.

    nota

    Copie o token quando ele for gerado. Você não pode visualizar o token após fechar esta página.

  7. Em um terminal (Linux, macOS ou Unix) ou prompt de comando (Windows), execute oget-pipelineNo pipeline em que você deseja alterar o token OAuth e depois copie a saída do comando para um arquivo JSON. Por exemplo, para um pipeline chamado MyFirstPipeline, você deve digitar algo semelhante ao seguinte:

    aws codepipeline get-pipeline --name MyFirstPipeline >pipeline.json

    A saída do comando é enviada ao arquivo pipeline.json.

  8. Abra o arquivo em um editor de texto plano e edite o valor no OAuthTokenField de sua ação do GitHub.

    Ao usar a AWS CLI para criar o pipeline, é possível transmitir um token de acesso pessoal do GitHub nesse campo. Substitua os asteriscos (****) com o token que você copiou do GitHub. Quando get-pipeline é executado para visualizar a configuração da ação, a máscara de quatro asteriscos é exibida para esse valor. Por exemplo, para um token de acesso pessoal com o valor 111222333444555666777888EXAMPLE:

    "configuration": { "Owner": "MyGitHubUserName", "Repo": "test-repo", "Branch": "main", "OAuthToken": "111222333444555666777888EXAMPLE" }
    nota

    Quando um modelo do AWS CloudFormation é usado para criar o pipeline, primeiro é necessário armazenar o token como um segredo no AWS Secrets Manager. Inclua o valor desse campo como uma referência dinâmica para o segredo armazenado no Secrets Manager. Para ver um exemplo, consulte Referência da estrutura de ação de origem do GitHub versão 1.

  9. Se você estiver trabalhando com a estrutura de pipeline recuperada por meio do comando get-pipeline, será necessário modificar a estrutura no arquivo JSON por meio da remoção das linhas metadata do arquivo. Caso contrário, o comando update-pipeline não é capaz de utilizá-la. Remova a seção da estrutura do pipeline no arquivo JSON (as linhas de "metadata": { } e os campos "created", "pipelineARN" e "updated").

    Por exemplo, remova as seguintes linhas da estrutura:

    "metadata": { "pipelineArn": "arn:aws:codepipeline:region:account-ID:pipeline-name", "created": "date", "updated": "date" }
  10. Salve o arquivo e depois execute update-pipeline com o parâmetro --cli-input-json para especificar o arquivo JSON recém-editado.

    Por exemplo, para atualizar um pipeline chamado MyFirstPipeline, você deve digitar algo semelhante ao seguinte:

    aws codepipeline update-pipeline --cli-input-json file://pipeline.json
    Importante

    Não se esqueça de incluir file:// antes do nome de arquivo. Ele é obrigatório nesse comando.

  11. Repita as etapas de 6 a 8 para cada pipeline que contém uma ação de GitHub.

  12. Ao concluir, exclua os arquivos JSON usados para atualizar os pipelines.

Use o GitHub e a CLI do CodePipeline para criar e alternar regularmente o token de acesso pessoal do GitHub

A vantagem de usar tokens em vez de senhas em um script é que os tokens podem ser revogados ou alternados. Você pode ainda conceder privilégios e permissões específicos a um token de acesso pessoal. Os tokens devem ser armazenados de forma segura e alternados ou regenerados regularmente. A alternância de tokens é recomenda pela RFC-6819 (OAuth 2.0 Threat Model and Security Considerations), seção 5.1.5.3.

Para obter mais informações, consulte Creating a personal access token for the command line no site do GitHub.

Depois de gerar novamente um novo token de acesso pessoal, poderá alterná-lo por meio da AWS CLI ou da API, ou usando o AWS CloudFormation e chamando UpdatePipeline.

nota

Talvez você precise atualizar outros aplicativos se eles estiverem usando o mesmo token de acesso pessoal. Uma prática de segurança recomendada é não compartilhar um único token entre vários aplicativos. Crie um novo token de acesso pessoal para cada aplicativo.

Use estas etapas para alternar o token de acesso pessoal do GitHub e, em seguida, atualize a estrutura do pipeline com o novo token.

nota

Depois de alternar o token de acesso pessoal, lembre-se de atualizar qualquer script da AWS CLI ou modelos do AWS CloudFormation que contenham informações sobre o token antigo.

  1. No GitHub, na opção suspensa em sua foto de perfil, escolha Settings.

  2. Escolha Developer settings (Configurações do desenvolvedor) e selecione Personal access tokens (Tokens de acesso pessoal).

  3. Próximo ao token de acesso pessoal do GitHub, escolha Edit.

  4. Escolha Regenerar token.

  5. Ao lado do token regenerado, escolha o ícone de copiar.

  6. Em um terminal (Linux, macOS ou Unix) ou prompt de comando (Windows), execute oget-pipelineNo pipeline em que você deseja alterar o token de acesso pessoal e depois copie a saída do comando para um arquivo JSON. Por exemplo, para um pipeline chamado MyFirstPipeline, você deve digitar algo semelhante ao seguinte:

    aws codepipeline get-pipeline --name MyFirstPipeline >pipeline.json

    A saída do comando é enviada ao arquivo pipeline.json.

  7. Abra o arquivo em um editor de texto plano e edite o valor no OAuthTokenField de sua ação do GitHub.

    Ao usar a AWS CLI para criar o pipeline, é possível transmitir um token de acesso pessoal do GitHub nesse campo. Substitua os asteriscos (****) com o token que você copiou do GitHub. Quando get-pipeline é executado para visualizar a configuração da ação, a máscara de quatro asteriscos é exibida para esse valor. Por exemplo, para um token de acesso pessoal com o valor 111222333444555666777888EXAMPLE:

    "configuration": { "Owner": "MyGitHubUserName", "Repo": "test-repo", "Branch": "main", "OAuthToken": "111222333444555666777888EXAMPLE" }
    nota

    Quando um modelo do AWS CloudFormation é usado para atualizar o pipeline, primeiro é necessário armazenar o token como um segredo no AWS Secrets Manager. Inclua o valor desse campo como uma referência dinâmica para o segredo armazenado no Secrets Manager. Para ver um exemplo, consulte Referência da estrutura de ação de origem do GitHub versão 1.

  8. Se você estiver trabalhando com a estrutura de pipeline recuperada por meio do comando get-pipeline, será necessário modificar a estrutura no arquivo JSON por meio da remoção das linhas metadata do arquivo. Caso contrário, o comando update-pipeline não é capaz de utilizá-la. Remova a seção da estrutura do pipeline no arquivo JSON (as linhas de "metadata": { } e os campos "created", "pipelineARN" e "updated").

    Por exemplo, remova as seguintes linhas da estrutura:

    "metadata": { "pipelineArn": "arn:aws:codepipeline:region:account-ID:pipeline-name", "created": "date", "updated": "date" }
  9. Salve o arquivo e depois execute update-pipeline com o parâmetro --cli-input-json para especificar o arquivo JSON recém-editado. Por exemplo, para atualizar um pipeline chamado MyFirstPipeline, você deve digitar algo semelhante ao seguinte:

    Importante

    Não se esqueça de incluir file:// antes do nome de arquivo. Ele é obrigatório nesse comando.

    aws codepipeline update-pipeline --cli-input-json file://pipeline.json
  10. Quando terminar de atualização seus pipelines, exclua os arquivos JSON.

Para obter mais informações, consulte Erro de pipeline: “Não foi possível acessar o repositório do GitHub” ou “Não foi possível conectar ao repositório do GitHub” (ações de origem do GitHub versão 1).

Tutorial: Crie um pipeline com oAWS CloudFormation(Ações de origem do GitHub versão 1)

nota

A ação do GitHub versão 1 não é recomendada. Para um pipeline com uma ação do GitHub versão 1, o CodePipeline usa tokens baseados em OAuthh para se conectar ao repositório do GitHub. Por outro lado, a ação do GitHub (versão 2) usa um recurso de conexão para associarAWSRecursos do para o repositório do GitHub. O recurso de conexão usa tokens baseados em aplicativo para se conectar. Para obter mais informações sobre como atualizar seu pipeline para a ação recomendada do GitHub que usa uma conexão, consulteAtualizar uma ação de origem do GitHub versão 1 para uma ação de origem do GitHub versão 2.

Este tutorial mostra como usar aAWS CloudFormationPara criar uma infraestrutura que inclui um pipeline conectado a um repositório de origem do GitHub. Neste tutorial, você utiliza o arquivo de modelo de exemplo para criar sua pilha de recursos, que inclui o armazenamento de artefatos, pipeline e recursos de detecção de alterações (seu webhook). Depois de criar sua pilha de recursos no AWS CloudFormation, você pode visualizar seu pipeline no console do AWS CodePipeline. O pipeline é composto por dois estágios, com um estágio de origem do GitHub e um estágio de implantação do CodeDeploy.

É altamente recomendável que você use o AWS Secrets Manager para armazenar suas credenciais. Se você usar o Secrets Manager, já terá configurado e armazenado seus parâmetros secretos no Secrets Manager. Este exemplo usa referências dinâmicas aAWSO Secrets Manager para as credenciais do GitHub para o webhook. Para obter mais informações, consulte Usar referências dinâmicas para especificar valores de modelo.

Importante

Ao transmitir parâmetros secretos, não insira o valor diretamente no modelo. O valor é renderizado como texto sem formatação e, portanto, é legível. Por motivos de segurança, não use texto sem formatação no modelo do AWS CloudFormation para armazenar suas credenciais.

Pré-requisitos:

Você deve ter criado os seguintes recursos para uso com o modelo do AWS CloudFormation de exemplo:

  • Um aplicativo e um grupo de implantação do CodeDeploy Use os recursos do CodeDeploy criados noTutorial: Criar um pipeline simples (repositório CodeCommit).

  • Escolha um desses links para fazer download do exemplo doAWS CloudFormationArquivo de modelo para criar um pipeline: YAML|JSON

    Descompacte o arquivo e coloque-o em seu computador local.

  • Os modelos de exemplo no marcador acima são configurados para usar um token secreto do GitHub com essa referência dinâmica ao token armazenado noAWS Secrets Manager: {{resolve:secretsmanager:MyGitHubSecret:SecretString:token}}. É necessário criar um token do GitHub e armazená-lo no Secrets Manager para usar a referência dinâmica no modelo para seuOAuthTokeneSecretTokenCampos do.

  • Baixe o SampleApp_Linux.zip.

  • A ramificação e o repositório GitHub que você deseja utilizar para sua origem.

  • Uma chave de acesso pessoal para seu repositório GitHub. Ela será utilizada para fornecer um token OAuth para conexão com o repositório.

Para criar sua pilha noAWS CloudFormation

  1. Descompacte os arquivos do SampleApp_Linux.zip e faça upload deles em seu repositório GitHub. Você deve carregar os arquivos descompactados no diretório raiz do seu repositório.

  2. Abra o console do AWS CloudFormation e selecione Create Stack (Criar pilha).

  3. Em Choose a template (Selecionar um modelo), selecione Upload a template to Amazon S3 (Carregar um modelo no Amazon S3). Selecione Browse (Procurar) e selecione o arquivo do modelo no seu computador local. Escolha Next (Próximo).

  4. Em Stack name (Nome da pilha), insira um nome para o pipeline. Os parâmetros especificados pelo modelo de exemplo são exibidos. Insira os seguintes parâmetros:

    1. DentroApplicationName, insira o nome do aplicativo CodeDeploy.

    2. DentroBetaFleet, insira o nome do grupo de implantação do CodeDeploy.

    3. Em BranchName, informe a ramificação do repositório que você deseja usar.

    4. Em GitHubOAuthToken, informe a chave de acesso pessoal para seu repositório GitHub.

    5. Em GitHubOwner, informe o nome de usuário do GitHub para o proprietário do repositório.

    6. Em GitHubSecret, informe o segredo que deseja utilizar para a criação do webhook do AWS CloudFormation.

    7. Em RepositoryName, informe o nome do seu repositório GitHub de origem.

  5. Escolha Next (Próximo). Aceite os padrões na página a seguir e selecione Next (Próximo).

  6. DentroCapacidades, selecioneEu reconheço queAWSCloudFormation pode criar recursos do IAMe, depois, escolhaCriar.

  7. Após a conclusão da criação da pilha, visualize a lista de eventos para verificar se há erros.

  8. Faça login noAWS Management Consolee abra o console do CodePipeline emhttps://console.aws.amazon.com/codepipeline/.

    Em Pipelines, selecione o pipeline e clique em View (Visualizar). O diagrama mostra os estágios de implantação e a origem do pipeline.

  9. No seu repositório de origem, confirme e envie uma alteração. Seus recursos de detecção de alterações capturam a alteração e o pipeline é iniciado.

Solução de problemas (ações de origem do GitHub versão 1)

Erro de pipeline: O estágio de origem do GitHub contém submódulos do Git, mas o CodePipeline não os inicializa (ações de origem do GitHub versão 1)

Problema: CodePipeline não suporta submódulos git. O CodePipeline se baseia no link de arquivo API do GitHub, que não suporta os submódulos.

Correções possíveis: Considere a clonagem do repositório GitHub diretamente como parte de um script separado. Por exemplo, você pode incluir uma ação de clonagem em um script de Jenkins.

Erro de pipeline: “Não foi possível acessar o repositório do GitHub” ou “Não foi possível conectar ao repositório do GitHub” (ações de origem do GitHub versão 1)

Problema: O CodePipeline usa tokens OAuth para integração com o GitHub. Quando você cria um pipeline com um provedor de origem GitHub, o CodePipeline gerencia suas credenciais do GitHub criando um token OAuth padrão. Quando o pipeline se conecta ao repositório, ele usa as credenciais do GitHub para se conectar ao GitHub. As credenciais de token OAuth são gerenciadas pelo CodePipeline. Você não visualiza ou gerencia o token de forma alguma. O outro tipo de credenciais que você pode usar para se conectar ao GitHub são tokens de acesso pessoal, que são criados por você, em vez de por aplicativos OAuth. Tokens de acesso pessoal são gerenciados por você e não pelo CodePipeline.

Se essas permissões foram revogadas ou desabilitadas, o pipeline falha quando não pode usar o token do GitHub para se conectar ao repositório.

Trata-se de uma prática de segurança recomendada para alternar o token de acesso pessoal em períodos regulares. Para obter mais informações, consulte Use o GitHub e a CLI do CodePipeline para criar e alternar regularmente o token de acesso pessoal do GitHub.

Correções possíveis:

Se o CodePipeline não consegue se conectar ao repositório do GitHub, há duas opções para solucionar o problema:

  • Você pode simplesmente precisar reconectar o pipeline ao repositório manualmente. Pode ser que você tenha revogado as permissões do token OAuth para CodePipeline e elas só precisam ser restauradas. Para fazer isso, siga as etapas abaixo.

  • Talvez você precise alterar o token OAuth padrão para um token de acesso pessoal. O número de tokens OAuth é limitado. Para mais informações, consulte a Documentação do GitHub. Se o CodePipeline atingir esse limite, os tokens mais antigos vão parar de funcionar, e as ações em pipelines que dependem desse token falharão.

  1. Verifique se as permissões para CodePipeline foram revogadas. Para as etapas de verificação da lista de Aplicativos OAuth autorizados no GitHub, consulte Visualizar aplicativos OAuth autorizados. Se o CodePipeline não aparecer na lista, você deve usar o console para reconectar o pipeline ao GitHub.

    1. Abra o pipeline no console e escolha Edit (Editar). Com o estágio de origem que contém a ação de origem do GitHub, escolha Edit stage (Editar estágio).

    2. Na ação de origem do GitHub, escolha o ícone de edição.

    3. Na página Edit action (Editar ação), escolha Connect to Github (Conectar-se ao GitHub) para restaurar a autorização.

      Se solicitado, pode ser necessário inserir novamente o Repository (Repositório) e a Branch (Ramificação) para sua ação. Escolha Done (Concluído). Escolha Done (Concluído) na página de edição de estágio e Save (Salvar) na página de edição do pipeline. Execute o pipeline.

  2. Se isso não corrigir o erro, mas você pode ver CodePipeline noAplicativos OAuth autorizadosNo GitHub, talvez você tenha excedido o número de tokens permitido. Para corrigir o problema, você pode configurar manualmente um token OAuth como um token de acesso pessoal e configurar todos os pipelines em sua conta da AWS para usar esse token. Para obter mais informações, consulte Configurar o pipeline para usar um token de acesso pessoal (GitHub e CLI).