Nombre de archivo y ubicación de almacenamiento de buildspec Sintaxis de buildspec Ejemplo de un archivo buildspec Versiones de buildspec

Referencia de especificación de compilación para CodeBuild

En este tema, se proporciona información de referencia importante sobre los archivos de especificación de compilación (buildspec). Una especificación de compilación es un conjunto de comandos de compilación y configuraciones relacionadas, en formato YAML, que se 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 Cómo funciona CodeBuild.

Temas

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 tu 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:

Ejecuta el update-project comando AWS CLI create-project o y establece el buildspec valor de la ruta al archivo buildspec alternativo en relación con el valor de la variable de entorno integrada. CODEBUILD_SRC_DIR También puedes hacer lo mismo con la create project operación en los SDK. 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 AWS CLI start-build comando y establezca el buildspecOverride valor de la ruta al archivo buildspec alternativo en relación con el valor de la variable de entorno integrada. CODEBUILD_SRC_DIR También puedes hacer lo mismo con la start build operación en los SDK. AWS Para obtener más información, consulte Ejecutar una compilación.
En una AWS CloudFormation plantilla, establece la BuildSpec propiedad de Source en un recurso de tipo en la ruta AWS::CodeBuild::Project al archivo buildspec alternativo en relación con el valor de la variable de entorno integrada. CODEBUILD_SRC_DIR Para obtener más información, consulte la BuildSpec propiedad en la fuente del AWS CodeBuild proyecto en la Guía del AWS CloudFormation usuario.

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
    # steps:
  pre_build:
    run-as: Linux-user-name
    on-failure: ABORT | CONTINUE
    commands:
      - command
      - command
    finally:
      - command
      - command
    # steps:
  build:
    run-as: Linux-user-name
    on-failure: ABORT | CONTINUE
    commands:
      - command
      - command
    finally:
      - command
      - command
    # steps:
  post_build:
    run-as: Linux-user-name
    on-failure: ABORT | CONTINUE
    commands:
      - command
      - command
    finally:
      - command
      - command
    # steps:
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:

versión

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 de especificación de compilación. run-as concede al usuario especificado permisos de lectura y ejecución. 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, los CodeBuild registros ocultan lo siguiente:

AWS identificadores de claves de acceso. Para obtener más información, consulte Administración de claves de acceso para usuarios de IAM en la Guía del usuario de AWS Identity and Access Management .
Cadenas especificadas mediante el almacén de parámetros. Para obtener más información, consulte Almacén de parámetros de Systems Manager y Tutorial de la consola del almacén de parámetros de Systems Manager en la Guía del usuario de Amazon EC2 Systems Manager.
Cadenas especificadas mediante AWS Secrets Manager. Para obtener más información, consulte Administración de claves.

env/shell

Secuencia opcional. Especifica el intérprete de comandos compatible con los sistemas operativos Linux o Windows.

En los sistemas operativos Linux, las etiquetas de intérprete de comandos compatibles son:

bash
/bin/sh

En los sistemas operativos Windows, las etiquetas de intérprete de comandos 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 encarecidamente almacenar valores confidenciales en variables de entorno. Las variables de entorno se pueden mostrar en texto plano mediante herramientas como la CodeBuild consola y el AWS 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:

El valor de la llamada a la operación de inicio de la compilación tiene la máxima prioridad. Al crear una compilación, puede añadir o anular las variables de entorno. Para obtener más información, consulte Ejecutar una compilación en AWS CodeBuild.
El valor de la definición del proyecto de compilación es el siguiente en orden de prioridad. Al crear o editar un proyecto, puede añadir las variables de entorno en el nivel del proyecto. Para obtener más información, consulte Creación de un proyecto de compilación en AWS CodeBuild y Cambiar la configuración de un proyecto de compilación en AWS CodeBuild.
El valor en la declaración de especificación de compilación es el que menos prioridad tiene.

env/parameter-store

