Referencia de variables - AWS CodePipeline
ConceptosCasos de uso de variables Configuración de variables Resolución de variablesReglas para variables Variables disponibles para acciones de canalización

Referencia de variables

Esta sección se incluye solo como referencia. Para obtener información sobre la creación de variables, consulte Trabajar con variables.

Las variables le permiten configurar las acciones de canalización con valores que se determinan en el momento de la ejecución de la canalización o de la ejecución de la acción.

Algunos proveedores de acciones producen un conjunto definido de variables. Puede elegir entre las claves de variables predeterminadas para ese proveedor de acciones, como el ID de confirmación.

importante

Al pasar parámetros del secreto, no introduzca el valor directamente. El valor se representa como texto no cifrado y, por lo tanto, se puede leer. Por razones de seguridad, no utilice texto sin formato con secretos. Se recomienda encarecidamente que utilice AWS Secrets Manager para almacenar secretos.

Para consultar ejemplos paso a paso del uso de variables:

Límites de variables

Para obtener información sobre los límites, consulte Cuotas en AWS CodePipeline.

nota

Cuando escriba la sintaxis de variable en los campos de configuración de acciones, no exceda el límite de 1000 caracteres de los campos de configuración. Cuando se supera este límite, se devuelve un error de validación.

Conceptos

En esta sección se enumeran los términos y conceptos clave relacionados con variables y espacios de nombres.

Variables

Las variables son pares clave-valor que se pueden utilizar para configurar dinámicamente acciones en la canalización. Actualmente hay tres maneras de hacer que estas variables estén disponibles:

  • Hay un conjunto de variables que están implícitamente disponibles al inicio de cada ejecución de canalización. Este conjunto incluye actualmente PipelineExecutionId, el ID de la ejecución de la canalización actual.

  • Las variables a nivel de canalización se definen cuando la canalización se crea y se resuelven en el tiempo de ejecución de la canalización.

    Las variables a nivel de canalización se especifican cuando se crea la canalización y se pueden proporcionar valores en el momento de la ejecución de la canalización.

  • Existen tipos de acción que producen conjuntos de variables cuando se ejecutan. Puede ver las variables producidas por una acción inspeccionando el campo outputVariables que forma parte de la API ListActionEjecutions . Para obtener una lista de los nombres de clave disponibles por proveedor de acciones, consulte Variables disponibles para acciones de canalización. Para ver qué variables produce cada tipo de acción, consulte CodePipeline Referencia de la estructura de acciones.

Para hacer referencia a estas variables en la configuración de acción, debe utilizar la sintaxis de referencia de variable con el espacio de nombres correcto.

Para ver un flujo de trabajo de variables de ejemplo, consulte Configuración de variables .

Espacios de nombres

Para garantizar que se pueda hacer referencia a las variables de forma única, deben asignarse a un espacio de nombres. Después de tener un conjunto de variables asignado a un espacio de nombres, se puede hacer referencia a las mismas en una configuración de acción mediante el espacio de nombres y la clave de variable con la siguiente sintaxis:

#{namespace.variable_key}

Hay tres tipos de espacios de nombres en los que se pueden asignar variables:

  • El espacio de nombres reservado codepipeline

    Este es el espacio de nombres asignado al conjunto de variables implícitas disponibles al inicio de cada ejecución de canalización. Este espacio de nombres es codepipeline. Ejemplo de referencia de variable:

    #{codepipeline.PipelineExecutionId}

  • El espacio de nombres de las variables a nivel de canalización

    Este es el espacio de nombres asignado a variables a nivel de canalización. El espacio de nombres de las variables a nivel de canalización es variables. Ejemplo de referencia de variable:

    #{variables.variable_name}

  • Espacio de nombres asignado a la acción

    Se trata de un espacio de nombres que se asigna a una acción. Todas las variables producidas por la acción caen bajo este espacio de nombres. Para que las variables producidas por una acción estén disponibles para su uso en una configuración de acción descendente, debe configurar la acción de producción con un espacio de nombres. Los espacios de nombres deben ser únicos en toda la definición de canalización y no pueden entrar en conflicto con ningún nombre de artefacto. Aquí hay una referencia de variable de ejemplo para una acción configurada con un espacio de nombres de SourceVariables.

    #{SourceVariables.VersionId}

