Referencia de la especificación de compilación de CodeBuild - AWS CodeBuild

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Referencia de la especificación de compilación de CodeBuild

En este tema, se proporciona información de referencia importante sobre los archivos de especificación de compilación (buildspec). UNAbuildspeces un conjunto de comandos de compilación y opciones relacionadas, en formato YAML, que CodeBuild utiliza para ejecutar una compilación. Puede incluir una especificación de compilación como parte del código fuente o puede incluir una especificación de compilación cuando cree un proyecto de compilación. Para obtener información sobre cómo funciona una especificación de compilación, consulte Funcionamiento de CodeBuild.

Nombre de archivo y ubicación de almacenamiento de buildspec

Si incluye una especificación de compilación como parte del código fuente, de forma predeterminada, el archivo de especificación de compilación debe llamarse buildspec.yml y debe encontrarse en la raíz del directorio de código fuente.

Puede invalidar el nombre y la ubicación predeterminados del archivo de especificación de compilación. Por ejemplo, puede hacer lo siguiente:

  • Usar un archivo de especificación de compilación diferente para las distintas compilaciones del mismo repositorio, como buildspec_debug.yml y buildspec_release.yml.

  • Almacenar un archivo de especificación de compilación en otro lugar que no sea la raíz de su directorio de origen, como en config/buildspec.yml o en un bucket de S3. El bucket de S3 debe estar en la misma AWS región que el proyecto de compilación. Especifique el archivo buildspec utilizando su ARN (por ejemplo, arn:aws:s3:::my-codebuild-sample2/buildspec.yml).

Solo puede especificar una especificación de compilación para un proyecto de compilación, independientemente del nombre del archivo de especificación de compilación.

Para invalidar el nombre y/o la ubicación del archivo de especificación de compilación, realice alguna de las siguientes operaciones:

  • Ejecute el comando create-project o update-project de la AWS CLI, estableciendo el valor buildspec en la ruta del archivo de especificación de compilación alternativo relativa al valor de la variable de entorno integrada CODEBUILD_SRC_DIR. También puede hacer lo mismo con la operación create project en los SDK de AWS. Para obtener más información, consulte Creación de un proyecto de compilación o Cambiar la configuración de un proyecto de compilación.

  • Ejecute el comando start-build de la AWS CLI, estableciendo el valor buildspecOverride en la ruta del archivo de especificación de compilación alternativo relativa al valor de la variable de entorno integrada CODEBUILD_SRC_DIR. También puede hacer lo mismo con la operación start build en los SDK de AWS. Para obtener más información, consulte Ejecutar una compilación.

  • En una plantilla de AWS CloudFormation, establezca la propiedad BuildSpec de Source en un recurso de tipo AWS::CodeBuild::Project en la ruta del archivo de especificación de compilación alternativo relativa al valor de la variable de entorno integrada CODEBUILD_SRC_DIR. Para obtener más información, consulte la propiedad buildSpec enAWS CodeBuildfuente de proyectoen laAWS CloudFormationGuía del usuario de.

Sintaxis de buildspec

Los archivos de especificación de compilación deben expresarse en formato YAML.

