Referência de variáveis - AWS CodePipeline
ConceitosCasos de uso de variáveis Configurar variáveis Resolução de variáveisRegras para variáveis Variáveis disponíveis para ações de pipeline

Referência de variáveis

Esta seção é apenas uma referência. Para obter informações sobre como criar variáveis, consulte Trabalhar com variáveis.

As variáveis permitem configurar as ações de pipeline com valores determinados no momento da execução do pipeline ou da ação.

Alguns provedores de ação produzem um conjunto definido de variáveis. Escolha entre chaves de variáveis padrão para esse provedor de ação, como ID de confirmação.

Importante

Ao transmitir parâmetros secretos, não insira o valor diretamente. O valor é renderizado como texto sem formatação e, portanto, é legível. Por motivos de segurança, não use texto sem formatação com segredos. É altamente recomendável que você use o AWS Secrets Manager para armazenar os segredos.

Para ver exemplos passo a passo do uso de variáveis:

Limites de variáveis

Para obter informações sobre limites, consulte Cotas no AWS CodePipeline..

nota

Ao inserir a sintaxe da variável nos campos de configuração da ação, não ultrapasse o limite de mil caracteres dos campos de configuração. Um erro de validação será retornado quando esse limite for excedido.

Conceitos

Esta seção lista os principais termos e conceitos relacionados a variáveis e namespaces.

Variáveis

As variáveis são pares chave-valor que podem ser usados para configurar dinamicamente ações em seu pipeline. No momento, existem três maneiras de disponibilizar essas variáveis:

  • Há um conjunto de variáveis que estão implicitamente disponíveis no início de cada execução do pipeline. Atualmente, esse conjunto inclui PipelineExecutionId, o ID da execução atual do pipeline.

  • As variáveis em nível de pipeline são definidas quando o pipeline é criado e resolvido no runtime do pipeline.

    Você deve especificar variáveis em nível do pipeline quando o pipeline é criado e pode fornecer valores no momento da execução do pipeline.

  • Existem tipos de ação que produzem conjuntos de variáveis quando são executados. Você pode ver as variáveis produzidas por uma ação inspecionando o campo outputVariables que faz parte da API ListActionExecutions. Para obter uma lista de nomes de chaves disponíveis por provedor de ação, consulte Variáveis disponíveis para ações de pipeline. Para ver quais variáveis cada tipo de ação produz, consulte o Referência da estrutura da ação do CodePipeline.

Para fazer referência a essas variáveis na configuração da ação, você deve usar a sintaxe de referência de variável com o namespace correto.

Para obter um fluxo de trabalho variável de exemplo, consulte Configurar variáveis .

Namespaces

Para garantir que as variáveis possam ser referenciadas exclusivamente, elas devem ser atribuídas a um namespace. Depois de um conjunto de variáveis serem atribuídas a um namespace, elas podem ser referenciadas em uma configuração de ação usando o namespace e a chave de variável com a seguinte sintaxe:

#{namespace.variable_key}

Existem três tipos de namespaces sob os quais as variáveis podem ser atribuídas:

  • O namespace reservado do codepipeline

    Esse é o namespace atribuído ao conjunto de variáveis implícitas disponíveis no início de cada execução do pipeline. Esse namespace é o codepipeline. Exemplo de referência de variável:

    #{codepipeline.PipelineExecutionId}

  • O namespace das variáveis no nível do pipeline

    Esse é o namespace atribuído às variáveis no nível do pipeline. O namespace de todas as variáveis em nível de pipeline é variables. Exemplo de referência de variável:

    #{variables.variable_name}

  • Namespace atribuído à ação

    Esse é um namespace que você atribui a uma ação. Todas as variáveis produzidas pela ação se enquadram nesse namespace. Para tornar as variáveis produzidas por uma ação disponíveis para uso em uma configuração de ação downstream, você deve configurar a ação de produção com um namespace. Os namespaces devem ser exclusivos na definição do pipeline e não podem entrar em conflito com nenhum nome de artefato. Veja uma referência variável de exemplo para uma ação configurada com um namespace de SourceVariables.

    #{SourceVariables.VersionId}

Casos de uso de variáveis

