Référence de spécification de construction pour CodeBuild - AWS CodeBuild
Nom de fichier buildspec et emplacement de stockageSyntaxe d'un fichier buildspecExemple de fichier buildspecVersions de fichier buildspec

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Référence de spécification de construction pour CodeBuild

Cette rubrique fournit des informations de référence importantes sur les fichiers de spécification de génération (buildspec). Un buildspec est un ensemble de commandes de construction et de paramètres associés, au format YAML, qui est CodeBuild utilisé pour exécuter un build. Vous pouvez inclure une spécification de construction dans le code source ou vous pouvez définir une spécification de construction lorsque vous créez un projet de construction. Pour plus d'informations sur le fonctionnement des spécifications de génération, consultez Fonctionnement de CodeBuild.

Rubriques

Nom de fichier buildspec et emplacement de stockage

Si vous incluez une spécification de build dans le cadre du code source, par défaut, le fichier de spécification de build doit être nommé buildspec.yml et être placé à la racine de votre répertoire source.

Vous pouvez remplacer le nom et l'emplacement par défaut du fichier de spécification de build. Par exemple, vous pouvez :

  • Utiliser un fichier de spécification de build distinct pour différentes builds dans le même référentiel, comme par exemple buildspec_debug.yml et buildspec_release.yml.

  • Stocker un fichier de spécification de build ailleurs qu'à la racine de votre répertoire source, par exemple config/buildspec.yml ou dans un compartiment S3. Le compartiment S3 doit se trouver dans la même AWS région que votre projet de construction. Spécifiez le fichier buildspec à l'aide de son nom ARN (par exemple, arn:aws:s3:::<my-codebuild-sample2>/buildspec.yml).

Vous pouvez spécifier une seule spécification de build pour un projet de build, quel que soit le nom du fichier de spécification de build.

Pour remplacer le nom, l'emplacement, ou les deux, du fichier de spécification de build par défaut, effectuez l'une des actions suivantes :

  • Exécutez la update-project commande AWS CLI create-project or, en définissant la buildspec valeur sur le chemin du fichier buildspec alternatif par rapport à la valeur de la variable d'environnement intégrée. CODEBUILD_SRC_DIR Vous pouvez également faire l'équivalent avec l'create projectopération dans les AWS SDK. Pour plus d’informations, consultez Création d'un projet de génération ou Modification des paramètres d'un projet de génération.

  • Exécutez la AWS CLI start-build commande en définissant la buildspecOverride valeur sur le chemin du fichier buildspec alternatif par rapport à la valeur de la variable d'environnement intégrée. CODEBUILD_SRC_DIR Vous pouvez également faire l'équivalent avec l'start buildopération dans les AWS SDK. Pour de plus amples informations, veuillez consulter Exécution d'une génération.

  • Dans un AWS CloudFormation modèle, définissez la BuildSpec propriété de Source in a resource of type AWS::CodeBuild::Project sur le chemin d'accès au fichier buildspec alternatif par rapport à la valeur de la variable d'environnement intégrée. CODEBUILD_SRC_DIR Pour plus d'informations, consultez la BuildSpec propriété dans la source AWS CodeBuild du projet dans le guide de AWS CloudFormation l'utilisateur.

Syntaxe d'un fichier buildspec

Les fichiers de spécification de build doivent être créés au format YAML.

