Automatizar a inicialização de pipelines usando gatilhos e filtragem

Os gatilhos permitem configurar o pipeline para iniciar em um determinado tipo de evento ou tipo de evento filtrado, como quando uma alteração em uma ramificação específica ou solicitação pull é detectada. Os gatilhos são configuráveis ​​para ações de origem com conexões que usam a ação CodeStarSourceConnection no CodePipeline, como GitHub, Bitbucket e GitLab. Para ter mais informações sobre ações de origem que usam conexões, consulte Adicionar provedores de origem de terceiros usando CodeConnections.

As ações de origem, como CodeCommit e S3, usam detecção automática de alterações para iniciar os pipelines quando uma alteração é feita. Para obter mais informações, consulte Ações de origem do CodeCommit e EventBridge.

Você especifica gatilhos usando o console ou a CLI.

Você especifica os tipos de filtro da seguinte forma:

• Sem filtro

  Esta configuração de gatilho inicia o pipeline em qualquer envio para a ramificação padrão especificada como parte da configuração da ação.

• Especificar filtro

  Adicione um filtro que inicia o pipeline em um filtro específico, como em nomes de ramificações para um push de código, e busca a confirmação exata. Isso também configura o pipeline para não iniciar automaticamente em nenhuma alteração.

  • Push

    • As combinações de filtro válidas são:

      • Tags do Git

        Incluir ou excluir

      • ramificações

        Incluir ou excluir

      • ramificações + caminhos de arquivo

        Incluir ou excluir

  • Solicitação pull

    • As combinações de filtro válidas são:

      • ramificações

        Incluir ou excluir

      • ramificações + caminhos de arquivo

        Incluir ou excluir

• Não detecte alterações

  Isso não adiciona um gatilho, e o pipeline não inicia automaticamente em nenhuma alteração.

A tabela a seguir fornece opções de filtro válidas para cada tipo de evento. A tabela também mostra quais configurações de gatilho são padronizadas como verdadeiras ou falsas para detecção automática de alterações na configuração da ação.

Configurações do gatilho	Tipo de evento	Opções de filtro	Detectar alterações
Adicionar um gatilho: sem filtro	nenhuma	nenhuma	true
Adicionar um gatilho: filtro no envio de código	evento push	Etiquetas Git, ramificações, caminhos de arquivo	false
Adicionar um gatilho: filtro para solicitações pull	solicitações pull	ramificações, caminhos de arquivo	false
Sem gatilho: não detectar	nenhuma	nenhuma	false

nota

Este tipo de gatilho usa detecção automatizada de alterações (como o tipo de gatilho Webhook). Os provedores de ações de origem que usam este tipo de gatilho são conexões configuradas para push de código por (Bitbucket Cloud, GitHub, GitHub Enterprise Server, GitLab.com e GitLab autogerenciado).

Para obter definições de campo e referência adicional para acionadores, consulte

Para conferir uma lista de definições de campo na estrutura JSON, consulte triggers.

Para filtragem, padrões de expressão regular no formato glob são compatíveis conforme detalhado em Trabalhar com padrões glob na sintaxe.

nota

Em certos casos, para pipelines com gatilhos filtrados por caminhos de arquivos, o pipeline pode não iniciar quando uma ramificação com um filtro de caminho de arquivo é criada pela primeira vez. Para obter mais informações, consulte Pipelines configurados com conexões que filtram gatilhos por caminhos de arquivos podem falhar ao iniciar durante a criação da ramificação..

Considerações sobre filtros de gatilho

As seguintes considerações se aplicam ao usar gatilhos.

• Você não pode adicionar mais de um acionador por ação de origem.

• Você pode adicionar vários tipos de filtro a um acionador. Para obter um exemplo, consulte 4: um acionador com dois tipos de filtro push com inclusões e exclusões conflitantes .

• Em gatilhos com filtros de ramificação e caminhos de arquivos, ao enviar a ramificação pela primeira vez, o pipeline não será acionado devido à indisponibilidade da lista de arquivos alterados na nova ramificação.