Obligatorio si se ha especificado env y desea recuperar variables de entorno personalizadas almacenadas en el almacén de parámetros de Amazon EC2 Systems Manager. Contiene una asignación de pares clave/valor escalares, donde cada asignación representa una única variable de entorno personalizada almacenada en el almacén de parámetros de Amazon EC2 Systems Manager. La clave es el nombre que utilizará más adelante en los comandos de compilación para hacer referencia a esta variable de entorno personalizada, y el valor es el nombre de la variable de entorno personalizada almacenada en el almacén de parámetros de Amazon EC2 Systems Manager. Para almacenar valores confidenciales, consulte Almacén de parámetros de Systems Manager y Tutorial: Crear y probar un parámetro de cadena de caracteres (consola) en la Guía del usuario de Amazon EC2 Systems Manager.

importante

CodeBuild Para permitir la recuperación de variables de entorno personalizadas almacenadas en el almacén de parámetros de Amazon EC2 Systems Manager, debe añadir ssm:GetParameters la acción a CodeBuild su rol de servicio. 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:

El valor de la llamada a la operación de inicio de la compilación tiene la máxima prioridad. Al crear una compilación, puede añadir o anular las variables de entorno. Para obtener más información, consulte Ejecutar una compilación en AWS CodeBuild.
El valor de la definición del proyecto de compilación es el siguiente en orden de prioridad. Al crear o editar un proyecto, puede añadir las variables de entorno en el nivel del proyecto. Para obtener más información, consulte Creación de un proyecto de compilación en AWS CodeBuild y Cambiar la configuración de un proyecto de compilación en AWS CodeBuild.
El valor en la declaración de especificación de compilación es el que menos prioridad tiene.

env/secrets-manager

Es obligatorio si desea recuperar las variables de entorno personalizadas almacenadas en AWS Secrets Manager. Especifique una reference-key de Secrets Manager utilizando el patrón siguiente:

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

<key>: (Obligatorio) Nombre de la variable de entorno local. Utilice este nombre para acceder a la variable durante la compilación.
<secret-id>: (Obligatorio) 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 , basta con especificar el nombre del secreto. Para acceder a un secreto de otra AWS cuenta, especifique el ARN secreto.
<json-key>: (Opcional) Especifica el nombre de la clave del par clave-valor de Secrets Manager cuyo valor desea recuperar. Si no especifica unjson-key, CodeBuild recupera todo el texto secreto.
<version-stage>: (Opcional) Especifica la versión del secreto que desea recuperar mediante la etiqueta de fase asociada 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 ejemplo siguiente, TestSecret es el nombre del par clave-valor almacenado en Secrets Manager. La clave de TestSecret es MY_SECRET_VAR. Se accede a la variable durante la compilación utilizando el nombre de LOCAL_SECRET_VAR.


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 con ellas AWS CodePipeline para exportar variables de entorno desde la fase de creación actual a las etapas siguientes de la fase de procesamiento. Para obtener más información, consulte Trabajar con variables en la Guía del usuario de AWS CodePipeline .

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.
Secretos de Secrets Manager especificados en el proyecto de compilación
Variables de entorno que empiezan por AWS_.

env/ git-credential-helper

Mapeo opcional. Se usa para indicar si CodeBuild usa su asistente de credenciales de Git para proporcionar las credenciales de Git. yessi se usa. 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. yesConfigúrelo para crear CloudWatch registros en un servidor proxy explícito. El valor predeterminado es no.

phases

Secuencia obligatoria. Representa los comandos que CodeBuild se ejecutan durante cada fase de la compilación.

nota

En la versión 0.1 de buildspec, CodeBuild ejecuta cada comando en una instancia independiente del shell predeterminado del 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 Intérpretes de comandos 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/*/on-failure

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

ABORT: anular la compilación.
CONTINUE: continuar con el paso siguiente.

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

phases/*/finally

Bloque opcional. Los comandos especificados en un bloque finally se ejecutan después de los del bloque commands. Los comandos de un bloque finally se aunque falle un comando del bloque commands. Por ejemplo, si el commands bloque contiene tres comandos y el primero falla, CodeBuild omite los dos comandos restantes y ejecuta todos los comandos del bloque. finally Se considera que la fase es satisfactoria cuando todos los comandos de los bloques commands y finally se ejecutan sin problemas. Si un comando de una fase falla, se considera que la fase falla.

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

phases/install