Casos de uso de variables

A continuación, se incluyen algunos de los casos de uso más comunes de variables a nivel de canalización y le ayuda a determinar cómo puede usar las variables para sus necesidades específicas.

  • Las variables a nivel de canalización son para los clientes de CodePipeline que desean usar la misma canalización cada vez con pequeñas variaciones en las entradas de la configuración de la acción. Cualquier desarrollador que inicie una canalización añade el valor de la variable en la interfaz de usuario cuando se inicia la canalización. Con esta configuración, solo se transfieren parámetros para esa ejecución.

  • Con las variables a nivel de canalización, puede pasar entradas dinámicas a las acciones de la canalización. Puedes migrar sus canalizaciones parametrizadas a CodePipeline sin tener que mantener diferentes versiones de la misma canalización ni crear canalizaciones complejas.

  • Puede usar variables a nivel de canalización para transferir parámetros de entrada que le permitan reutilizar una canalización en cada ejecución, por ejemplo, cuando quiere especificar qué versión quiere implementar en un entorno de producción, de forma que no tenga que duplicar las canalizaciones.

  • Puede usar una única canalización para implementar recursos en varios entornos de creación e implementación. Por ejemplo, para una canalización con un repositorio de CodeCommit, la implementación desde una ramificación específica y un entorno de implementación de destino se puede realizar con los parámetros CodeBuild y CodeDeploy pasados a nivel de canalización.

nota

Para los orígenes de Amazon ECR, Amazon S3 o CodeCommit, también puede crear una anulación de origen mediante la entrada de transformación de entrada para utilizar revisionValue en EventBridge para el evento de canalización, donde revisionValue se deriva de la variable de evento de origen para la clave de objeto, confirmación o ID de imagen. Para obtener más información, consulte el paso opcional para la entrada de transformación de entrada, que se incluye en los procedimientos de acciones de origen de Amazon ECR y recursos de EventBridge, Conexión a acciones de origen de Amazon S3 con un origen habilitado para eventos o acciones de origen de CodeCommit y EventBridge.

Configuración de variables

Puede configurar las variables a nivel de canalización o a nivel de acción en la estructura de canalización.

Configuración de variables a nivel de canalización

Puede agregar una o varias variables a nivel de canalización. Puede hacer referencia a este valor en la configuración de las acciones de CodePipeline. Puede añadir los nombres de las variables, los valores predeterminados y las descripciones al crear la canalización. Las variables se resuelven en el momento de la ejecución.

nota

Si no se define un valor predeterminado para una variable a nivel de canalización, la variable se considera obligatoria. Debe especificar las anulaciones para todas las variables obligatorias al iniciar una canalización; de lo contrario, la ejecución de la canalización fallará y se producirá un error de validación.

Las variables se proporcionan a nivel de canalización mediante el atributo de variables de la estructura de canalización. En el siguiente ejemplo, la variable Variable1 tiene un valor de Value1.

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

Para ver un ejemplo en la estructura del JSON de la canalización, consulte Creación de una canalización, etapas y acciones.

Para ver un tutorial con una variable a nivel de canalización que se transfiere en el momento de la ejecución de la canalización, consulte Tutorial: Uso de variables a nivel de canalización.

Tenga en cuenta que no se admite el uso de variables a nivel de canalización en ningún tipo de acción de origen.

nota

Si el espacio de nombres variables ya se utiliza en algunas de las acciones del proceso, debe actualizar la definición de la acción y elegir otro espacio de nombres para la acción conflictiva.

Configuración de variables a nivel de acción

Una acción se configura para generar variables declarando un espacio de nombres para la acción. La acción ya debe ser uno de los proveedores de acciones que generan variables. De lo contrario, las variables disponibles son variables de nivel de canalización.

El espacio de nombres se declara mediante:

  • En la páginaEdit action (Editar acción) de la consola, introduciendo un espacio de nombres en Variable namespace (Espacio de nombres de variable).

  • Introduciendo un espacio de nombres en el campo de parámetros namespace en la estructura de canalización JSON.

En este ejemplo, agregue el parámetro namespace a la acción de origen CodeCommit con el nombre SourceVariables. Esto configura la acción para producir las variables disponibles para ese proveedor de acciones, 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
        }
    ]
},