• A mesclagem de um pull request pode acionar duas execuções de pipeline, nos casos em que as configurações de acionador push (filtro de ramificações) e pull request (filtro de ramificações) se cruzam.

• Para um filtro que acione o pipeline em eventos pull request, para o tipo de evento pull request Fechado, o provedor de repositório de terceiros da conexão pode ter um status à parte para um evento de mesclagem. Por exemplo, no Bitbucket, o evento Git de uma mesclagem não é um evento de encerramento pull request. No entanto, no GitHub, a mesclagem de uma pull request é um evento de encerramento. Para obter mais informações, consulte Eventos pull request para acionadores por provedor.

Eventos pull request para acionadores por provedor

A tabela a seguir apresenta um resumo dos eventos do Git, como o encerramento de pull request, que resultem em tipos de evento pull request por provedor.

	Provedor de repositório para a conexão
Evento PR para acionador	Bitbucket	GitHub	GHES	GitLab
Abrir: esta opção aciona o pipeline quando uma pull request é criada para o caminho de ramificação/arquivo.	A criação de um pull request resulta em um evento do Git Aberto.	A criação de um pull request resulta em um evento do Git Aberto.	A criação de um pull request resulta em um evento do Git Aberto.	A criação de um pull request resulta em um evento do Git Aberto.
Atualizar: esta opção aciona o pipeline quando uma revisão pull request é publicada para o caminho de ramificação/arquivo.	A publicação de uma atualização resulta em um evento do Git Atualizado.	A publicação de uma atualização resulta em um evento do Git Atualizado.	A publicação de uma atualização resulta em um evento do Git Atualizado.	A publicação de uma atualização resulta em um evento do Git Atualizado.
Fechado: esta opção aciona o pipeline quando uma pull request é fechada para o caminho de ramificação/arquivo.	A mesclagem de uma pull request no Bitbucket resulta em um evento do Git Fechado. Importante: o fechamento manual de uma pull request no Bitbucket sem mesclar não resulta em um evento do Git Fechado.	A mesclagem ou o fechamento manual de uma pull request resulta em um evento do Git Fechado.	A mesclagem ou o fechamento manual de uma pull request resulta em um evento do Git Fechado.	A mesclagem ou o fechamento manual de uma pull request resulta em um evento do Git Fechado.

Exemplos de filtros de gatilho

Para uma configuração do Git com filtros para os tipos de eventos push e solicitação pull, os filtros especificados podem entrar em conflito entre si. Veja a seguir exemplos de combinações de filtros válidas para eventos push e solicitação pull. Um acionador pode conter vários tipos de filtro, como dois tipos de filtro push na configuração do acionador, e os tipos de filtro push e pull request usarão uma operação OR entre eles, o que significa que qualquer correspondência iniciará o pipeline. Da mesma forma, cada tipo de filtro pode incluir vários filtros, como filePaths e ramificações; esses filtros usarão um operador AND, o que significa que somente uma correspondência completa iniciará o pipeline. Cada tipo de filtro pode conter inclusões e exclusões, e elas usarão um operador AND entre elas, o que significa que somente uma correspondência completa iniciará o pipeline. Os nomes dentro da inclusão/exclusão, como nomes de ramificação, usam uma operação OR. Se houver um conflito, como entre dois filtros push, como quando um inclui a ramificação main e o outro a exclui, o padrão será excluir. A lista a seguir resume as operações de cada parte do objeto de configuração do Git.

Para obter uma lista de definições de campo na estrutura JSON e uma referência detalhada para inclusões e exclusões, consulte triggers.

exemplo 1: um tipo de filtro com filtros para ramificações e caminhos de arquivo (operação AND)

Para um único tipo de filtro, como pull request, você pode combinar filtros e esses filtros usarão um operador AND, o que significa que somente uma correspondência completa iniciará o pipeline. O exemplo a seguir mostra uma configuração do Git para um tipo de evento push com dois filtros diferentes (filePaths e branches). No exemplo a seguir, filePaths será usado com o operador E e com branches:

