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 una colección de comandos de compilación y opciones de configuración 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 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
ybuildspec_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
oupdate-project
de la AWS CLI, estableciendo el valorbuildspec
en la ruta del archivo de especificación de compilación alternativo relativa al valor de la variable de entorno integradaCODEBUILD_SRC_DIR
. También puede hacer lo mismo con la operacióncreate project
en los SDK de AWS. Para obtener más información, consulte Creación de un proyecto de compilación o Cambio de la configuración del proyecto de compilación. -
Ejecute el comando
start-build
de la AWS CLI, estableciendo el valorbuildspecOverride
en la ruta del archivo de especificación de compilación alternativo relativa al valor de la variable de entorno integradaCODEBUILD_SRC_DIR
. También puede hacer lo mismo con la operaciónstart build
en los SDK de AWS. Para obtener más información, consulte Ejecución de compilaciones de forma manual. -
En una plantilla de AWS CloudFormation, establezca la propiedad
BuildSpec
deSource
en un recurso de tipoAWS::CodeBuild::Project
en la ruta del archivo de especificación de compilación alternativo relativa al valor de la variable de entorno integradaCODEBUILD_SRC_DIR
. Para obtener más información, consulte la propiedad BuildSpec en la fuente del proyecto AWS CodeBuild en la Guía del usuario de AWS CloudFormation.
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:
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, lo siguiente está oculto en los registros de CodeBuild:
-
ID de clave de acceso de AWS. 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 paresclave
/valor
escalares, donde cada asignación representa una única variable de entorno personalizada en texto sin formato. Laclave
es el nombre de la variable de entorno personalizada, mientras que elvalor
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 sin formato con herramientas como la consola de CodeBuild y la AWS CLI. Para valores confidenciales, le recomendamos utilizar el mapeo
parameter-store
osecrets-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 demy_value
y establece una variable de entorno denominadaMY_VAR
con un valor deother_value
,my_value
se reemplaza porother_value
. Asimismo, si la imagen de Docker ya contiene una variable de entorno denominadaPATH
con un valor de/usr/local/sbin:/usr/local/bin
y establece una variable de entorno denominadaPATH
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 Ejecución de compilaciones de AWS CodeBuild de forma manual.
-
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 Cambio de la configuración del 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 paresclave
/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. Laclave
es el nombre que utilizará más adelante en los comandos de compilación para hacer referencia a esta variable de entorno personalizada, y elvalor
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
Para permitir que CodeBuld recupere variables de entorno personalizadas almacenadas en el almacén de parámetros de Amazon EC2 Systems Manager, es necesario añadir la acción
ssm:GetParameters
al rol de servicio de CodeBuild. Para obtener más información, consulte Cómo permitir que CodeBuild interactúe con otros servicios de AWS.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 demy_value
y recupera una variable de entorno denominadaMY_VAR
con un valor deother_value
,my_value
se reemplaza porother_value
. Asimismo, si la imagen de Docker ya contiene una variable de entorno denominadaPATH
con un valor de/usr/local/sbin:/usr/local/bin
y recupera una variable de entorno denominadaPATH
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 Ejecución de compilaciones de AWS CodeBuild de forma manual.
-
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 Cambio de la configuración del 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
-
Obligatorio si se desea recuperar 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 en una cuenta de AWS diferente, especifique el ARN del secreto.
<json-key>
-
(Opcional) Especifica el nombre de la clave del par clave-valor de Secrets Manager cuyo valor desea recuperar. Si no se especifica una
json-key
, CodeBuild recupera todo el texto del 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 especifiqueversion-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ónAWSCURRENT
. <version-id>
-
(Opcional) Especifica el identificador único de la versión del secreto que desea utilizar. Si especifica
version-id
, no especifiqueversion-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ónAWSCURRENT
.
En el ejemplo siguiente,
TestSecret
es el nombre del par clave-valor almacenado en Secrets Manager. La clave deTestSecret
esMY_SECRET_VAR
. Se accede a la variable durante la compilación utilizando el nombre deLOCAL_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 AWS CodePipeline para exportar variables de entorno desde la fase de creación actual a las etapas siguientes del 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 faseinstall
y el final de la fasepost_build
. Una vez finalizada la fasepost_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 utiliza para indicar si CodeBuild utiliza su ayudante de credenciales de Git para proporcionar las credenciales de Git.
yes
si se utiliza. De lo contrario, seleccioneno
o sin especificar. Para obtener más información, consulte gitcredentialsen 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 esno
. - proxy/logs
-
Mapeo opcional. Se establece en
yes
para que la compilación de un servidor de proxy explícito cree Registros de CloudWatch. El valor predeterminado esno
.
phases
Secuencia obligatoria. Representa los comandos que CodeBuild ejecuta durante cada fase de la compilación.
nota
En la versión de especificación de compilación 0.1, CodeBuild ejecuta cada comando en una instancia distinta del intérprete de comandos predeterminado 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 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, sirun-as
especifica globalmente User-1 y para la faseinstall
solo una instrucciónrun-as
especifica User-2, todos los comandos del archivo buildspec se ejecutan como User-1 excepto los comandos de la faseinstall
, 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 bloquecommands
. Los comandos de un bloquefinally
se aunque falle un comando del bloquecommands
. Por ejemplo, si el bloquecommands
contiene tres comandos y el primero produce un error, CodeBuild omite los dos comandos restantes y ejecuta los comandos del bloquefinally
. Se considera que la fase es satisfactoria cuando todos los comandos de los bloquescommands
yfinally
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 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 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 entorno de tiempo de ejecución utilizando una versión específica, una versión principal seguida de
.x
para indicar que CodeBuild utiliza esa versión principal con su última versión secundaria olatest
para indicar que se va a utilizar la versión principal y secundaria más recientes (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 se especifica ningún entorno de tiempo de ejecución en el archivo de especificación de compilación, CodebBuild elige los entornos de tiempo de ejecución predeterminados disponibles en la imagen que se utilice. Si se especifican uno o más entornos de tiempo de ejecución, CodeBuild utiliza solo estos. Si no se especifica un entorno de tiempo de ejecución dependiente, CodeBuild intenta elegir uno por su cuenta.Si dos runtimes especificados están en conflicto, la compilación produce un error. Por ejemplo,
android: 29
yjava: 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 valores escalares, en la que cada valor escalar representa un comando que CodeBuild 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 CodeBulild debe ejecutar 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 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 los hay, que CodeBuild ejecuta 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 valores escalares, en la que cada valor escalar representa un comando que CodeBuild 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 los hay, que CodeBuild 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 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 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 se especifica un nombre, CodeBuild crea un grupo de informes utilizando el nombre del proyecto y el nombre especificado 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 valores escalares, en la que cada valor representa una ubicación independiente donde CodeBulid puede encontrar los archivos de prueba, en relación con la ubicación de la compilación original o, si se ha establecido, el
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,
omy-subdirectory
/my-test-report-file.json
).my-parent-subdirectory
/my-subdirectory
/my-test-report-file.json -
'**/*'
representa todos los archivos recursivamente. -
representa todos los archivos de un subdirectorio denominadomy-subdirectory
/*my-subdirectory
. -
representa todos los archivos recursivamente a partir de un subdirectorio denominadomy-subdirectory
/**/*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 informes de cobertura de código JSON generados por simplecov
, no 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 la compilación original, que CodeBuild utiliza 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 contieneyes
, todos los archivos de prueba se colocan en el mismo directorio de salida. Por ejemplo, si una ruta a un resultado de prueba escom/myapp/mytests/TestResult.xml
, especificaryes
colocará este archivo en/TestResult.xml
.
artefactos
Secuencia opcional. Representa información sobre dónde CodeBuild puede encontrar el resultado de compilación y cómo lo prepara para cargarlo en el bucket 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 encabezado de CodeBuild llamado x-amz-meta-codebuild-buildarn
que contiene la buildArn
de la compilación de CodeBuild 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 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,
omy-subdirectory
/my-file.jar
).my-parent-subdirectory
/my-subdirectory
/my-file.jar -
'**/*'
representa todos los archivos recursivamente. -
representa todos los archivos de un subdirectorio denominadomy-subdirectory
/*my-subdirectory
. -
representa todos los archivos recursivamente a partir de un subdirectorio denominadomy-subdirectory
/**/*my-subdirectory
.
AL especificar las ubicaciones de artefactos de salida de la compilación, CodeBuld 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 comoecho $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.
-
Puede utilizar la API de CodeBuild para crear sus compilaciones. Cuando se crea un proyecto, se actualiza o se inicia una compilación, se establece la marca
overrideArtifactName
en el objetoProjectArtifacts
. -
Puede utilizar la consola de CodeBuild para crear sus compilaciones. El nombre se especifica en el archivo de especificaciones de compilación y debe seleccionar Habilitar control semántico de versiones 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 utiliza una variable de entorno de 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 utiliza una variable de entorno de CodeBuild con la fecha de creación del artefacto añadida al final.
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 contieneyes
, 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 escom/mycompany/app/HelloWorld.java
, especificaryes
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 la compilación original, que CodeBuild usa 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 pormy-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
ydiscard-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 a
base-directory
que CodeBuild excluirá de los artefactos de compilació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 bloqueartifacts
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 la 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 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,
omy-subdirectory
/my-file.jar
).my-parent-subdirectory
/my-subdirectory
/my-file.jar -
'**/*'
representa todos los archivos recursivamente. -
representa todos los archivos de un subdirectorio denominadomy-subdirectory
/*my-subdirectory
. -
representa todos los archivos recursivamente a partir de un subdirectorio denominadomy-subdirectory
/**/*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 las consolas de CodeBuild o AWS CodePipeline en lugar de un archivo buildspec.yml, solamente podrá insertar comandos en 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 utilizar las consolas de CodeBuild o CodePipeline, 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 de la fase build
para su uso con las consolas de CodeBuild o 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 claveLOGIN_PASSWORD
. -
No puede cambiar estos nombres de fases de compilación. Los comandos que se ejecutan en este ejemplo son
apt-get update -y
yapt-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 personalizadadockerLoginPassword
definida en el almacén de parámetros de Amazon EC2 Systems Manager) y varios comandosecho
. Los comandosecho
se incluyen aquí para mostrar cómo CodeBuild ejecuta los comandos y en qué orden lo hace. -
files
representa los archivos que se cargan en la ubicación de salida de la compilación. En este ejemplo, CodeBuld carga un solo archivomessageUtil-1.0.jar
. El archivomessageUtil-1.0.jar
se encuentra en el directorio relativo denominadotarget
en el entorno de compilación. Como se ha especificadodiscard-paths: yes
,messageUtil-1.0.jar
se carga directamente (y no en un directoriotarget
intermedio). El nombre de archivomessageUtil-1.0.jar
y el nombre del directorio relativotarget
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 directoriotarget/tests/reports
. El formato del archivo esJunitXml
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 esmy-project
, se crea un grupo de informes con el nombremy-project-reportGroupCucumberJson
cuando se ejecuta una compilación. Los resultados de prueba generados por el marco de pruebas están encucumber/target/cucumber-tests.xml
. El formato del archivo de prueba esCucumberJson
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 |
|
0.1 | Esta es la primera definición del formato de especificación de compilación. |