Veja a seguir alguns dos casos de uso mais comuns de variáveis em nível de pipeline para ajudar você a determinar como usar as variáveis para necessidades específicas.

  • As variáveis em nível de pipeline se destinam aos clientes do CodePipeline que desejam usar sempre o mesmo pipeline com pequenas variações nas entradas da configuração da ação. Qualquer desenvolvedor que inicie um pipeline inclui o valor da variável na interface do usuário quando o pipeline é iniciado. Com essa configuração, você deve transmitir parâmetros somente para essa execução.

  • Com variáveis em nível de pipeline, é possível transmitir entradas dinâmicas para ações no pipeline. É possível migrar seus pipelines parametrizados para o CodePipeline sem precisar manter versões diferentes do mesmo pipeline nem criar pipelines complexos.

  • É possível usar variáveis em nível de pipeline para transmitir parâmetros de entrada que permitem reutilizar um pipeline a cada execução, como quando você deseja especificar qual versão deseja implantar em um ambiente de produção, para não precisar duplicar os pipelines.

  • É possível usar um único pipeline para implantar recursos em vários ambientes de criação e implantação. Por exemplo, para um pipeline com um repositório do CodeCommit, a implantação a partir de uma ramificação especificada e do ambiente de implantação de destino pode ser feita com os parâmetros do CodeBuild e do CodeDeploy transmitidos em nível de pipeline.

nota

Para origens do Amazon ECR, do Amazon S3 ou do CodeCommit, você também pode criar uma substituição de origem usando a entrada de transformação da entrada para usar revisionValue no EventBridge para o evento de pipeline, em que revisionValue deriva da variável do evento de origem da chave de objeto, confirmação ou ID da imagem. Para obter mais informações, consulte a etapa opcional da entrada da transformação de entrada incluída nos procedimentos em Ações de origem do Amazon ECR e recursos do EventBridge, Conexão a ações de origem do Amazon S3 com uma fonte habilitada para eventos ou Ações de origem do CodeCommit e EventBridge.

Configurar variáveis

É possível configurar variáveis em nível de pipeline ou em nível de ação na estrutura do pipeline.

Configurar variáveis em nível de pipeline

É possível adicionar uma ou mais variáveis em nível de pipeline. É possível fazer referência a esse valor na configuração das ações do CodePipeline. É possível adicionar os nomes das variáveis, os valores padrão e as descrições ao criar o pipeline. As variáveis são resolvidas no momento da execução.

nota

Se um valor padrão não for definido para uma variável em nível de pipeline, a variável será considerada necessária. É necessário especificar substituições para todas as variáveis necessárias ao iniciar um pipeline, caso contrário, a execução do pipeline falhará com um erro de validação.

Forneça variáveis no nível do pipeline usando o atributo variables na estrutura do pipeline. No exemplo a seguir, o valor da variável Variable1 é Value1.

       "variables": [
            {
                "name": "Variable1",
                "defaultValue": "Value1",
                "description": "description"
            }
        ]

Para ver um exemplo de estrutura JSON do pipeline, consulte Criar um pipeline, estágios e ações.

Para assistir a um tutorial com uma variável no nível do pipeline que é passada no momento da execução do pipeline, consulte. Tutorial: Usar variáveis no nível do pipeline

Observe que o uso de variáveis em nível de pipeline em qualquer tipo de ação de origem não é aceito.

nota

Se o namespace variables já estiver sendo usado em algumas ações no pipeline, você deverá atualizar a definição da ação e escolher outro namespace para a ação conflitante.

Configuração de variáveis no nível da ação

Configure uma ação para produzir variáveis declarando um namespace para a ação. A ação já deve ser um dos provedores da ação que gera variáveis. Caso contrário, as variáveis disponíveis serão variáveis em nível de pipeline.

Declare o namespace:

  • Na página Edit action (Editar ação) do console, digitando um namespace em Variable namespace (Namespace de variáveis).

  • Inserindo um namespace no campo do parâmetro namespace na estrutura do pipeline JSON.

Neste exemplo, você adiciona o parâmetro namespace à ação de origem CodeCommit com o nome SourceVariables. Isso configura a ação para produzir as variáveis disponíveis para esse provedor de ação, como CommitId. 

{
    "name": "Source",
    "actions": [
        {
            "outputArtifacts": [
                {
                    "name": "SourceArtifact"
                }
            ],
            "name": "Source",
            "namespace": "SourceVariables",
            "configuration": {
                "RepositoryName": "MyRepo",
                "BranchName": "mainline",
                "PollForSourceChanges": "false"
            },
            "inputArtifacts": [],
            "region": "us-west-2",
            "actionTypeId": {
                "provider": "CodeCommit",
                "category": "Source",
                "version": "1",
                "owner": "AWS"
            },
            "runOrder": 1
        }
    ]
},

Depois, configure a ação downstream para usar as variáveis produzidas pela ação anterior. Faça isso:

  • Na página Edit action (Editar ação) do console, inserindo a sintaxe de variável (para a ação downstream) nos campos de configuração da ação.

  • Entrando a sintaxe de variável (da ação downstream) nos campos de configuração da ação na estrutura do pipeline JSON