{
  "filePaths": {
    "includes": ["common/**/*.js"]
  },
  "branches": {
    "includes": ["feature/**"]
  }
}

Com a configuração do Git acima, este exemplo mostra um evento que iniciará a execução do pipeline porque o uso do operador E foi bem-sucedido. Em outras palavras, o caminho do arquivo common/app.js é incluído para o filtro, que inicia o pipeline como AND mesmo que a ramificação refs/heads/feature/triggers especificada não tenha tido impacto.

{
  "ref": "refs/heads/feature/triggers",
  ...
  "commits": [
    {
      ...
      "modified": [
        "common/app.js"
      ]
      ...
    }
  ]
}

O exemplo a seguir mostra um evento de um acionador com a configuração acima que não iniciará a execução do pipeline porque a ramificação consegue filtrar, mas o caminho do arquivo não.

{
   "ref": "refs/heads/feature/triggers",
  ...
  "commits": [
    {
      ...
      "modified": [
        "src/Main.java"
      ]
      ...
    }
  ]
}

exemplo 2: as inclusões e exclusões usam uma operação AND entre elas

Filtros de acionador, como ramificação em um único tipo de evento pull request, usam uma operação AND entre as inclusões e as exclusões. Isso permite que você configure vários gatilhos para iniciar a execução no mesmo pipeline. O exemplo a seguir mostra uma configuração de acionador com um único tipo de filtro (branches) no objeto de configuração de um evento push. As operações Includes e Excludes serão classificadas como AND, o que significa que, se uma ramificação corresponder a um padrão de exclusão (como feature-branch no exemplo), o pipeline não será acionado, a menos que uma inclusão também corresponda. Se o padrão de inclusão corresponder, como no caso da ramificação main, o pipeline será acionado.

Para o seguinte JSON de exemplo:

• O envio de uma confirmação para a ramificação main acionará o pipeline

• O envio de uma confirmação para a ramificação feature-branch não acionará o pipeline.

{
  "branches": {
      "Includes": [
          "main"
      ],
      "Excludes": [
          "feature-branch"
      ]
   }

exemplo 3: um acionador com tipos de filtro push e pull request (operação OR), filtros para caminhos e ramificações de arquivo (operação AND) e inclusões/exclusões (operação AND)

Os objetos de configuração do acionador, como um acionador que contém um tipo de evento push e um tipo de evento pull request, usam uma operação OR entre os dois tipos de evento. O exemplo a seguir mostra uma configuração de acionador com um tipo de evento push com a ramificação main incluída e um tipo de evento pull request com a mesma ramificação main excluída. Além disso, o tipo de evento push tem um caminho de arquivo LICENSE.txt excluído e um caminho de arquivo README.MD incluído. Para o segundo tipo de evento, uma pull request que seja Closed ou Created na ramificação feature-branch (incluída) inicia o pipeline, e o pipeline não inicia ao criar ou fechar uma pull request nas ramificações feature-branch-2 ou main (excluídas). As operações Excludes e Includes serão AND, com um conflito assumindo como padrão a exclusão. Por exemplo, para um evento de pull request na feature-branch ramificação (incluído na pull request) e a ramificação feature-branch é excluída para o tipo de evento push, logo, o padrão será excluir.

Para o exemplo a seguir,

• O envio de uma confirmação para a ramificação main (incluída) do caminho do arquivo README.MD (incluído) acionará o pipeline.

• Na ramificação feature-branch (excluída), o envio de uma confirmação não acionará o pipeline.

• Na ramificação incluída, a edição do caminho do arquivo README.MD (incluído) aciona o pipeline.

• Na ramificação incluída, a edição do caminho do arquivo LICENSE.TXT (excluído) não aciona o pipeline.

• Na ramificação feature-branch, o fechamento de uma solicitação pull para o caminho do arquivo README.MD (incluído para o evento push) não acionará o pipeline porque o tipo de evento push especifica a ramificação feature-branch como excluída e, assim, o conflito assume como padrão a exclusão.

A imagem a seguir mostra a configuração.

Este é o JSON exemplo da configuração.

"triggers": [
            {
                "providerType": "CodeStarSourceConnection",
                "gitConfiguration": {
                    "sourceActionName": "Source",
                    "push": [
                        {
                            "branches": {
                                "includes": [
                                    "main"
                                ],
                                "excludes": [
                                    "feature-branch",
                                    "feature-branch-2"
                                ]
                            },
                            "filePaths": {
                                "includes": [
                                    "README.md"
                                ],
                                "excludes": [
                                    "LICENSE.txt"
                                ]
                            }
                        }
                    ],
                    "pullRequest": [
                        {
                            "events": [
                                "CLOSED",
                                "OPEN"
                            ],
                            "branches": {
                                "includes": [
                                    "feature-branch"
                                ],
                                "excludes": [
                                    "feature-branch-2",
                                    "main"
                                ]
                            }
                        }
                    ]
                }
            }
        ]
    },