Si une commande contient un caractère ou une chaîne de caractères qui ne sont pas pris en charge par YAML, vous devez placer la commande entre guillemets (""). La commande suivante est placée entre guillemets car un deux-points (:) suivi d'un espace n'est pas autorisé dans YAML. Dans la commande, le guillemet est échappé (\").

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

La spécification de build a la syntaxe suivante :

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 spécification de build contient les éléments suivants :

version

Mappage obligatoire. Représente la version de la spécification de build. Nous vous recommandons d'utiliser 0.2.

Note

Bien que la version 0.1 soit toujours prise en charge, nous vous recommandons d'utiliser la version 0.2 dans la mesure du possible. Pour de plus amples informations, veuillez consulter Versions de fichier buildspec.

run-as

Séquence facultative. Disponible uniquement pour les utilisateurs Linux. Spécifie un utilisateur Linux qui exécute des commandes dans ce fichier buildspec. run-asaccorde à l'utilisateur spécifié des autorisations de lecture et d'exécution. Lorsque vous spécifiez run-as en haut du fichier buildspec, il s'applique globalement à toutes les commandes. Si vous ne voulez pas spécifier un utilisateur pour toutes les commandes de fichier buildspec, vous pouvez en spécifier un pour les commandes dans une phase à l'aide de run-as dans l'un des blocs phases. Si run-as n'est pas spécifié, toutes les commandes sont exécutées en tant qu'utilisateur racine.

env

Séquence facultative. Représente les informations pour une ou plusieurs variables d'environnement personnalisées.

Note

Pour protéger les informations sensibles, les informations suivantes sont masquées dans CodeBuild les journaux :

env/ coque

Séquence facultative. Spécifie le shell pris en charge pour les systèmes d'exploitation Linux ou Windows.

Pour les systèmes d'exploitation Linux, les balises shell prises en charge sont les suivantes :

  • bash

  • /bin/sh

Pour les systèmes d'exploitation Windows, les balises shell prises en charge sont les suivantes :

  • powershell.exe

  • cmd.exe

env/variables

Obligatoire si env est spécifié, et que vous voulez définir des variables d'environnement personnalisées en texte brut. Contient un mappage de scalaires clé / valeur, où chaque mappage représente une variable d'environnement personnalisée unique en texte brut. clé est le nom de la variable d'environnement personnalisée, et valeur est la valeur de cette variable.

Important

Nous déconseillons vivement le stockage de valeurs sensibles dans les variables d'environnement. Les variables d'environnement peuvent être affichées en texte brut à l'aide d'outils tels que la CodeBuild console et le AWS CLI. Pour les valeurs sensibles, nous vous recommandons d'utiliser à la place le mappage parameter-store ou secrets-manager, comme décrit plus loin dans cette section.

Les variables d'environnement que vous définissez remplacent les variables d'environnement existantes. Par exemple, si l'image Docker contient déjà une variable d'environnement nommée MY_VAR avec la valeur my_value et que vous définissez une variable d'environnement nommée MY_VAR avec la valeur other_value, la valeur my_value est remplacée par other_value. De même, si l'image Docker contient déjà une variable d'environnement nommée PATH avec la valeur /usr/local/sbin:/usr/local/bin et que vous définissez une variable d'environnement nommée PATH avec la valeur $PATH:/usr/share/ant/bin, la valeur /usr/local/sbin:/usr/local/bin est remplacée par la valeur littérale $PATH:/usr/share/ant/bin.

Ne définissez pas de variables d'environnement avec un nom commençant par CODEBUILD_. Ce préfixe est réservé à une utilisation interne .

Si une variable d'environnement avec le même nom est définie dans plusieurs emplacements, la valeur est déterminée comme suit :

env/magasin de paramètres

Obligatoire si cela env est spécifié et si vous souhaitez récupérer des variables d'environnement personnalisées stockées dans Amazon EC2 Systems Manager Parameter Store. Contient un mappage de scalaires clé/valeur, où chaque mappage représente une variable d'environnement personnalisée unique stockée dans le magasin de paramètres Amazon EC2 Systems Manager. key est le nom que vous utiliserez ultérieurement dans vos commandes de compilation pour faire référence à cette variable d'environnement personnalisée, et value est le nom de la variable d'environnement personnalisée stockée dans Amazon EC2 Systems Manager Parameter Store. Pour stocker des valeurs sensibles, consultez la section Stockage des paramètres de Systems Manager et procédure pas à pas : création et test d'un paramètre de chaîne (console) dans le guide de l'utilisateur d'Amazon EC2 Systems Manager.

Important

CodeBuild Pour permettre de récupérer des variables d'environnement personnalisées stockées dans Amazon EC2 Systems Manager Parameter Store, vous devez ajouter ssm:GetParameters l'action à CodeBuild votre rôle de service. Pour de plus amples informations, veuillez consulter Création d'un rôle CodeBuild de service.

Toutes les variables d'environnement que vous récupérez depuis Amazon EC2 Systems Manager Parameter Store remplacent les variables d'environnement existantes. Par exemple, si l'image Docker contient déjà une variable d'environnement nommée MY_VAR avec une valeur my_value, et que vous récupérez une variable d'environnement nommée MY_VAR avec une valeur other_value, la valeur my_value est alors remplacée par other_value. De même, si l'image Docker contient déjà une variable d'environnement nommée PATH avec une valeur /usr/local/sbin:/usr/local/bin, et que vous récupérez une variable d'environnement nommée PATH avec une valeur $PATH:/usr/share/ant/bin, la valeur /usr/local/sbin:/usr/local/bin est alors remplacée par la valeur littérale $PATH:/usr/share/ant/bin.

Ne stockez pas de variables d'environnement avec un nom commençant par CODEBUILD_. Ce préfixe est réservé à une utilisation interne .

Si une variable d'environnement avec le même nom est définie dans plusieurs emplacements, la valeur est déterminée comme suit :

env/Secrets Manager

Obligatoire si vous souhaitez récupérer des variables d'environnement personnalisées stockées dans AWS Secrets Manager. Spécifiez un Gestionnaire de Secrets reference-key en utilisant le modèle suivant :

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

<key>

(Obligatoire) Le nom de la variable d'environnement locale. Utilisez ce nom pour accéder à la variable lors de la génération.

<secret-id>

(Obligatoire) Le nom ou Amazon Resource Name (ARN) qui sert d'identifiant unique pour le secret. Pour accéder à un secret dans votre compte AWS , spécifiez simplement le nom secret. Pour accéder à un secret dans un autre AWS compte, spécifiez l'ARN du secret.

<json-key>

(Facultatif) Spécifie le nom de clé de la paire clé-valeur de Secrets Manager dont vous souhaitez récupérer la valeur. Si vous ne spécifiez pas dejson-key, CodeBuild récupère l'intégralité du texte secret.

<version-stage>

(Facultatif) Spécifie la version secrète que vous souhaitez récupérer à l'aide de l'étiquette intermédiaire attachée à la version. Les étiquettes intermédiaires sont utilisées pour assurer le suivi des différentes versions au cours du processus de rotation. Si vous utilisez la version-stage, ne spécifiez pas l’version-id. Si vous ne spécifiez pas d'étape de version ni d'ID de version, par défaut, vous devez récupérer la version avec la valeur d'étape de version de AWSCURRENT.

<version-id>

(Facultatif) Spécifie l'identifiant unique de la version du secret que vous souhaitez utiliser. Si vous spécifiez version-id, ne spécifiez pas version-stage. Si vous ne spécifiez pas d'étape de version ni d'ID de version, par défaut, vous devez récupérer la version avec la valeur d'étape de version de AWSCURRENT.

Dans l'exemple suivant, TestSecret c'est le nom de la paire clé-valeur stockée dans Secrets Manager. La clé pour TestSecret nousMY_SECRET_VAR. Vous pouvez accéder à la variable pendant la construction en utilisant le LOCAL_SECRET_VAR nom.

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

Pour plus d’informations, consultez Présentation de AWS Secrets Manager dans le Guide de l’utilisateur AWS Secrets Manager .

env/variables exportées

Mappage facultatif. Permet de répertorier les variables d'environnement que vous souhaitez exporter. Spécifiez le nom de chaque variable que vous souhaitez exporter sur une ligne distincte sous exported-variables. La variable que vous souhaitez exporter doit être disponible dans votre conteneur pendant la génération. La variable que vous exportez peut être une variable d'environnement.

Les variables d'environnement exportées sont utilisées conjointement AWS CodePipeline pour exporter les variables d'environnement de la phase de construction actuelle vers les étapes suivantes du pipeline. Pour plus d'informations, consultez la section Utilisation des variables dans le Guide de AWS CodePipeline l'utilisateur.

Lors d'une génération, la valeur d'une variable est disponible dès la phase install. Elle peut être mise à jour entre le début de la phase install et la fin de la phase post_build. Lorsque la phase post_build est terminée, la valeur des variables exportées ne peut pas changer.

Note

Les éléments suivants ne peuvent pas être exportés :

  • Les secrets du magasin de paramètres Amazon EC2 Systems Manager sont spécifiés dans le projet de construction.

  • Secrets Manager : secrets spécifiés dans le projet de construction

  • Les variables d'environnement qui commencent par AWS_.

env/ git-credential-helper

Mappage facultatif. Utilisé pour indiquer s'il CodeBuild utilise son assistant d'identification Git pour fournir des informations d'identification Git. yess'il est utilisé. Sinon, no ou non spécifié. Pour plus d'informations, consultez gitcredentials sur le site web de Git.

Note

git-credential-helper n’est pas pris en charge pour les générations qui sont déclenchées par un webhook pour un référentiel Git public.

proxy

Séquence facultative. Utilisé pour représenter les paramètres si vous exécutez votre génération dans un serveur proxy explicite. Pour de plus amples informations, veuillez consulter Exécution de CodeBuild sur un serveur proxy explicite.

proxy/charger les artefacts

Mappage facultatif. Définissez ce paramètre sur yes si vous souhaitez que votre build dans un serveur proxy explicite charge des artefacts. L’argument par défaut est no.

proxy/journaux

Mappage facultatif. Définissez ce yes paramètre pour intégrer un serveur proxy explicite afin de créer des CloudWatch journaux. L’argument par défaut est no.

phases

Séquence obligatoire. Représente les CodeBuild commandes exécutées pendant chaque phase de la génération.

Note

Dans la version 0.1 de buildspec, CodeBuild exécute chaque commande dans une instance distincte du shell par défaut dans l'environnement de construction. Cela signifie que chaque commande s'exécute isolée de toutes les autres commandes. Par conséquent, par défaut, vous ne pouvez pas exécuter une commande unique qui s'appuie sur l'état de commandes précédentes (par exemple, pour le changement de répertoire ou la définition de variables d'environnement). Pour contourner ce problème, nous vous recommandons d'utiliser la version 0.2, qui permet de résoudre ce problème. Si vous devez utiliser la spécification de build de version 0.1, nous vous recommandons les approches figurant dans Shells et commandes dans les environnements de génération.

phases/*/run-as

Séquence facultative. Utilisez-le dans une phase de build pour spécifier un utilisateur Linux qui exécute ses commandes. Si run-as est également spécifié globalement pour toutes les commandes en haut du fichier buildspec, alors l'utilisateur au niveau de phase est prioritaire. Par exemple, si run-as spécifie globalement l'utilisateur-1, et pour la phase install seule une instruction run-as spécifie l'utilisateur 2, alors toutes les commandes dans le fichier buildspec sont exécutées en tant qu'utilisateur-1, sauf les commandes dans la phase install, qui sont exécutées en tant qu'utilisateur-2.

phases/*/ en cas de défaillance

Séquence facultative. Spécifie l'action à entreprendre en cas de défaillance au cours de la phase. Il peut s’agir de l’une des valeurs suivantes :

  • ABORT- Annulation de la construction.

  • CONTINUE- Passez à la phase suivante.

Si cette propriété n'est pas spécifiée, le processus d'échec suit les phases de transition, comme indiqué dansTransitions des phases de génération.

phases/*/ enfin

Bloc facultatif. Les commandes spécifiées dans un finally bloc sont exécutées après les commandes du commands bloc. Les commandes d'un finally bloc sont exécutées même si une commande du commands bloc échoue. Par exemple, si le commands bloc contient trois commandes et que la première échoue, CodeBuild ignore les deux commandes restantes et exécute toutes les commandes du finally bloc. La phase est réussie lorsque toutes les commandes des blocs commands et finally s'exécutent avec succès. Si une commande d'une phase échoue, la phase échoue.

Les noms de phase de génération autorisés sont :

phases/installer

Séquence facultative. Représente les commandes, le cas échéant, CodeBuild exécutées pendant l'installation. Nous vous recommandons d'utiliser la phase install uniquement pour l'installation de packages dans l'environnement de génération. Par exemple, vous pouvez utiliser cette phase pour installer une infrastructure de test de code comme Mocha ou RSpec.

phases/installer/versions d'exécution

Séquence facultative. Une version d'exécution est prise en charge avec l'image standard Ubuntu 5.0 ou ultérieure et l'image standard Amazon Linux 2 4.0 ou version ultérieure. Si cette valeur est spécifiée, au moins une exécution doit être incluse dans cette section. Spécifiez un environnement d'exécution utilisant une version spécifique, une version majeure suivie de .x pour spécifier qui CodeBuild utilise cette version majeure avec sa dernière version mineure, ou latest pour utiliser les versions majeure et mineure les plus récentes (par exempleruby: 3.2,nodejs: 18.x, oujava: latest). Vous pouvez spécifier l’exécution à l'aide d'un nombre ou d'une variable d'environnement. Par exemple, si vous utilisez l'image standard 4.0 d'Amazon Linux 2, ce qui suit indique que la version 17 de Java, la dernière version mineure de python version 3 et une version contenue dans une variable d'environnement de Ruby sont installées. Pour de plus amples informations, veuillez consulter Images Docker fournies par CodeBuild. 

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

Vous pouvez spécifier un ou plusieurs runtimes dans la section runtime-versions de votre fichier buildspec. Si votre runtime dépend d'un autre runtime, vous pouvez également spécifier son runtime dépendant dans le fichier buildspec. Si vous ne spécifiez aucun environnement d'exécution dans le fichier buildspec, CodeBuild choisissez les environnements d'exécution par défaut disponibles dans l'image que vous utilisez. Si vous spécifiez un ou plusieurs environnements d'exécution, utilisez uniquement CodeBuild ces environnements d'exécution. Si aucun environnement d'exécution dépendant n'est spécifié, CodeBuild tente de le choisir pour vous.

Si deux exécutions spécifiées entrent en conflit, la génération échoue. Par exemple, android: 29 et java: openjdk11 sont en conflit, par conséquent si les deux sont spécifiés, la génération échoue.

Pour plus d'informations sur les environnements d'exécution disponibles, consultezRuntimes disponibles.

Note

Si vous spécifiez une runtime-versions section et utilisez une image autre qu'Ubuntu Standard Image 2.0 ou version ultérieure, ou l'image standard Amazon Linux 2 (AL2) 1.0 ou version ultérieure, le build émet l'avertissement « »Skipping install of runtimes. Runtime version selection is not supported by this build image.

phases/installer/commandes

Séquence facultative. Contient une séquence de scalaires, où chaque scalaire représente une commande unique CodeBuild exécutée pendant l'installation. CodeBuild exécute chaque commande, une par une, dans l'ordre indiqué, du début à la fin.

phases/prégénération

Séquence facultative. Représente les commandes, le cas échéant, CodeBuild exécutées avant la génération. Par exemple, vous pouvez utiliser cette phase pour vous connecter à Amazon ECR, ou vous pouvez installer des dépendances npm.

phases/prégénération/commandes

Séquence obligatoire si pre_build est spécifié. Contient une séquence de scalaires, où chaque scalaire représente une commande unique CodeBuild exécutée avant la génération. CodeBuildexécute chaque commande, une par une, dans l'ordre indiqué, du début à la fin.

phases/génération

Séquence facultative. Représente les commandes, le cas échéant, CodeBuild exécutées pendant la génération. Par exemple, vous pouvez utiliser cette phase pour exécuter Mocha, RSpec ou sbt.

phases/génération/commandes

Obligatoire si cela build est spécifié. Contient une séquence de scalaires, où chaque scalaire représente une commande unique CodeBuild exécutée pendant la génération. CodeBuild exécute chaque commande, une par une, dans l'ordre indiqué, du début à la fin.

phases/post-génération

Séquence facultative. Représente les commandes, le cas échéant, qui CodeBuild s'exécutent après la génération. Par exemple, vous pouvez utiliser Maven pour empaqueter les artefacts de construction dans un fichier JAR ou WAR, ou vous pouvez transférer une image Docker dans Amazon ECR. Vous pouvez ensuite envoyer une notification de build via Amazon SNS.

phases/post-génération/commandes

Obligatoire si cela post_build est spécifié. Contient une séquence de scalaires, où chaque scalaire représente une commande unique CodeBuild exécutée après la génération. CodeBuild exécute chaque commande, une par une, dans l'ordre indiqué, du début à la fin.

rapports

report-group-name-or-fil

Séquence facultative. Spécifie le groupe de rapports auquel les rapports sont envoyés. Un projet peut comporter un maximum de cinq groupes de rapports. Spécifiez l'ARN d'un groupe de rapports existant ou le nom d'un nouveau groupe de rapports. Si vous spécifiez un nom, CodeBuild crée un groupe de rapports en utilisant le nom de votre projet et le nom que vous spécifiez dans le format<project-name>-<report-group-name>. Le nom du groupe de rapports peut également être défini à l'aide d'une variable d'environnement dans la spécification de construction, telle que. $REPORT_GROUP_NAME Pour de plus amples informations, veuillez consulter Attribution des noms des groupes de rapports.

rapports/<groupe de rapports>/fichiers

Séquence obligatoire. Représente les emplacements qui contiennent les données brutes des résultats de test générés par le rapport. Contient une séquence de scalaires, chaque scalaire représentant un emplacement distinct où se CodeBuild trouvent les fichiers de test, par rapport à l'emplacement de construction d'origine ou, s'il est défini, au. base-directory Il peut s'agir notamment des emplacements suivants :

  • Un fichier unique (par exemple, my-test-report-file.json).

  • Un fichier unique dans un sous-répertoire (par exemple, my-subdirectory/my-test-report-file.json ou my-parent-subdirectory/my-subdirectory/my-test-report-file.json).

  • '**/*' représente tous les fichiers de manière récursive.

  • my-subdirectory/* représente tous les fichiers dans un sous-répertoire nommé mon-sous-répertoire.

  • my-subdirectory/**/* représente tous les fichiers de manière récursive à partir d'un sous-répertoire nommé mon-sous-répertoire.

rapports/<groupe de rapports>/format de fichier

Mappage facultatif. Représente le format du fichier de rapport. Si non spécifié, JUNITXML est utilisé. Cette valeur ne distingue pas les majuscules et minuscules. Les valeurs possibles sont :

Rapports d'essais
CUCUMBERJSON

Cucumber JSON

JUNITXML

JUnit XML

NUNITXML

NUnit XML

NUNIT3XML

NUnit 3 XML

TESTNGXML

TestNG XML

VISUALSTUDIOTRX

Visual Studio TRX

Rapports sur la couverture du code
CLOVERXML

Trèfle XML

COBERTURAXML

Couverture XML

JACOCOXML

JaCoCo XML

SIMPLECOV

SimpleCov JSON

Note

CodeBuild accepte les rapports de couverture du code JSON générés par simplecov, et non par simplecov-json.

rapports/<groupe de rapports>/répertoire de base

Mappage facultatif. Représente un ou plusieurs répertoires de niveau supérieur, relatifs à l'emplacement de construction d'origine, qui CodeBuild permettent de déterminer où trouver les fichiers de test bruts.

rapports/<groupe de rapports>/annuler les chemins

Facultatif. Spécifie si les répertoires de fichiers de rapport sont aplatis dans la sortie. Si cela n'est pas spécifié ou si no est défini, les fichiers de rapport sont générés avec leur structure de répertoire intacte. Si yes est défini, tous les fichiers de test sont placés dans le même répertoire de sortie. Par exemple, si un chemin d'accès à un résultat de test est com/myapp/mytests/TestResult.xml, la définition de yes place ce fichier dans /TestResult.xml.

artefacts

Séquence facultative. Représente des informations indiquant où se CodeBuild trouve la sortie de génération et comment CodeBuild la préparer pour le téléchargement vers le compartiment de sortie S3. Cette séquence n'est pas obligatoire si, par exemple, vous créez et transférez une image Docker vers Amazon ECR, ou si vous exécutez des tests unitaires sur votre code source, mais que vous ne le créez pas.

Note

Les métadonnées Amazon S3 ont un CodeBuild en-tête nommé x-amz-meta-codebuild-buildarn qui contient le nom buildArn de la CodeBuild version qui publie les artefacts sur Amazon S3. Le buildArn est ajouté pour permettre le suivi de la source des notifications et pour indiquer la version à partir de laquelle l'artefact est généré.

artefacts/fichiers

Séquence obligatoire. Représente les emplacements qui contiennent les artefacts de sortie de génération dans l'environnement de génération. Contient une séquence de scalaires, où chaque scalaire représente un emplacement distinct où CodeBuild peut trouver des artefacts de sortie de génération, par rapport à l'emplacement de génération d'origine ou, si défini, au répertoire de base. Il peut s'agir notamment des emplacements suivants :

  • Un fichier unique (par exemple, my-file.jar).

  • Un fichier unique dans un sous-répertoire (par exemple, my-subdirectory/my-file.jar ou my-parent-subdirectory/my-subdirectory/my-file.jar).

  • '**/*' représente tous les fichiers de manière récursive.

  • my-subdirectory/* représente tous les fichiers dans un sous-répertoire nommé mon-sous-répertoire.

  • my-subdirectory/**/* représente tous les fichiers de manière récursive à partir d'un sous-répertoire nommé mon-sous-répertoire.

Lorsque vous spécifiez les emplacements des artefacts de sortie de construction, vous CodeBuild pouvez localiser l'emplacement de construction d'origine dans l'environnement de construction. Vous n'avez pas besoin de préfixer les emplacements d'artefact de sortie de génération avec le chemin de l'emplacement de génération d'origine, ni de spécifier ./ ou un élément similaire. Si vous souhaitez connaître le chemin d'accès à cet emplacement, vous pouvez exécuter une commande comme echo $CODEBUILD_SRC_DIR pendant une génération. L'emplacement de chaque environnement de génération peut être légèrement différent.

artefacts/nom

Nom facultatif. Spécifie un nom pour votre artefact de génération. Ce nom est utilisé lorsque l'une des conditions suivantes est vraie.

  • Vous utilisez l' CodeBuild API pour créer vos versions et l'overrideArtifactNameindicateur est défini sur l'ProjectArtifactsobjet lorsqu'un projet est mis à jour, qu'un projet est créé ou qu'un build est lancé.

  • Vous utilisez la CodeBuild console pour créer vos versions, un nom est spécifié dans le fichier buildspec et vous sélectionnez Activer le versionnement sémantique lorsque vous créez ou mettez à jour un projet. Pour de plus amples informations, veuillez consulter Création d'un projet de génération (console).

Vous pouvez spécifier un nom dans le fichier de spécification de build qui est calculé au moment de la génération. Le nom spécifié dans un fichier de spécification de build utilise le langage de commandes Shell. Par exemple, vous pouvez ajouter une date et une heure au nom de votre artefact afin qu'il soit toujours unique. Les noms d'artefact uniques empêchent les artefacts d'être écrasés. Pour de plus amples informations, veuillez consulter Langage de commandes Shell.

  • Ceci est un exemple de nom d'artefact suivi de la date à laquelle l'artefact a été créé. 

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

  • Il s'agit d'un exemple de nom d'artefact qui utilise une variable d' CodeBuild environnement. Pour de plus amples informations, veuillez consulter Variables d'environnement dans les environnements de génération. 

    version: 0.2
phases:
  build:
    commands:
      - rspec HelloWorld_spec.rb
artifacts:
  files:
    - '**/*'
  name: myname-$AWS_REGION

  • Il s'agit d'un exemple de nom d'artefact qui utilise une variable d' CodeBuild environnement à laquelle est ajoutée la date de création de l'artefact. 

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

Vous pouvez ajouter des informations de chemin au nom afin que les artefacts nommés soient placés dans des répertoires en fonction du chemin indiqué dans le nom. Dans cet exemple, les artefacts de construction sont placés dans la sortie sousbuilds/<build number>/my-artifacts.

version: 0.2
phases:
  build:
    commands:
      - rspec HelloWorld_spec.rb
artifacts:
  files:
    - '**/*'
  name: builds/$CODEBUILD_BUILD_NUMBER/my-artifacts
artefacts/ignorer les chemins

Facultatif. Spécifie si les répertoires d'artefacts de génération sont aplatis dans la sortie. Si cela n'est pas spécifié, si no est défini, les artefacts de génération sont générés avec leur structure de répertoire intacte. Si yes est défini, tous les artefacts de génération sont placés dans le même répertoire de sortie. Par exemple, si un chemin d'accès à un fichier dans l'artefact de sortie de génération est com/mycompany/app/HelloWorld.java, la définition de yes permet de placer ce fichier dans /HelloWorld.java.

artefacts/répertoire de base

Mappage facultatif. Représente un ou plusieurs répertoires de niveau supérieur, relatifs à l'emplacement de génération d'origine, qui permettent CodeBuild de déterminer les fichiers et sous-répertoires à inclure dans l'artefact de sortie de génération. Les valeurs valides sont les suivantes :

  • Un répertoire unique de niveau supérieur (par exemple, my-directory).

  • 'my-directory*' représente tous les répertoires de niveau supérieur avec les noms commençant par my-directory.

Les répertoires de niveau supérieur correspondants ne sont pas inclus dans l'artefact de sortie de génération, seulement leurs fichiers et sous-répertoires.

Vous pouvez utiliser files et discard-paths pour limiter encore plus les fichiers et sous-répertoires inclus. Par exemple, pour la structure de répertoire suivante : 

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

Et pour la séquence artifacts suivante :

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

Le sous-répertoire et le fichier suivants seront inclus dans l'artefact de sortie de génération :

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

Alors que pour la séquence artifacts suivante :

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

Les fichiers suivants seront inclus dans l'artefact de sortie de génération :

.
├── my-file-1.txt
├── my-file-2.txt
└── my-file-3.txt
artéfacts/ chemins d'exclusion

Mappage facultatif. Représente un ou plusieurs chemins, relatifs àbase-directory, qui CodeBuild seront exclus de la construction des artefacts. L'astérisque (*) correspond à zéro ou plusieurs caractères d'un composant de nom sans dépasser les limites d'un dossier. Un double astérisque (**) correspond à zéro ou plusieurs caractères d'un composant de nom dans tous les répertoires.

Les exemples de chemins d'exclusion sont les suivants :

  • Pour exclure un fichier de tous les répertoires : "**/file-name/**/*"

  • Pour exclure tous les dossiers à points, procédez comme suit : "**/.*/**/*"

  • Pour exclure tous les fichiers à points : "**/.*"

Facultatif. Si le type de sortie estZIP, indique si les liens symboliques internes sont conservés dans le fichier ZIP. Si tel est le casyes, tous les liens symboliques internes de la source seront conservés dans le fichier ZIP des artefacts.

artéfacts/ préfixe s3

Facultatif. Spécifie un préfixe utilisé lorsque les artefacts sont envoyés vers un compartiment Amazon S3 et que le type d'espace de noms est. BUILD_ID Lorsqu'il est utilisé, le chemin de sortie dans le compartiment est<s3-prefix>/<build-id>/<name>.zip.

artefacts/artefacts secondaires

Séquence facultative. Représente une ou plusieurs définitions d'artefacts comme correspondance entre l'identificateur d'un artefact et la définition d'un artefact. Chaque identifiant d'artefact de ce bloc doit correspondre à un artefact défini dans l'attribut secondaryArtifacts de votre projet. Chaque définition distincte a la même syntaxe que le bloc artifacts ci-dessus.

Note

La artifacts/filesséquence est toujours requise, même lorsque seuls des artefacts secondaires sont définis.

Par exemple, si la structure de votre projet est la suivante :

{
  "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"
    }
  ]
}