Neste exemplo, o campo de configuração da ação de compilação mostra variáveis de ambiente que são atualizadas na execução da ação. O exemplo especifica o namespace e a variável para o ID de execução com #{codepipeline.PipelineExecutionId} e o namespace e a variável do ID de confirmação com #{SourceVariables.CommitId}. 

{
    "name": "Build",
    "actions": [
        {
            "outputArtifacts": [
                {
                    "name": "BuildArtifact"
                }
            ],
            "name": "Build",
            "configuration": {
                "EnvironmentVariables": "[{\"name\":\"Release_ID\",\"value\":\"#{codepipeline.PipelineExecutionId}\",\"type\":\"PLAINTEXT\"},{\"name\":\"Commit_ID\",\"value\":\"#{SourceVariables.CommitId}\",\"type\":\"PLAINTEXT\"}]",
                "ProjectName": "env-var-test"
            },
            "inputArtifacts": [
                {
                    "name": "SourceArtifact"
                }
            ],
            "region": "us-west-2",
            "actionTypeId": {
                "provider": "CodeBuild",
                "category": "Build",
                "version": "1",
                "owner": "AWS"
            },
            "runOrder": 1
        }
    ]
},

Resolução de variáveis

Cada vez que uma ação é executada como parte de uma execução do pipeline, as variáveis que ela produz estão disponíveis para uso em qualquer ação que, garantidamente, ocorrerá após a ação de produção. Para usar essas variáveis em uma ação de consumo, você pode adicioná-las à configuração da ação de consumo usando a sintaxe mostrada no exemplo anterior. Antes de executar uma ação de consumo, o CodePipeline resolve todas as referências de variáveis presentes na configuração antes de iniciar a execução da ação.

Exemplo: variáveis para várias ações

Regras para variáveis

As regras a seguir ajudam você na configuração de variáveis:

  • Especifique o namespace e a variável para uma ação por meio de uma nova propriedade de ação ou editando uma ação.

  • Quando você usa o assistente de criação de pipeline, o console gera um namespace para cada ação criada com o assistente.

  • Se o namespace não for especificado, as variáveis produzidas por essa ação não poderão ser referenciadas em nenhuma configuração de ação.

  • Para referenciar variáveis produzidas por uma ação, a ação de referência deve ocorrer após a ação que produz as variáveis. Isso significa que ela está em um estágio posterior à ação que produz as variáveis, ou no mesmo estágio, mas em uma ordem de execução posterior.

Variáveis disponíveis para ações de pipeline

O provedor de ação determina quais variáveis podem ser geradas pela ação.

Para obter os procedimentos passo a passo para gerenciamento de variáveis, consulte Trabalhar com variáveis.

Ações com chaves variáveis definidas

Ao contrário de um namespace que você pode escolher, as ações a seguir usam chaves de variáveis não podem ser editadas. Por exemplo, para o provedor de ação do Amazon S3, apenas as chaves de variáveis ETag e VersionId estão disponíveis.

Cada execução também tem um conjunto de variáveis de pipeline geradas pelo CodePipeline que contêm dados sobre a execução, como o ID da versão do pipeline. Essas variáveis podem ser consumidas por qualquer ação no pipeline.

Variável de ID de execução do CodePipeline

Variável de ID de execução do CodePipeline
Provedor Chave de variável Valor de exemplo Exemplo de sintaxe de variável
codepipeline PipelineExecutionId 8abc75f0-fbf8-4f4c-bfEXAMPLE #{codepipeline.PipelineExecutionId}

Variáveis de saída de ação do Amazon ECR

Variáveis do Amazon ECR
Chave de variável Valor de exemplo Exemplo de sintaxe de variável
ImageDigest sha256:EXAMPLE1122334455 #{SourceVariables.ImageDigest}
ImageTag mais recente #{SourceVariables.ImageTag}
ImageURI 11111EXAMPLE.dkr.ecr.us-west-2.amazonaws.com/ecs-repo:latest #{SourceVariables.ImageURI}
RegistryId EXAMPLE12233 #{SourceVariables.RegistryId}
RepositoryName my-image-repo #{SourceVariables.RepositoryName}

Variáveis de saída da ação StackSets do CloudFormation

Variáveis StackSets do CloudFormation
Chave de variável Valor de exemplo Exemplo de sintaxe de variável
OperationId 11111111-2bbb-111-2bbb-11111example #{DeployVariables.OperationId}
StackSetId my-stackset:1111aaaa-1111-2222-2bbb-11111example #{DeployVariables.StackSetId}

Variáveis de saída da ação do CodeCommit

Variáveis do CodeCommit
Chave de variável Valor de exemplo Exemplo de sintaxe de variável
AuthorDate 2019-10-29T03:32:21Z #{SourceVariables.AuthorDate}
BranchName desenvolvimento #{SourceVariables.BranchName}
CommitId