exemplo 4: um acionador com dois tipos de filtro push com inclusões e exclusões conflitantes

A imagem a seguir mostra um tipo de filtro push especificando o filtro na tag release-1 (incluída). Um segundo tipo de filtro por push é adicionado especificando a filtragem na ramificação main (incluída) e não iniciar um envio por push para as ramificações feature* (excluídas).

Para o seguinte exemplo:

• Pressionar uma liberação da tag release-1 (incluída para o primeiro filtro push) na feature-branch ramificação (excluída como feature* para o segundo filtro push) não acionará o pipeline porque os dois tipos de evento serão AND.

• O envio por push uma liberação da ramificação main (incluída para o segundo filtro Push) iniciará o pipeline.

O exemplo a seguir da página Editar mostra os dois tipos de filtros push e as configurações para inclusões e exclusões.

Este é o JSON exemplo da configuração.

"triggers": [
            {
                "providerType": "CodeStarSourceConnection",
                "gitConfiguration": {
                    "sourceActionName": "Source",
                    "push": [
                        {
                            "tags": {
                                "includes": [
                                    "release-1"
                                ]
                            }
                        },
                        {
                            "branches": {
                                "includes": [
                                    "main*"
                                ],
                                "excludes": [
                                    "feature*"
                                ]
                            }
                        }
                    ]
                }
            }
        ]
    },

exemplo 5: acionador configurado enquanto a configuração da ação padrão BranchName é usada para uma inicialização manual

O campo BranchName padrão de configuração da ação define uma única ramificação que será usada quando o pipeline for iniciado manualmente, e os gatilhos com filtros podem ser usados para qualquer ramificação ou ramificações especificadas por você.

Este é o JSON de exemplo para a configuração de ação que mostra o campo BranchName.

{
                "name": "Source",
                "actions": [
                    {
                        "name": "Source",
                        "actionTypeId": {
                            "category": "Source",
                            "owner": "AWS",
                            "provider": "CodeStarSourceConnection",
                            "version": "1"
                        },
                        "runOrder": 1,
                        "configuration": {
                            "BranchName": "main",
                            "ConnectionArn": "ARN",
                            "DetectChanges": "false",
                            "FullRepositoryId": "owner-name/my-bitbucket-repo",
                            "OutputArtifactFormat": "CODE_ZIP"
                        },
                        "outputArtifacts": [
                            {
                                "name": "SourceArtifact"
                            }
                        ],
                        "inputArtifacts": [],
                        "region": "us-west-2",
                        "namespace": "SourceVariables"
                    }
                ],

A saída da ação de exemplo a seguir mostra que a ramificação principal padrão foi usada quando o pipeline foi iniciado manualmente.

A saída da ação de exemplo a seguir mostra a pull request e a ramificação que foi usada para o acionador quando filtrado por pull request.