Votre fichier buildspec ressemble alors à ceci :

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

Séquence facultative. Représente des informations sur l'endroit où CodeBuild préparer les fichiers pour le téléchargement du cache dans un compartiment de cache S3. Cette séquence n'est pas requise si le type de cache du projet est No Cache.

cache/chemins

Séquence obligatoire. Représente les emplacements du cache. Contient une séquence de scalaires, chaque scalaire représentant un emplacement distinct où CodeBuild peuvent trouver les artefacts de sortie de construction, par rapport à l'emplacement de construction d'origine ou, s'il est défini, au répertoire de base. Il peut s'agir notamment des emplacements suivants :

  • Un fichier unique (par exemple, my-file.jar).

  • Un fichier unique dans un sous-répertoire (par exemple, my-subdirectory/my-file.jar ou my-parent-subdirectory/my-subdirectory/my-file.jar).

  • '**/*' représente tous les fichiers de manière récursive.

  • my-subdirectory/* représente tous les fichiers dans un sous-répertoire nommé mon-sous-répertoire.

  • my-subdirectory/**/* représente tous les fichiers de manière récursive à partir d'un sous-répertoire nommé mon-sous-répertoire.

Important

Comme une déclaration de spécification de build doit être dans un format YAML valide, les espaces sont importants dans une déclaration de spécification de build. Si le nombre d'espaces dans votre déclaration de spécification de build n'est pas valide, les builds peuvent échouer immédiatement. Vous pouvez utiliser un validateur YAML pour tester si vos déclarations de spécification de build sont dans un format YAML valide.