Secuencia opcional. Representa los comandos, si los hay, que CodeBuild se ejecutan 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 en tiempo de ejecución es compatible con la imagen estándar de Ubuntu 5.0 o una versión posterior y la imagen estándar de Amazon Linux 2 4.0 o una versión posterior. Si se especifica, al menos debe haber un entorno de tiempo de ejecución incluido en esta sección. Especifique un tiempo de ejecución mediante una versión específica, una versión principal seguida de una versión principal .x para especificar si CodeBuild utiliza esa versión principal con su versión secundaria más reciente o latest si utiliza la versión principal y secundaria más reciente (por ejemplo,ruby: 3.2,nodejs: 18.x, ojava: latest). Puede especificar el entorno de tiempo de ejecución mediante un número o una variable de entorno. Por ejemplo, si utiliza la imagen de Amazon Linux 2 estándar 4.0, lo siguiente especifica que la versión 17 de Java, la versión secundaria más reciente de python versión 3 y una versión contenida en una variable de entorno de Ruby están instaladas. 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 especificas ningún tiempo de ejecución en el archivo buildspec, CodeBuild selecciona los tiempos de ejecución predeterminados que estén disponibles en la imagen que utilices. Si especificas uno o más tiempos de ejecución, utiliza solo esos tiempos de ejecución. CodeBuild Si no se especifica un tiempo de ejecución dependiente, CodeBuild intentará elegir el tiempo de ejecución dependiente por usted.

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 sobre los entornos de tiempo de ejecución disponibles, consulte Tiempos de ejecución disponibles.

nota

Si se especifica una sección de runtime-versions y se utiliza una imagen distinta de Ubuntu Standard Image 2.0 o posterior, o la imagen estándar de Amazon Linux 2 (AL2) 1.0 o posterior, la compilación mostrará 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 escalares, donde cada escalar representa un único comando que CodeBuild se ejecuta durante la instalación. CodeBuild ejecuta cada comando, uno a la vez, en el orden indicado, de principio a fin.

phases/pre_build

Secuencia opcional. Representa los comandos, si los hay, que CodeBuild se ejecutan 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 escalares, donde cada escalar representa un único comando que CodeBuild se ejecuta antes de la compilación. CodeBuildejecuta cada comando, uno a la vez, en el orden indicado, de principio a fin.

phases/build

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

phases/build/commands: Es obligatorio si se ha especificado build. Contiene una secuencia de escalares, donde cada escalar representa un único comando que CodeBuild se ejecuta durante la compilación. CodeBuild ejecuta cada comando, uno a la vez, en el orden indicado, de principio a fin.

phases/post_build

Secuencia opcional. Representa los comandos, si los hay, que CodeBuild se ejecutan 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 remitir una imagen de Docker hacia Amazon ECR. A continuación, puede enviar una notificación de compilación a través de Amazon SNS.

phases/post_build/commands: Es obligatorio si se ha especificado post_build. Contiene una secuencia de escalares, donde cada escalar representa un único comando que CodeBuild se ejecuta después de la compilación. CodeBuild ejecuta cada comando, uno a la 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 con el nombre del proyecto y el nombre que especifique en el formato. <project-name>-<report-group-name> El nombre del grupo de informes también se puede establecer mediante una variable de entorno en la especificación de compilación, como. $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 escalares, en la que cada escalar representa una ubicación independiente donde se CodeBuild pueden encontrar los archivos de prueba, en relación con la ubicación de compilación original o, si está establecida, con la. base-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 ha especificado, se utiliza JUNITXML. Este valor 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: Clover XML
COBERTURAXML: Cobertura XML
JACOCOXML: JaCoCo XML
SIMPLECOV: SimpleCov JSON

nota
CodeBuild acepta los informes de cobertura de código JSON generados por simplecov, no por simplecov-json.

reports/<grupo-informes>/base-directory

Mapeo opcional. Representa uno o más directorios de nivel superior, en relación con la ubicación de compilación original, que se CodeBuild utilizan para determinar dónde encontrar 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

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

nota

Los metadatos de Amazon S3 tienen un nombre de CodeBuild encabezado x-amz-meta-codebuild-buildarn que contiene el nombre buildArn de la CodeBuild compilación que publica los artefactos en Amazon S3. Se añade buildArn para permitir el seguimiento de las notificaciones en la fuente y para hacer referencia a la compilación de donde procede 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.