A continuación, configure la acción descendente para utilizar las variables producidas por la acción anterior. Esto se hace del siguiente modo:

  • En la página Edit action (Editar acción) de la consola, introduciendo la sintaxis de variable (para la acción descendente) en los campos de configuración de acción.

  • Introduciendo la sintaxis de variable (para la acción descendente) en los campos de configuración de acciones en la estructura de canalización JSON

En este ejemplo, el campo de configuración de la acción de compilación muestra variables de entorno que se actualizan en la ejecución de la acción. El ejemplo especifica el espacio de nombres y la variable para el ID de ejecución con #{codepipeline.PipelineExecutionId} y el espacio de nombres y la variable para el ID de confirmación con #{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
        }
    ]
},

Resolución de variables

Cada vez que se ejecuta una acción como parte de una ejecución de canalización, las variables que produce están disponibles para su uso en cualquier acción que se garantice que ocurra después de la acción de producción. Para utilizar estas variables en una acción de consumo, puede agregarlas a la configuración de la acción de consumo utilizando la sintaxis mostrada en el ejemplo anterior. Antes de realizar una acción de consumo, CodePipeline resuelve todas las referencias de variables presentes en la configuración antes de iniciar la ejecución de la acción.

Ejemplo: variables para varias acciones

Reglas para variables

Las siguientes reglas le ayudan con la configuración de variables:

  • Especifique el espacio de nombres y la variable de una acción a través de una nueva propiedad de acción o editando una acción.

  • Cuando se utiliza el asistente de creación de canalizaciones, la consola genera un espacio de nombres para cada acción creada con el asistente.

  • Si no se especifica el espacio de nombres, no se puede hacer referencia a las variables producidas por esa acción en ninguna configuración de acción.

  • Para hacer referencia a variables producidas por una acción, la acción de referencia debe producirse después de la acción que produce las variables. Esto significa que está en una etapa posterior a la acción que produce las variable o en la misma etapa pero en un orden de ejecución más alto.

Variables disponibles para acciones de canalización

El proveedor de la acción determina qué variables puede generar la acción.

Para ver los procedimientos paso a paso para administrar variables, consulte Trabajar con variables.

Acciones con claves de variables definidas

A diferencia de un espacio de nombres que puede elegir, las siguientes acciones utilizan claves de variables que no se pueden editar. Por ejemplo, para el proveedor de acciones de Amazon S3, solo están disponibles las claves de variables ETag y VersionId.

Cada ejecución también tiene un conjunto de variables de canalización generadas por CodePipeline que contienen datos sobre la ejecución, como el ID de versión de la canalización. Estas variables las puede consumir cualquier acción de la canalización.

Variable de ID de ejecución de CodePipeline

Variable de ID de ejecución de CodePipeline
Proveedor Clave de variable Ejemplo de valor Ejemplo de sintaxis de variables
codepipeline PipelineExecutionId 8abc75f0-fbf8-4f4c-bfEXAMPLE #{codepipeline.PipelineExecutionId}

Variables de salida de acciones de Amazon ECR

Variables de Amazon ECR
Clave de variable Ejemplo de valor Ejemplo de sintaxis de variables
ImageDigest sha256:EXAMPLE1122334455 #{SourceVariables.ImageDigest}
ImageTag más reciente #{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}

Variables de salida de acciones de CloudFormation StackSets

Variables de CloudFormation StackSets
Clave de variable Ejemplo de valor Ejemplo de sintaxis de variables
OperationId 11111111-2bbb-111-2bbb-11111example #{DeployVariables.OperationId}
StackSetId my-stackset:1111aaaa-1111-2222-2bbb-11111example #{DeployVariables.StackSetId}

Variables de salida de acción de CodeCommit

Variables de CodeCommit
Clave de variable Ejemplo de valor Ejemplo de sintaxis de variables
AuthorDate 2019-10-29T03:32:21Z #{SourceVariables.AuthorDate}
BranchName desarrollo #{SourceVariables.BranchName}
CommitId

exampleb01f91b31

 #{SourceVariables.CommitId}