Si vous utilisez le AWS CLI ou les AWS SDK pour déclarer une spécification de construction lorsque vous créez ou mettez à jour un projet de construction, la spécification de construction doit être une chaîne unique exprimée au format YAML, avec les espaces blancs et les caractères d'échappement de nouvelle ligne requis. Vous trouverez un exemple dans la section suivante.

Si vous utilisez les AWS CodePipeline consoles CodeBuild ou au lieu d'un fichier buildspec.yml, vous pouvez insérer des commandes pour la phase uniquement. build Au lieu d'utiliser la syntaxe précédente, vous répertoriez, sur une seule ligne, toutes les commandes que vous souhaitez exécuter lors de la phase de génération (build). Pour plusieurs commandes, séparez celles-ci avec && (par exemple, mvn test && mvn package).

Vous pouvez utiliser les CodePipeline consoles CodeBuild ou au lieu d'un fichier buildspec.yml pour spécifier les emplacements des artefacts de sortie de génération dans l'environnement de génération. Au lieu d'utiliser la syntaxe précédente, vous répertoriez, sur une seule ligne, tous les emplacements. Pour plusieurs emplacements, séparez ceux-ci avec une virgule (par exemple, buildspec.yml, target/my-app.jar).

Exemple de fichier buildspec

Voici un exemple de fichier 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/**/*'