Al especificar las ubicaciones de los artefactos de salida de la compilación, CodeBuild puede localizar la ubicación de construcció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.

Usas la CodeBuild API para crear tus compilaciones y el overrideArtifactName indicador se establece en el ProjectArtifacts objeto cuando se actualiza un proyecto, se crea un proyecto o se inicia una compilación.
Usas la CodeBuild consola para crear tus compilaciones, se especifica un nombre en el archivo buildspec y seleccionas Habilitar el control de versiones semántico al 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 usa una variable de entorno. CodeBuild 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 usa una variable de CodeBuild 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 añadir información sobre la ruta al nombre para que los artefactos nombrados se coloquen en directorios según la ruta que figure en el nombre. En este ejemplo, los artefactos de compilación se colocan en la salida dentro de builds/<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 más directorios de nivel superior, en relación con la ubicación de compilación original, que se CodeBuild utilizan para determinar qué archivos y subdirectorios 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

artifacts/exclude-paths

Mapeo opcional. Representa una o más rutas, relativas abase-directory, que CodeBuild se excluirán de los artefactos de construcción. El carácter asterisco (*) coincide con cero o varios caracteres de un componente de nombre sin superar límites de carpeta. Un asterisco doble (**) coincide con cero o más caracteres de un componente de nombre en todos los directorios.

A continuación, se muestran ejemplos de excude-path:

Para excluir un archivo de todos los directorios: "**/file-name/**/*"
Para excluir todas las carpetas de punto: "**/.*/**/*"
Para excluir todos los archivos de punto: "**/.*"

artifacts/enable-symlinks

Opcional. Si el tipo de salida es ZIP, esto especifica si los enlaces simbólicos internos se conservan en el archivo ZIP. Si esto contieneyes, todos los enlaces simbólicos internos de la fuente se conservarán en el archivo ZIP de artefactos.

artifacts/s3-prefix

Opcional. Especifica un prefijo que se utiliza cuando los artefactos se envían a un bucket de Amazon S3 y el tipo de espacio de nombres es BUILD_ID. Cuando se usa, la ruta de salida del 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

La secuencia de artifacts/files siempre es obligatoria, incluso si solo se han definido artefactos secundarios.

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

cache

Secuencia opcional. Representa información sobre dónde CodeBuild se pueden preparar los archivos para cargar la caché en un depósito de 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 escalares, cada uno de los cuales representa una ubicación independiente en la que se CodeBuild pueden encontrar los artefactos de salida de la compilación, en relación con la ubicación de compilación original o, si está establecida, con 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 utilizas el o los AWS CLI AWS SDK para declarar una especificación de construcción al crear o actualizar 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 utilizas las AWS CodePipeline consolas CodeBuild o en lugar del archivo buildspec.yml, solo puedes insertar comandos para la fase. build 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 usar las CodePipeline consolas CodeBuild o en lugar del 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/**/*'

Este es un ejemplo de la especificación de compilación anterior, expresada como una sola cadena, para usarla con el o los SDK. AWS CLI 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/**/*'"

Este es un ejemplo de los comandos de la build fase para usarlos con las consolas o. CodeBuild CodePipeline


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.
Se hace referencia a una variable de entorno llamada dockerLoginPassword y almacenada en el almacén de parámetros de Amazon EC2 Systems Manager en comandos posteriores en la compilación mediante la clave LOGIN_PASSWORD.
No puede cambiar estos nombres de fases de compilación. Los comandos que se ejecutan en este ejemplo son apt-get update -y y apt-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 y para 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 correspondiente al valor de la variable de entorno personalizada dockerLoginPassword definida en el almacén de parámetros de Amazon EC2 Systems Manager) y varios comandos echo. Los echo comandos se incluyen aquí para mostrar cómo CodeBuild se ejecutan los comandos y el orden en que se ejecutan.
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

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 independiente 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 del entorno de compilación.
0.1	Esta es la primera definición del formato de especificación de compilación.

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 independiente 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 del entorno de compilación.

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

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Planificación de una compilación

Referencia de especificaciones de compilación por lotes