CommitMessage Se ha corregido un error (tamaño máximo de 100 KB) #{SourceVariables.CommitMessage}
CommitterDate 2019-10-29T03:32:21Z #{SourceVariables.CommitterDate}
RepositoryName MyCodeCommitRepo #{SourceVariables.RepositoryName}

Variables de salida de acción de CodestarSourceConnection

Variables de CodeStarSourceConnection (Bitbucket Cloud, GitHub, GitHub Enterprise Repository y Gitlab.com)
Clave de variable Ejemplo de valor Ejemplo de sintaxis de variables
AuthorDate 2019-10-29T03:32:21Z #{SourceVariables.AuthorDate}
BranchName desarrollo #{SourceVariables.BranchName}
CommitId

exampleb01f91b31

 #{SourceVariables.CommitId}
CommitMessage Se ha corregido un error (tamaño máximo de 100 KB) #{SourceVariables.CommitMessage}
ConnectionArn arn:aws:codestar-connections:region:id-cuenta:connection/id-conexión #{SourceVariables.ConnectionArn}
FullRepositoryName username/GitHubRepo #{SourceVariables.FullRepositoryName}

Variables de salida de acciones de GitHub (GitHub mediante la aplicación OAuth)

Variables de GitHub (acción de GitHub (mediante la aplicación OAuth))
Clave de variable Ejemplo de valor Ejemplo de sintaxis de variables
AuthorDate 2019-10-29T03:32:21Z #{SourceVariables.AuthorDate}
BranchName main #{SourceVariables.BranchName}
CommitId

exampleb01f91b31

 #{SourceVariables.CommitId}
CommitMessage

Se ha corregido un error (tamaño máximo de 100 KB)

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

Variables de salida de acciones de S3

Variables de S3
Clave de variable Ejemplo de valor Ejemplo de sintaxis de variables
ETag example28be1c3 #{SourceVariables.ETag}
VersionId exampleta_IUQCv #{SourceVariables.VersionId}

Acciones con claves de variables configuradas por el usuario

Para las acciones de CodeBuild, CloudFormation y de Lambda, el usuario configura las claves de variables.

Variables de salida de acciones de CloudFormation

CloudFormationVariables de
Clave de variable Ejemplo de sintaxis de variables

Para las acciones de CloudFormation, las variables se producen a partir de cualquier valor designado en la sección Outputs de una plantilla de pila. Tenga en cuenta que los únicos modos de acción de CloudFormation que generan salidas son los que dan como resultado la creación o actualización de una pila, como la creación de pila, las actualizaciones de pila y la ejecución de conjuntos de cambios. Los modos de acción correspondientes que generan variables son:

  • CREATE_UPDATE

  • CHANGE_SET_EXECUTE

  • CHANGE_SET_REPLACE

  • REPLACE_ON_FAILURE

Para obtener más información sobre estos modos de acción, consulte Referencia de la acción de implementación de CloudFormation. Para ver un tutorial que muestre cómo crear una canalización con una acción de implementación de CloudFormation en una canalización que utilice variables de salida de CloudFormation, consulte Tutorial: Crear una canalización que utilice variables a partir de acciones de implementación de AWS CloudFormation.		 #{DeployVariables.StackName}

Variables de salida de acciones de CodeBuild

Variables de CodeBuild
Clave de variable Ejemplo de sintaxis de variables

Para las acciones de CodeBuild, las variables se generan a partir de valores generados por las variables de entorno exportadas. Configure una variable de entorno de CodeBuild editando su acción de CodeBuild en CodePipeline o añadiendo la variable de entorno a la especificación de compilación.

Añada instrucciones a la especificación de compilación de CodeBuild para añadir la variable de entorno en la sección de variables exportadas. Consulte env/exported-variables en la Guía del usuario de AWS CodeBuild.

 
#{BuildVariables.EnvVar}

Variables de salida de acciones de Lambda

Variables de Lambda
Clave de variable Ejemplo de sintaxis de variables
La acción de Lambda producirá como variables todos los pares clave-valor que están incluidos en la sección outputVariables de la solicitud PutJobSuccessResult API.

Para ver un tutorial sobre una acción de Lambda que usa variables de una acción anterior (CodeCommit) y genera variables de salida, consulte Tutorial: Uso de variables con acciones de invocación de Lambda.

 #{TestVariables.testRunId}