Voici un exemple de la spécification de construction précédente, exprimée sous forme de chaîne unique, à utiliser avec le ou AWS CLI les SDK. 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/**/*'"

Voici un exemple des commandes de la build phase, à utiliser avec les CodePipeline consoles CodeBuild or.

echo Build started on `date` && mvn install

Dans les exemples suivants :

  • Une variable d'environnement personnalisée, en texte brut, avec la clé JAVA_HOME et la valeur /usr/lib/jvm/java-8-openjdk-amd64 est définie.

  • Une variable d'environnement personnalisée nommée dockerLoginPassword you stockée dans Amazon EC2 Systems Manager Parameter Store est référencée ultérieurement dans les commandes de construction à l'aide de la LOGIN_PASSWORD clé.

  • Vous ne pouvez pas modifier ces noms de phase de génération. Les commandes exécutées dans cet exemple sont apt-get update -y et apt-get install -y maven (pour installer Apache Maven), mvn install (pour compiler, tester et empaqueter le code source dans un artefact de sortie de build et pour installer l'artefact de sortie de build dans son référentiel interne), docker login (pour se connecter à Docker avec le mot de passe correspondant à la valeur de la variable d'environnement personnalisée que dockerLoginPassword vous avez définie dans Amazon EC2 Systems Manager Parameter Store) et plusieurs commandes. echo Les echo commandes sont incluses ici pour montrer comment les CodeBuild commandes sont exécutées et l'ordre dans lequel elles sont exécutées.

  • files représente les fichiers à charger dans l'emplacement de sortie de génération. Dans cet exemple, CodeBuild télécharge le fichier messageUtil-1.0.jar unique. Le fichier messageUtil-1.0.jar peut être trouvé dans le répertoire relatif nommé target dans l'environnement de génération. Comme discard-paths: yes est spécifié, messageUtil-1.0.jar est chargé directement (et non dans un répertoire target intermédiaire). Le nom de fichier messageUtil-1.0.jar et le nom de répertoire relatif de target sont basés sur la façon dont Apache crée et stocke les artefacts de sortie de génération pour cet exemple uniquement. Dans votre propres scénarios, ces noms de fichier et ces répertoires seront différents.

  • reports représente deux groupes de rapports qui génèrent des rapports pendant la génération :

    • arn:aws:codebuild:your-region:your-aws-account-id:report-group/report-group-name-1 spécifie l'ARN d'un groupe de rapports. Les résultats des tests générés par le framework de test se trouvent dans le répertoire target/tests/reports. Le format de fichier est JunitXml et le chemin d'accès n'est pas supprimé des fichiers contenant les résultats du test.

    • reportGroupCucumberJson spécifie un nouveau groupe de rapports. Si le nom du projet est my-project, un groupe de rapports portant le nom my-project-reportGroupCucumberJson est créé lors de l'exécution d'une génération. Les résultats des tests générés par le framework de test sont dans cucumber/target/cucumber-tests.xml. Le format de fichier test est CucumberJson et le chemin d'accès est supprimé des fichiers contenant les résultats du test.

Versions de fichier buildspec

Le tableau suivant répertorie les versions de spécification de build et les modifications entre les versions.

Version Modifications
0.2

  • environment_variables a été renommée en env.

  • plaintext a été renommée en variables.

  • La propriété type pour artifacts est obsolète.

  • Dans la version 0.1, AWS CodeBuild exécute chaque commande de construction dans une instance distincte du shell par défaut dans l'environnement de construction. Dans la version 0.2, CodeBuild exécute toutes les commandes de construction dans la même instance du shell par défaut dans l'environnement de construction.
0.1 Il s'agit de la définition initiale du format de spécification de génération.