exampleb01f91b31

 #{SourceVariables.CommitId}
CommitMessage Corrigido um erro (tamanho máximo de 100 KB) #{SourceVariables.CommitMessage}
CommitterDate 2019-10-29T03:32:21Z #{SourceVariables.CommitterDate}
RepositoryName myCodeCommitRepo #{SourceVariables.RepositoryName}

Variáveis de saída da ação CodeStarSourceConnection

Variáveis CodeStarSourceConnection (Bitbucket Cloud, GitHub, GitHub Enterprise Repository e GitLab.com)
Chave de variável Valor de exemplo Exemplo de sintaxe de variável
AuthorDate 2019-10-29T03:32:21Z #{SourceVariables.AuthorDate}
BranchName desenvolvimento #{SourceVariables.BranchName}
CommitId

exampleb01f91b31

 #{SourceVariables.CommitId}
CommitMessage Corrigido um erro (tamanho máximo de 100 KB) #{SourceVariables.CommitMessage}
ConnectionArn arn:aws:codestar-connections:region:account-id:connection/connection-id #{SourceVariables.ConnectionArn}
FullRepositoryName username/GitHubRepo #{SourceVariables.FullRepositoryName}

Variáveis de saída da ação do GitHub (ação do GitHub [por meio do aplicativo OAuth])

Variáveis do GitHub (ação do GitHub [por meio do aplicativo OAuth])
Chave de variável Valor de exemplo Exemplo de sintaxe de variável
AuthorDate 2019-10-29T03:32:21Z #{SourceVariables.AuthorDate}
BranchName main #{SourceVariables.BranchName}
CommitId

exampleb01f91b31

 #{SourceVariables.CommitId}
CommitMessage

Corrigido um erro (tamanho máximo de 100 KB)

 #{SourceVariables.CommitMessage}
CommitterDate 2019-10-29T03:32:21Z #{SourceVariables.CommitterDate}
CommitUrl #{SourceVariables.CommitUrl}
RepositoryName myGitHubRepo #{SourceVariables.RepositoryName}

Variáveis de saída da ação do S3

Variáveis do S3
Chave de variável Valor de exemplo Exemplo de sintaxe de variável
ETag example28be1c3 #{SourceVariables.ETag}
VersionId exampleta_IUQCv #{SourceVariables.VersionId}

Ações com chaves variáveis configuradas pelo usuário

Para ações do CodeBuild, do CloudFormation e do Lambda, as chaves de variáveis são configuradas pelo usuário.

Variáveis de saída da ação do CloudFormation

CloudFormationVariáveis do
Chave de variável Exemplo de sintaxe de variável

Para ações do CloudFormation, as variáveis são produzidas com quaisquer valores designados na seção Outputs de um modelo de pilha. Observe que os únicos modos de ação do CloudFormation que geram saídas são aqueles que resultam na criação ou na atualização de uma pilha, como criação e atualizações de pilha, bem como execução de conjunto de alterações. Os modos de ação correspondentes que geram variáveis são:

  • CREATE_UPDATE

  • CHANGE_SET_EXECUTE

  • CHANGE_SET_REPLACE

  • REPLACE_ON_FAILURE

Para obter mais informações sobre esses modos de ação, consulte CloudFormationReferência da ação de implantação do . Para ver um tutorial que mostra como criar um pipeline com uma ação de implantação do CloudFormation em um pipeline que usa variáveis de saída do CloudFormation, consulte Tutorial: Criar um pipeline que usa variáveis de ações de implantação do AWS CloudFormation.		 #{DeployVariables.StackName}

Variáveis de saída da ação do CodeBuild

Variáveis do CodeBuild
Chave de variável Exemplo de sintaxe de variável

Para ações do CodeBuild, as variáveis são produzidas a partir de valores gerados pelas variáveis de ambiente exportadas. Configure uma variável de ambiente do CodeBuild editando a ação do CodeBuild no CodePipeline ou adicionando a variável de ambiente à especificação de compilação.

Adicione instruções à especificação de compilação do CodeBuild para adicionar a variável de ambiente na seção de variáveis exportadas. Consulte env/exported-variables no Guia do usuário do AWS CodeBuild.

 
#{BuildVariables.EnvVar}

Variáveis de saída de ação do Lambda

Variáveis do Lambda
Chave de variável Exemplo de sintaxe de variável
A ação do Lambda produzirá como variáveis todos os pares de chave-valor incluídos na seção outputVariables da solicitação da API PutJobSuccessResult.

Para assistir a um tutorial com uma ação do Lambda que usa variáveis de uma ação upstream (CodeCommit) e gera variáveis de saída, consulte Tutorial: Usar variáveis com ações de invocação do Lambda.

 #{TestVariables.testRunId}