Si un comando contiene un carácter, o una cadena de caracteres, que no es compatible con YAML, debe encerrar el comando entre comillas (""). El siguiente comando se incluye entre comillas porque no se permiten dos puntos (:) seguidos de un espacio en YAML. La comilla en el comando utiliza la secuencia de escape (\ ").

"export PACKAGE_NAME=$(cat package.json | grep name | head -1 | awk -F: '{ print $2 }' | sed 's/[\",]//g')"

La especificación de compilación tiene la siguiente sintaxis:

version: 0.2 run-as: Linux-user-name env: shell: shell-tag variables: key: "value" key: "value" parameter-store: key: "value" key: "value" exported-variables: - variable - variable secrets-manager: key: secret-id:json-key:version-stage:version-id git-credential-helper: no | yes proxy: upload-artifacts: no | yes logs: no | yes batch: fast-fail: false | true # build-list: # build-matrix: # build-graph: phases: install: run-as: Linux-user-name on-failure: ABORT | CONTINUE runtime-versions: runtime: version runtime: version commands: - command - command finally: - command - command pre_build: run-as: Linux-user-name on-failure: ABORT | CONTINUE commands: - command - command finally: - command - command build: run-as: Linux-user-name on-failure: ABORT | CONTINUE commands: - command - command finally: - command - command post_build: run-as: Linux-user-name on-failure: ABORT | CONTINUE commands: - command - command finally: - command - command reports: report-group-name-or-arn: files: - location - location base-directory: location discard-paths: no | yes file-format: report-format artifacts: files: - location - location name: artifact-name discard-paths: no | yes base-directory: location exclude-paths: excluded paths enable-symlinks: no | yes s3-prefix: prefix secondary-artifacts: artifactIdentifier: files: - location - location name: secondary-artifact-name discard-paths: no | yes base-directory: location artifactIdentifier: files: - location - location discard-paths: no | yes base-directory: location cache: paths: - path - path

La especificación de compilación contiene lo siguiente:

version

Mapeo obligatorio. Representa la versión de la especificación de compilación. Le recomendamos que utilice 0.2.

nota

Aunque la versión 0.1 sigue siendo compatible, le recomendamos que utilice la versión 0.2 siempre que sea posible. Para obtener más información, consulte Versiones de buildspec.

run-as

Secuencia opcional. Disponible solo para usuarios de Linux. Especifica un usuario de Linux que ejecuta comandos en este archivo buildspec.run-asotorga al usuario los permisos de lectura y ejecución especificados. Cuando se especifica run-as en la parte superior del archivo buildspec, se aplica globalmente a todos los comandos. Si no desea especificar un usuario para todos los comandos de archivo buildspec, puede especificar uno para comandos en una fase utilizando run-as en uno de los bloques phases. Si no se especifica run-as, todos los comandos se ejecutan como usuario raíz.

env

Secuencia opcional. Representa información para una o más variables de entorno personalizadas.

nota

Para proteger la información confidencial, lo siguiente está oculto en CodeBuild registros:

env/shell

Secuencia opcional. Especifica el shell compatible para los sistemas operativos Linux o Windows.

Para los sistemas operativos Linux, las etiquetas de shell compatibles son:

  • bash

  • /bin/sh

Para los sistemas operativos Windows, las etiquetas de shell compatibles son:

  • powershell.exe

  • cmd.exe

env/variables

Obligatorio si se especifica env y desea definir variables de entorno personalizadas en texto sin formato. Contiene una asignación de pares clave/valor escalares, donde cada asignación representa una única variable de entorno personalizada en texto sin formato. La clave es el nombre de la variable de entorno personalizada, mientras que el valor es el valor de la variable.

importante

Se desaconseja el almacenamiento de valores confidenciales, especialmente los identificadores de clave de acceso y las claves de acceso secretas de AWS en variables de entorno. Las variables de entorno se pueden mostrar en texto sin formato con herramientas como la CodeBuild Consola y elAWS CLI. Para valores confidenciales, le recomendamos utilizar el mapeo parameter-store o secrets-manager en su lugar, tal y como se describe más adelante en esta sección.

Las variables de entorno que defina reemplazan las variables de entorno existentes. Por ejemplo, si la imagen de Docker ya contiene una variable de entorno denominada MY_VAR con un valor de my_value y establece una variable de entorno denominada MY_VAR con un valor de other_value, my_value se reemplaza por other_value. Asimismo, si la imagen de Docker ya contiene una variable de entorno denominada PATH con un valor de /usr/local/sbin:/usr/local/bin y establece una variable de entorno denominada PATH con un valor de $PATH:/usr/share/ant/bin, /usr/local/sbin:/usr/local/bin se reemplaza por el valor literal $PATH:/usr/share/ant/bin.

No establezca variables de entorno con un nombre que empiece por CODEBUILD_. Este prefijo se reserva para uso interno de .

Si se define una variable de entorno con el mismo nombre en varios lugares, el valor se determina de la siguiente manera:

env/parameter-store

Obligatorio sienvy desea recuperar variables de entorno personalizadas almacenadas en el almacén de parámetros de Amazon EC2 Systems Manager. Contiene un mapeo declave/valuevalores escalares, en los que cada asignación representa una única variable de entorno personalizada almacenada en el almacén de parámetros de Amazon EC2 Systems Manager.clavees el nombre que se utiliza más adelante en los comandos de compilación para referirse a esta variable de entorno personalizada, yvaluees el nombre de la variable de entorno personalizada almacenada en el almacén de parámetros Amazon EC2 Systems Manager. Para almacenar valores sensibles, consulteAlmacén de parámetros de Administrador de sistemasyGuía del tutorial: Creación y prueba de parámetros String (consola)en laGuía del usuario de Amazon EC2 Systems Manager.

importante

Para permitir CodeBuild Para recuperar variables de entorno personalizadas almacenadas en el almacén de parámetros de Amazon EC2 Systems Manager, debe añadir elssm:GetParametersacción a tu CodeBuild rol de servicio de. Para obtener más información, consulte Crear un rol de servicio de CodeBuild.

Todas las variables de entorno que recupere del almacén de parámetros de Amazon EC2 Systems Manager reemplazan las variables de entorno existentes. Por ejemplo, si la imagen de Docker ya contiene una variable de entorno denominada MY_VAR con un valor de my_value y recupera una variable de entorno denominada MY_VAR con un valor de other_value, my_value se reemplaza por other_value. Asimismo, si la imagen de Docker ya contiene una variable de entorno denominada PATH con un valor de /usr/local/sbin:/usr/local/bin y recupera una variable de entorno denominada PATH con un valor de $PATH:/usr/share/ant/bin, /usr/local/sbin:/usr/local/bin se reemplaza por el valor literal $PATH:/usr/share/ant/bin.

No almacene variables de entorno con un nombre que empiece por CODEBUILD_. Este prefijo se reserva para uso interno de .

Si se define una variable de entorno con el mismo nombre en varios lugares, el valor se determina de la siguiente manera:

env/secrets-manager

Obligatorio si desea recuperar variables de entorno personalizadas almacenadas enAWS Secrets Manager. Especificar un Secrets Managerreference-keyutilizando el siguiente patrón:

<key>: <secret-id>:<json-key>:<version-stage>|<version-id>

<key>

(Obligatorio) El nombre de la variable de entorno local. Utilice este nombre para acceder a la variable durante la compilación.

<secret-id>

(Obligatorio) El nombre o nombre de recurso de Amazon (ARN) que sirve como identificador único del secreto. Para acceder a un secreto en su cuenta de AWS, simplemente especifique el nombre del secreto. Para acceder a un secreto en una cuenta de AWS diferente, especifique el ARN del secreto.

<json-key>

(Opcional) Especifica el nombre Secrets Manager clave del par clave-valor cuyo valor desea recuperar. Si no se especifica unajson-key, CodeBuild recupera todo el texto secreto.

<version-stage>

(Opcional) Especifica la versión del secreto que desea recuperar mediante la etiqueta de fase que se asocio a la versión. Las etiquetas de fase se utilizan para realizar un seguimiento de las diferentes versiones durante el proceso de rotación. Si usa version-stage, no especifique version-id. Si no especifica una fase o un ID de versión, el valor predeterminado será recuperar la versión con el valor de la fase de versión AWSCURRENT.

<version-id>

(Opcional) Especifica el identificador único de la versión del secreto que desea utilizar. Si especifica version-id, no especifique version-stage. Si no especifica una fase o un ID de versión, el valor predeterminado será recuperar la versión con el valor de la fase de versión AWSCURRENT.

En el siguiente ejemplo,TestSecretes el nombre del par clave-valor almacenado en Secrets Manager. La clave deTestSecretesMY_SECRET_VAR. Puede acceder a la variable durante la compilación mediante elLOCAL_SECRET_VARnombre.

env: secrets-manager: LOCAL_SECRET_VAR: "TestSecret:MY_SECRET_VAR"

Para obtener más información, consulte ¿Qué es AWS Secrets Manager? en la Guía del usuario de AWS Secrets Manager.

env/exported-variables

Mapeo opcional. Se utiliza para enumerar las variables de entorno que desea exportar. Especifique el nombre de cada variable en la que desee exportar en una línea independiente exported-variables. La variable que desea exportar debe estar disponible en su contenedor durante la compilación. La variable exportada puede ser una variable de entorno.

Las variables de entorno exportadas se utilizan junto conAWS CodePipelinepara exportar variables de entorno desde la fase de compilación actual a las fases posteriores de la canalización. Para obtener más información, consulteTrabajar con variablesen laAWS CodePipelineGuía del usuario de.

Durante una compilación, el valor de una variable está disponible a partir de la fase install. Se puede actualizar entre el inicio de la fase install y el final de la fase post_build. Una vez finalizada la fase post_build, el valor de las variables exportadas no puede cambiar.

nota

No se pueden exportar los siguientes elementos:

  • Secretos del almacén de parámetros de Amazon EC2 Systems Manager especificados en el proyecto de compilación.

  • Secrets Manager de secretos especificados en el proyecto de compilación

  • Variables de entorno que empiezan por AWS_.

env/git-credencial-ayudante

Mapeo opcional. Se utiliza para indicar si CodeBuild utiliza su auxiliar de credenciales de Git para proporcionar las credenciales de Git.yessi se utiliza. De lo contrario, seleccione no o sin especificar. Para obtener más información, consulte gitcredentials en el sitio web de Git.

nota

git-credential-helper no es compatible con compilaciones desencadenadas por un webhook para un repositorio de Git público.

proxy

Secuencia opcional. Se utiliza para representar configuraciones si ejecuta la compilación en un servidor de proxy explícito. Para obtener más información, consulte Ejecución de CodeBuild en un servidor proxy explícito.

proxy/upload-artifacts

Mapeo opcional. Establezca en yes si desea que la compilación de un servidor de proxy explícito cargue artefactos. El valor predeterminado es no.

proxy/logs

Mapeo opcional. Establecido enyespara que la compilación de un servidor proxy explícito cree CloudWatch registros. El valor predeterminado es no.

phases

Secuencia obligatoria. Representa los comandos CodeBuild ejecuta durante cada fase de la compilación.

nota

En buildspec versión 0.1, CodeBuild ejecuta cada comando en una instancia del shell predeterminado distinta en el entorno de compilación. Esto significa que cada comando se ejecuta con independencia de los demás. Por lo tanto, de forma predeterminada, no puede ejecutar un comando que se base en el estado de comandos anteriores (por ejemplo, cambiar directorios o configurar variables de entorno). Para solventar esta limitación, le recomendamos utilizar la versión 0.2, que soluciona este problema. Si debe utilizar la versión de especificación de compilación 0.1, se recomiendan los enfoques que se describen en Shells y comandos de los entornos de compilación.

phases/*/run-as

Secuencia opcional. Utilice una fase de compilación para especificar un usuario de Linux que ejecuta sus comandos. Si run-as también se especifica globalmente para todos los comandos en la parte superior del archivo buildspec, entonces el usuario de nivel de fase tiene prioridad. Por ejemplo, si run-as especifica globalmente User-1 y para la fase install solo una instrucción run-as especifica User-2, todos los comandos del archivo buildspec se ejecutan como User-1 excepto los comandos de la fase install, que se ejecutan como User-2.

phases/*/en caso de error

Secuencia opcional. Especifica la acción que se debe llevar a cabo si se produce un error durante la fase. Puede ser uno de los siguientes valores:

  • ABORT- Aborta la compilación.

  • CONTINUE- Continúe en la fase siguiente.

Si no se especifica esta propiedad, el proceso de error sigue las fases de transición, como se muestra enTransiciones de fases de compilación.

phases/*/finally

Bloque opcional. Comandos especificados en unfinallyblock se ejecutan después de los comandos delcommandsbloque. Los comandos de unfinallybloque se ejecuta incluso si un comando en lacommandsfalla el bloque. Por ejemplo, si elcommandsbloque contiene tres comandos y el primero falla, CodeBuild omite los dos comandos restantes y ejecuta cualquier comando delfinallybloque. La fase se lleva a cabo correctamente cuando todos los comandos de los bloques commands y finally se ejecutan sin problemas. Si un comando de una fase produce un error, la fase también producirá un error.

Los nombres de las fases de compilación permitidos son:

phases/install

Secuencia opcional. Representa los comandos, si hay alguno, que CodeBuild se ejecuta durante la instalación. Le recomendamos que utilice la fase install únicamente para instalar paquetes en el entorno de compilación. Por ejemplo, puede utilizar esta fase para instalar una plataforma de comprobación de código como Mocha o RSpec.

phases/install/runtime-versions

Secuencia opcional. Una versión del entorno ejecución es compatible con la imagen estándar de Ubuntu 2.0 o posterior y la imagen estándar de Amazon Linux 2 1.0 o posterior. Si se especifica, al menos debe haber un runtime incluido en esta sección. Especificar un motor de ejecución utilizando una versión específica, una versión principal seguida de.xpara especificar que CodeBuild utiliza esa versión principal con su última versión secundaria, olatestpara utilizar la versión principal y secundaria más reciente (por ejemplo,java: openjdk11,ruby: 2.6,nodejs: 12.x, o bienjava: latest). Puede especificar el runtime mediante un número o una variable de entorno. Por ejemplo, si utiliza la versión 2.0 de la imagen estándar de Amazon Linux 2, el fragmento siguiente especifica que está instalada la versión 8 de Java, la versión secundaria más reciente de la versión 3 de Python y una versión incluida en una variable de entorno de Ruby. Para obtener más información, consulte Imágenes de Docker proporcionadas por CodeBuild.

phases: install: runtime-versions: java: corretto8 python: 3.x ruby: "$MY_RUBY_VAR"

Puede especificar uno o más tiempos de ejecución en la sección runtime-versions del archivo de especificación de compilación. Si el tiempo de ejecución depende de otro tiempo de ejecución, también puede especificar el tiempo de ejecución dependiente en el archivo de especificación de compilación. Si no especifica ningún tiempo de ejecución en el archivo buildspec, CodeBuild elige los tiempos de ejecución predeterminados que están disponibles en la imagen que utiliza. Si especifica uno o varios tiempos de ejecución, CodeBuild utiliza solo esos tiempos de ejecución. Si no se especifica un motor de ejecución dependiente, CodeBuild intenta elegir el motor de ejecución dependiente.

Si dos runtimes especificados están en conflicto, la compilación produce un error. Por ejemplo, android: 29 y java: openjdk11 están en conflicto, por lo que si se especifican ambos, la compilación produce un error.

Para obtener más información acerca de los tiempos de ejecución disponibles, consulteTiempos de ejecución disponibles.

nota

Si especifica unruntime-versionsy utilizar una imagen que no sea Ubuntu Standard Image 2.0 o posterior, o la imagen estándar 1.0 de Amazon Linux 2 (AL2) o posterior, la compilación emite la advertencia»Skipping install of runtimes. Runtime version selection is not supported by this build image».

phases/install/commands

Secuencia opcional. Contiene una secuencia de valores escalares, en la que cada valor escalar representa un comando que CodeBuild se ejecuta durante la instalación. CodeBuild ejecuta cada comando, uno cada vez, en el orden indicado, de principio a fin.

phases/pre_build

Secuencia opcional. Representa los comandos, si hay alguno, que CodeBuild se ejecuta antes de la compilación. Por ejemplo, puede utilizar esta fase para iniciar sesión en Amazon ECR o puede instalar dependencias npm.

phases/pre_build/commands

Secuencia obligatoria si se especifica pre_build. Contiene una secuencia de valores escalares, en la que cada valor escalar representa un comando que CodeBuild se ejecuta antes de la compilación. CodeBuild ejecuta cada comando, uno cada vez, en el orden indicado, de principio a fin.

phases/build

Secuencia opcional. Representa los comandos, si hay alguno, que CodeBuild se ejecuta durante la compilación. Por ejemplo, puede utilizar esta fase para ejecutar Mocha, RSpec o sbt.

phases/build/commands

Obligatorio sibuildse especifica. Contiene una secuencia de valores escalares, en la que cada valor escalar representa un comando que CodeBuild se ejecuta durante la compilación. CodeBuild ejecuta cada comando, uno cada vez, en el orden indicado, de principio a fin.

phases/post_build

Secuencia opcional. Representa los comandos, si hay alguno, que CodeBuild se ejecuta después de la compilación. Por ejemplo, puede utilizar Maven para empaquetar los artefactos de la compilación en un archivo JAR o WAR, o puede insertar una imagen de Docker en Amazon ECR. A continuación, puede enviar una notificación de compilación a través de Amazon SNS.

phases/post_build/commands

Obligatorio sipost_buildse especifica. Contiene una secuencia de valores escalares, en la que cada valor escalar representa un comando que CodeBuild ejecuta tras la compilación. CodeBuild ejecuta cada comando, uno cada vez, en el orden indicado, de principio a fin.

informes

report-group-name-or-arn

Secuencia opcional. Especifica el grupo de informes al que se envían los informes. Un proyecto puede tener un máximo de cinco grupos de informes. Especifique el ARN de un grupo de informes existente o el nombre de un nuevo grupo de informes. Si especifica un nombre, CodeBuild crea un grupo de informes utilizando el nombre de proyecto y el nombre especificado en el formato<project-name>-<report-group-name>. Para obtener más información, consulte Nomenclatura de grupos de informes.

reports/<grupo-informes>/files

Secuencia obligatoria. Representa las ubicaciones que contienen los datos sin procesar de los resultados de las pruebas generados por el informe. Contiene una secuencia de valores escalares, en la que cada valor escalar representa una ubicación independiente donde CodeBuild puede encontrar los archivos de prueba, en relación con la ubicación de la compilación original o, si se ha establecido, labase-directory. Las ubicaciones pueden ser las siguientes:

  • Un archivo único (por ejemplo, my-test-report-file.json).

  • Un único archivo de un subdirectorio (por ejemplo, my-subdirectory/my-test-report-file.json o my-parent-subdirectory/my-subdirectory/my-test-report-file.json).

  • '**/*' representa todos los archivos recursivamente.

  • my-subdirectory/* representa todos los archivos de un subdirectorio denominado my-subdirectory.

  • my-subdirectory/**/* representa todos los archivos recursivamente a partir de un subdirectorio denominado my-subdirectory.

reports/<grupo-informes>/file-format

Mapeo opcional. Representa el formato del archivo de informe. Si no se especifica, se utiliza JUNITXML. No distingue entre mayúsculas y minúsculas. Los valores posibles son los siguientes:

Informes de pruebas

CUCUMBERJSON

Cucumber JSON

JUNITXML

JUnit XML

NUNITXML

NUnit XML

NUNIT3XML

NUnit 3 XML

TESTNGXML

TestNG XML

VISUALSTUDIOTRX

Visual Studio TRX

Informes de cobertura de código

CLOVERXML

XML de trébol

COBERTURAXML

Cobertura XML

JACOCOXML

XML de JaCoCo

SIMPLECOV

SimpleCov JSON

nota

CodeBuild acepta informes de cobertura de código JSON generados porsimplecov, nosimplecov-json.

reports/<grupo-informes>/base-directory

Mapeo opcional. Representa uno o varios directorios de nivel superior, en relación con la ubicación de la compilación original, que CodeBuild utiliza para determinar dónde se encuentran los archivos de prueba sin procesar.

reports/<grupo-informes>/discard-paths

Opcional. Especifica si los directorios del archivo de informes se aplanan en la salida. Si esto no se especifica o contiene no, los archivos de informes se generan con su estructura de directorios intacta. Si esto contiene yes, todos los archivos de prueba se colocan en el mismo directorio de salida. Por ejemplo, si una ruta a un resultado de prueba es com/myapp/mytests/TestResult.xml, especificar yes colocará este archivo en /TestResult.xml.

Artefactos de

Secuencia opcional. Representa información sobre dónde CodeBuild puede encontrar el resultado de la compilación y cómo CodeBuild lo prepara para cargarlo en el bucket de salida S3. Esta secuencia no es necesaria si, por ejemplo, va a crear e insertar una imagen de Docker en Amazon ECR, o si va a ejecutar pruebas unitarias en el código fuente pero no va a compilarlas.

nota

Los metadatos de Amazon S3 tienen un CodeBuild encabezado denominadox-amz-meta-codebuild-buildarnque contiene elbuildArndel CodeBuild compilación que publica artefactos en Amazon S3. LabuildArnse añade para permitir el seguimiento del origen de las notificaciones y para hacer referencia a partir de qué compilación se genera el artefacto.

artifacts/files

Secuencia obligatoria. Representa las ubicaciones que contienen los artefactos de salida de la compilación en el entorno de compilación. Contiene una secuencia de valores escalares, en la que cada valor escalar representa una ubicación independiente donde CodeBuild puede encontrar artefactos de salida de la compilación en relación con la ubicación de la compilación original o, si se ha definido, el directorio base. Las ubicaciones pueden ser las siguientes:

  • Un archivo único (por ejemplo, my-file.jar).

  • Un único archivo de un subdirectorio (por ejemplo, my-subdirectory/my-file.jar o my-parent-subdirectory/my-subdirectory/my-file.jar).

  • '**/*' representa todos los archivos recursivamente.

  • my-subdirectory/* representa todos los archivos de un subdirectorio denominado my-subdirectory.

  • my-subdirectory/**/* representa todos los archivos recursivamente a partir de un subdirectorio denominado my-subdirectory.

Cuando especifica ubicaciones de artefactos de salida de compilación, CodeBuild puede encontrar la ubicación de la compilación original en el entorno de compilación. No tiene que anexar las ubicaciones de los artefactos de salida de la compilación a la ruta de acceso de la ubicación de la compilación original ni especificar ./ o similar. Si desea conocer la ruta a esta ubicación, puede ejecutar un comando como echo $CODEBUILD_SRC_DIR durante una compilación. La ubicación de cada entorno de compilación puede ser ligeramente diferente.

artifacts/name

Nombre opcional. Especifica un nombre para su artefacto de compilación. Este nombre se utiliza cuando se cumple alguna de las condiciones siguientes.

  • Utilizas el CodeBuild API para crear tus compilaciones y eloverrideArtifactNamela bandera está establecida en elProjectArtifactsobjeto cuando se actualiza un proyecto, se crea un proyecto o se inicia una compilación.

  • Utilizas el CodeBuild consola de para crear sus compilaciones, se especifica un nombre en el archivo buildspec y se seleccionaHabilitación de versiones semánticasal crear o actualizar un proyecto. Para obtener más información, consulte Creación de un proyecto de compilación (consola).

Puede especificar un nombre en el archivo de especificación de compilación que se calcula en el momento de la compilación. El nombre especificado en un archivo de especificación utiliza el lenguaje de comandos Shell. Por ejemplo, puede adjuntar una fecha y una hora al nombre del artefacto para que siempre sea único. Los nombres de artefactos únicos impiden que los artefactos se sobrescriban. Para obtener más información, consulte Lenguaje de comandos Shell.

  • Este es un ejemplo de una nombre de artefacto asociado con la fecha de creación del artefacto.

    version: 0.2 phases: build: commands: - rspec HelloWorld_spec.rb artifacts: files: - '**/*' name: myname-$(date +%Y-%m-%d)
  • Este es un ejemplo de un nombre de artefacto que utiliza un CodeBuild variable de entorno. Para obtener más información, consulte Variables de entorno en los entornos de compilación.

    version: 0.2 phases: build: commands: - rspec HelloWorld_spec.rb artifacts: files: - '**/*' name: myname-$AWS_REGION
  • Este es un ejemplo de un nombre de artefacto que utiliza un CodeBuild variable de entorno con la fecha de creación del artefacto adjunta.

    version: 0.2 phases: build: commands: - rspec HelloWorld_spec.rb artifacts: files: - '**/*' name: $AWS_REGION-$(date +%Y-%m-%d)

Puede agregar información de ruta al nombre para que los artefactos con nombre se coloquen en directorios según la ruta del nombre. En este ejemplo, los artefactos de compilación se colocan en la salida debuilds/<build number>/my-artifacts.

version: 0.2 phases: build: commands: - rspec HelloWorld_spec.rb artifacts: files: - '**/*' name: builds/$CODEBUILD_BUILD_NUMBER/my-artifacts
artifacts/discard-paths

Opcional. Especifica si los directorios de artefactos de compilación se aplanan en la salida. Si esto no se especifica o contiene no, los artefactos de compilación se generan con su estructura de directorios intacta. Si esto contiene yes, todos los artefactos de compilación se colocan en el mismo directorio de salida. Por ejemplo, si una ruta a un archivo en el artefacto de salida de compilación es com/mycompany/app/HelloWorld.java, especificar yes colocará este archivo en /HelloWorld.java.

artifacts/base-directory

Mapeo opcional. Representa uno o varios directorios de nivel superior, en relación con la ubicación de la compilación original, que CodeBuild utiliza para determinar qué archivos y subdirectorios debe incluir en el artefacto de salida de la compilación. Los valores válidos son:

  • Un único directorio de nivel superior (por ejemplo, my-directory).

  • 'my-directory*' representa todos los directorios de nivel superior con nombres que empiezan por my-directory.

Los directorios de nivel superior coincidentes no se incluyen en el artefacto de salida de la compilación, solo sus archivos y subdirectorios.

Puede utilizar files y discard-paths para restringir aún más los archivos y subdirectorios que se incluyen. Por ejemplo, para la siguiente estructura de directorios:

. ├── my-build-1 │ └── my-file-1.txt └── my-build-2 ├── my-file-2.txt └── my-subdirectory └── my-file-3.txt

Y para la siguiente secuencia artifacts:

artifacts: files: - '*/my-file-3.txt' base-directory: my-build-2

Se incluiría el siguiente subdirectorio y archivo en el artefacto de salida de la compilación:

. └── my-subdirectory └── my-file-3.txt

Sin embargo, para la siguiente secuencia artifacts:

artifacts: files: - '**/*' base-directory: 'my-build*' discard-paths: yes

Se incluirían los siguientes archivos en el artefacto de salida de la compilación:

. ├── my-file-1.txt ├── my-file-2.txt └── my-file-3.txt
artifactos/rutas de exclusión

Mapeo opcional. Representa uno o varios trazados, en relación conbase-directory, que CodeBuild excluirá de los artefactos de compilación.

artifactos/habilitar enlaces simbólicos

Opcional. Si el tipo de salida esZIP, especifica si los vínculos simbólicos internos se conservan en el archivo ZIP. Si contieneyes, todos los enlaces simbólicos internos del origen se conservarán en el archivo ZIP de artefactos.

artifactos/prefijo s3

Opcional. Especifica un prefijo utilizado cuando los artefactos se envían a un bucket de Amazon S3 y el tipo de espacio de nombres esBUILD_ID. Cuando se utiliza, la ruta de salida en el bucket es<s3-prefix>/<build-id>/<name>.zip.

artifacts/secondary-artifacts

Secuencia opcional. Representa una o varias definiciones de artefacto como mapeo entre un identificador de artefacto y una definición de este. Cada uno de los identificadores de artefacto de este bloque debe coincidir con un artefacto definido en el atributo secondaryArtifacts del proyecto. Todas las definiciones tienen la misma sintaxis que el bloque artifacts anterior.

nota

Laartifacts/filesla secuencia siempre es necesaria, incluso cuando solo haya artefactos secundarios definidos.

Por ejemplo, si el proyecto tiene la estructura siguiente:

{ "name": "sample-project", "secondaryArtifacts": [ { "type": "S3", "location": "output-bucket1", "artifactIdentifier": "artifact1", "name": "secondary-artifact-name-1" }, { "type": "S3", "location": "output-bucket2", "artifactIdentifier": "artifact2", "name": "secondary-artifact-name-2" } ] }

El archivo buildspec tiene este aspecto:

version: 0.2 phases: build: commands: - echo Building... artifacts: files: - '**/*' secondary-artifacts: artifact1: files: - directory/file1 name: secondary-artifact-name-1 artifact2: files: - directory/file2 name: secondary-artifact-name-2

caché

Secuencia opcional. Representa información sobre dónde CodeBuild puede preparar los archivos para cargar la memoria caché en un bucket de memoria caché de S3. Esta secuencia no es necesaria si el tipo de caché del proyecto es No Cache.

cache/paths

Secuencia obligatoria. Representa las ubicaciones de la caché. Contiene una secuencia de valores escalares, en la que cada valor escalar representa una ubicación independiente donde CodeBuild puede encontrar artefactos de salida de la compilación en relación con la ubicación de la compilación original o, si se ha definido, el directorio base. Las ubicaciones pueden ser las siguientes:

  • Un archivo único (por ejemplo, my-file.jar).

  • Un único archivo de un subdirectorio (por ejemplo, my-subdirectory/my-file.jar o my-parent-subdirectory/my-subdirectory/my-file.jar).

  • '**/*' representa todos los archivos recursivamente.

  • my-subdirectory/* representa todos los archivos de un subdirectorio denominado my-subdirectory.

  • my-subdirectory/**/* representa todos los archivos recursivamente a partir de un subdirectorio denominado my-subdirectory.

importante

Como una declaración de especificación de compilación debe ser una declaración YAML válida, los espacios de la declaración son importantes. Si el número de espacios en la declaración de la especificación de compilación no es válido, es posible que las compilaciones produzcan un error inmediatamente. Puede utilizar un validador YAML para comprobar si sus declaraciones de especificación de compilación son declaraciones YAML válidas.

Si utiliza la AWS CLI o los SDK de AWS para declarar una especificación de compilación cuando crea o actualiza un proyecto de compilación, la especificación de compilación debe ser una cadena única expresada en formato YAML, junto con los espacios en blanco y los caracteres de escape de nueva línea necesarios. Encontrará un ejemplo en la siguiente sección.

Si utiliza el CodeBuild oAWS CodePipelineconsolas en lugar de un archivo buildspec.yml, puede insertar comandos para labuildfase solamente. En lugar de utilizar la sintaxis anterior, incluirá en una sola línea todos los comandos que desea ejecutar durante la fase de compilación. En caso de que haya varios comandos, separe cada comando con && (por ejemplo, mvn test && mvn package).

Puede utilizar el CodeBuild o CodePipeline Consolas en lugar de un archivo buildspec.yml para especificar las ubicaciones de los artefactos de salida de la compilación en el entorno de compilación. En lugar de utilizar la sintaxis anterior, incluirá en una sola línea todas las ubicaciones. Si hay varias ubicaciones, separe cada una de las ubicaciones con una coma (por ejemplo, buildspec.yml, target/my-app.jar).

Ejemplo de un archivo buildspec

A continuación se muestra un ejemplo de un archivo buildspec.yml.

version: 0.2 env: variables: JAVA_HOME: "/usr/lib/jvm/java-8-openjdk-amd64" parameter-store: LOGIN_PASSWORD: /CodeBuild/dockerLoginPassword phases: install: commands: - echo Entered the install phase... - apt-get update -y - apt-get install -y maven finally: - echo This always runs even if the update or install command fails pre_build: commands: - echo Entered the pre_build phase... - docker login -u User -p $LOGIN_PASSWORD finally: - echo This always runs even if the login command fails build: commands: - echo Entered the build phase... - echo Build started on `date` - mvn install finally: - echo This always runs even if the install command fails post_build: commands: - echo Entered the post_build phase... - echo Build completed on `date` reports: arn:aws:codebuild:your-region:your-aws-account-id:report-group/report-group-name-1: files: - "**/*" base-directory: 'target/tests/reports' discard-paths: no reportGroupCucumberJson: files: - 'cucumber/target/cucumber-tests.xml' discard-paths: yes file-format: CUCUMBERJSON # default is JUNITXML artifacts: files: - target/messageUtil-1.0.jar discard-paths: yes secondary-artifacts: artifact1: files: - target/artifact-1.0.jar discard-paths: yes artifact2: files: - target/artifact-2.0.jar discard-paths: yes cache: paths: - '/root/.m2/**/*'

A continuación se muestra un ejemplo de la especificación de compilación anterior, expresada como una sola cadena, para su uso con la AWS CLI o los SDK de AWS.

"version: 0.2\n\nenv:\n variables:\n JAVA_HOME: \"/usr/lib/jvm/java-8-openjdk-amd64\\"\n parameter-store:\n LOGIN_PASSWORD: /CodeBuild/dockerLoginPassword\n phases:\n\n install:\n commands:\n - echo Entered the install phase...\n - apt-get update -y\n - apt-get install -y maven\n finally:\n - echo This always runs even if the update or install command fails \n pre_build:\n commands:\n - echo Entered the pre_build phase...\n - docker login -u User -p $LOGIN_PASSWORD\n finally:\n - echo This always runs even if the login command fails \n build:\n commands:\n - echo Entered the build phase...\n - echo Build started on `date`\n - mvn install\n finally:\n - echo This always runs even if the install command fails\n post_build:\n commands:\n - echo Entered the post_build phase...\n - echo Build completed on `date`\n\n reports:\n reportGroupJunitXml:\n files:\n - \"**/*\"\n base-directory: 'target/tests/reports'\n discard-paths: false\n reportGroupCucumberJson:\n files:\n - 'cucumber/target/cucumber-tests.xml'\n file-format: CUCUMBERJSON\n\nartifacts:\n files:\n - target/messageUtil-1.0.jar\n discard-paths: yes\n secondary-artifacts:\n artifact1:\n files:\n - target/messageUtil-1.0.jar\n discard-paths: yes\n artifact2:\n files:\n - target/messageUtil-1.0.jar\n discard-paths: yes\n cache:\n paths:\n - '/root/.m2/**/*'"

A continuación, se muestra un ejemplo de los comandos delbuildfase, para usar con el CodeBuild o CodePipeline consolas.

echo Build started on `date` && mvn install

En estos ejemplos:

  • Se establece una variable de entorno personalizada, en texto sin formato, con la clave JAVA_HOME y el valor /usr/lib/jvm/java-8-openjdk-amd64.

  • Variable de entorno personalizada denominadadockerLoginPasswordalmacenada en los comandos de compilación a un almacén de parámetros de Amazon EC2 Systems Manager se usa la claveLOGIN_PASSWORD.

  • No puede cambiar estos nombres de fases de compilación. Los comandos que se ejecutan en este ejemplo son:apt-get update -yyapt-get install -y maven(para instalar Apache Maven),mvn install(para compilar, probar y empaquetar el código fuente en un artefacto de salida de la compilación e instalar el artefacto de salida de la compilación en su repositorio interno),docker login(para iniciar sesión en Docker con la contraseña que corresponde al valor de la variable de entorno personalizada)dockerLoginPasswordse ha establecido en el almacén de parámetros Amazon EC2 Systems Manager) y variosechocommands. Laechoaquí se incluyen comandos para mostrar cómo CodeBuild ejecuta comandos y en el orden en que los ejecuta.

  • files representa los archivos que se cargan en la ubicación de salida de la compilación. En este ejemplo, CodeBuild carga el único archivomessageUtil-1.0.jar. El archivo messageUtil-1.0.jar se encuentra en el directorio relativo denominado target en el entorno de compilación. Como se ha especificado discard-paths: yes, messageUtil-1.0.jar se carga directamente (y no en un directorio target intermedio). El nombre de archivo messageUtil-1.0.jar y el nombre del directorio relativo target se basan en la forma en la que Apache Maven crea y almacena los artefactos de salida de la compilación solo para este ejemplo. En sus propios escenarios, estos nombres de archivos y directorios serán diferentes.

  • reports representa dos grupos de informes que generan informes durante la compilación:

    • arn:aws:codebuild:your-region:your-aws-account-id:report-group/report-group-name-1 especifica el ARN de un grupo de informes. Los resultados de la prueba generados por el marco de prueba están en el directorio target/tests/reports. El formato del archivo es JunitXml y la ruta no se elimina de los archivos que contienen los resultados de prueba.

    • reportGroupCucumberJson especifica un nuevo grupo de informes. Si el nombre del proyecto es my-project, se crea un grupo de informes con el nombre my-project-reportGroupCucumberJson cuando se ejecuta una compilación. Los resultados de prueba generados por el marco de pruebas están en cucumber/target/cucumber-tests.xml. El formato del archivo de prueba es CucumberJson y la ruta se elimina de los archivos que contienen los resultados de prueba.

Versiones de buildspec

En la siguiente tabla se muestran las versiones de especificaciones de compilación y los cambios entre versiones.

Versión Cambios
0.2
  • environment_variables ahora se llama env.

  • plaintext ahora se llama variables.

  • La propiedad type de artifacts ya no se utiliza.

  • En la versión 0.1, AWS CodeBuild ejecuta cada comando de compilación en una instancia distinta del shell predeterminado del entorno de compilación. En la versión 0.2, CodeBuild ejecuta todos los comandos de compilación en la misma instancia del shell predeterminado en el entorno de compilación.

0.1 Esta es la primera definición del formato de especificación de compilación.