Build-Spezifikationsreferenz für CodeBuild - AWS CodeBuild
Dateiname der Build-Spezifikation und SpeicherortSyntax der Build-SpezifikationBeispiel für eine Build-SpezifikationVersionen der Build-Spezifikationen

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Build-Spezifikationsreferenz für CodeBuild

Dieses Thema stellt wichtige Referenzinformationen über Build-Spezifikationsdateien (buildspecs) bereit. AbuildSpecEine Sammlung von Build-Befehlen und zugehörigen Einstellungen im YAML-Format, die CodeBuild zum Ausführen eines Builds verwendet. – Sie können eine Build-Spezifikation als Bestandteil des Quellcodes hinterlegen, oder Sie können eine Build-Spezifikation festlegen, wenn Sie ein Build-Projekt erstellen. Informationen zur Funktionsweise einer Build-Spezifikation finden Sie unter Funktionsweise von CodeBuild.

Themen

Dateiname der Build-Spezifikation und Speicherort

Wenn Sie eine Build-Spezifikation als Teil des Quellcodes einbinden, muss die Build-Spezifikationsdatei standardmäßig als buildspec.yml benannt und im Stammverzeichnis Ihres Quellverzeichnisses abgelegt werden.

Sie können den Standard-Namen und -Speicherort der Build-Spezifikationsdatei überschreiben. Beispielsweise können Sie:

  • Verwenden Sie eine andere Build-Spezifikationsdatei für verschiedene Builds im selben Repository, z. B. buildspec_debug.yml und buildspec_release.yml.

  • Speichern Sie eine Build-Spezifikationsdatei in einem anderen Verzeichnis als dem Stammverzeichnis des Quellverzeichnisses, also z. B. in config/buildspec.yml oder in einem S3-Bucket. Der S3-Bucket muss sich in derselben AWS-Region wie das Build-Projekt befinden. Geben Sie die buildspec-Datei mit ihrem ARN an (z. B. arn:aws:s3:::my-codebuild-sample2/buildspec.yml).

Sie können für ein Build-Projekt nur ein Build-Spezifikation angeben, unabhängig vom Namen der Build-Spezifikationsdatei.

Führen Sie einen der folgenden Schritte aus, um den Standard-Dateinamen, -Speicherort der Build-Spezifikationsdatei oder beides zu überschreiben:

  • Führen Sie den AWS CLIcreate-project- oder den update-project-Befehl aus und setzen Sie den buildspec-Wert auf den Pfad zur alternativen Build-Spezifikationsdatei relativ zum Wert der integrierten Umgebungsvariablen CODEBUILD_SRC_DIR. Vergleichbares erreichen Sie mit der create project-Operation in den AWS-SDKs. Weitere Informationen finden Sie unter Erstellen eines Build-Projekts oder Ändern der Einstellungen eines Build-Projekts.

  • Führen Sie den AWS CLI-Befehl start-build aus und setzen Sie den buildspecOverride-Wert auf den Pfad zur alternativen Build-Spezifikationsdatei relativ zum Wert der integrierten Umgebungsvariablen CODEBUILD_SRC_DIR. Vergleichbares erreichen Sie mit der start build-Operation in den AWS-SDKs. Weitere Informationen finden Sie unter Ausführen eines Build.

  • Setzen Sie in einer AWS CloudFormation-Vorlage die BuildSpec-Eigenschaft von Source in einer Ressource vom Typ AWS::CodeBuild::Project auf den Pfad zur alternativen Build-Spezifikationsdatei relativ zum Wert der integrierten Umgebungsvariablen CODEBUILD_SRC_DIR. Weitere Informationen finden Sie unter der BuildSpec eigenschaft inAWS CodeBuildProjektquelleimAWS CloudFormation-Benutzerhandbuchaus.

Syntax der Build-Spezifikation

Build-Spezifikationsdateien müssen im Format YAML ausgedrückt werden.

Wenn ein Befehl ein Zeichen oder eine Zeichenfolge enthält, die von YAML nicht unterstützt wird, müssen Sie den Befehl in Anführungszeichen ("") einschließen. Der folgende Befehl ist in Anführungszeichen eingeschlossen, da ein Doppelpunkt (:) gefolgt von einem Leerzeichen in YAML nicht erlaubt ist. Das Anführungszeichen im Befehl wird mit Escape (\") angegeben. 

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

Die Build-Spezifikation hat die folgende Syntax:

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

Die Build-Spezifikation enthält Folgendes:

version

Erforderliche Zuweisung. Diese steht für die Version der Build-Spezifikation. Wir empfehlen Ihnen, 0.2 zu verwenden.

Anmerkung

Obwohl Version 0.1 wird weiterhin unterstützt wird, empfehlen wir Ihnen, nach Möglichkeit Version 0.2 zu verwenden. Weitere Informationen finden Sie unter Versionen der Build-Spezifikationen.

run-as

Optionale Sequenz. Nur für Linux-Benutzer verfügbar. Gibt einen Linux-Benutzer an, der die Befehle in der buildspec-Datei ausführt.run-asgewährt dem angegebenen Benutzer Lese- und Ausführungsberechtigungen. Wenn Sie run-as zu Beginn der buildspec-Datei angeben, gilt die Einstellung global für alle Befehle. Wenn Sie nicht möchten, dass ein Benutzer Berechtigungen für sämtliche Befehle in der buildspec-Datei erhält, können Sie die Berechtigungen auf eine Phase beschränken, indem Sie run-as in einem der phases-Blöcke angeben. Wird run-as nicht angegeben, werden alle Befehle als Root-Benutzer ausgeführt.

env

Optionale Sequenz. Diese steht für die Informationen von einer oder mehrerer benutzerdefinierter Umgebungsvariablen.

Anmerkung

Zum Schutz vertraulicher Informationen wird in CodeBuild Protokollen Folgendes ausgeblendet:

env/-Shell

Optionale Sequenz. Gibt die unterstützte Shell für Linux- oder Windows-Betriebssysteme an.

Für Linux-Betriebssysteme werden folgende Shell-Tags unterstützt:

  • bash

  • /bin/sh

Für Windows-Betriebssysteme werden folgende Shell-Tags unterstützt:

  • powershell.exe

  • cmd.exe

env/variables

Erforderlich, wenn env angegeben ist und Sie benutzerdefinierte Umgebungsvariablen im Klartext definieren möchten. Enthält eine Zuweisung von Schlüssel/Wert- Skalaren, wobei jede Zuweisung für eine einzige, benutzerdefinierte Umgebungsvariable in Klartext steht. key (Schlüssel) ist der Name der benutzerdefinierten Umgebungsvariablen und value (Wert) ist der Wert dieser Variablen.

Wichtig

Wir raten dringend davon ab, Umgebungsvariablen zum Speichern vertraulicher Werte zu verwenden, dies gilt insbesondere für AWS-Zugriffsschlüssel-IDs und geheime Zugriffsschlüssel. Umgebungsvariablen können mit Tools wie der CodeBuild Konsole und über dieAWS CLIaus. Für vertrauliche Werte sollte stattdessen die Zuweisung per parameter-store oder secrets-manager verwendet werden (siehe unten in diesem Abschnitt).

Jede festgelegte Umgebungsvariable ersetzt vorhandene Umgebungsvariablen. Wenn das Docker-Image beispielsweise bereits eine Umgebungsvariable mit dem Namen MY_VAR und einem Wert von my_value enthält und Sie eine Umgebungsvariable mit dem Namen MY_VAR und einem Wert von other_value festlegen, wird my_value durch other_value ersetzt. Wenn das Docker-Image demgegenüber bereits eine Umgebungsvariable mit dem Namen PATH und einem Wert von /usr/local/sbin:/usr/local/bin enthält und Sie eine Umgebungsvariable mit dem Namen PATH und einem Wert von $PATH:/usr/share/ant/bin festlegen, wird /usr/local/sbin:/usr/local/bin durch den Literalwert $PATH:/usr/share/ant/bin ersetzt.

Legen Sie keine Umgebungsvariable mit einem Namen fest, der mit CODEBUILD_ beginnt. Dieses Präfix ist zur internen Verwendung reserviert.

Wenn eine Umgebungsvariable mit identischem Namen an mehreren Orten definiert ist, wird der Wert folgendermaßen bestimmt:

env/parameter-store

Erforderlich, wennenvErforderlich, und Sie benutzerdefinierte Umgebungsvariablen abrufen möchten, die in Amazon EC2 Systems Manager Parameter Store gespeichert sind. Enthält eine Zuordnung vonSchlüssel/WertSteht für Skalare, wobei jede Zuweisung für eine einzige, benutzerdefinierte Umgebungsvariable steht, die im Amazon EC2 Systems Manager Parameter Store gespeichert ist.SchlüsselDies ist der Name, den Sie später in Ihren Build-Befehlen verwenden werden, um auf diese benutzerdefinierte Umgebungsvariable zu verweisen, undWertDer Name der benutzerdefinierten Umgebungsvariablen, die im Amazon EC2 Systems Manager Parameter Store gespeichert ist. Informationen zum Speichern sensibler Werte finden Sie unterSystems Manager Parameter StoreundExemplarische Vorgehensweise: Erstellen und Testen eines String-Parameters (Konsole)imAmazon EC2 Systems Manager Benutzerhandbuchaus.

Wichtig

Um CodeBuild zu erlauben, benutzerdefinierte Umgebungsvariablen abzurufen, die in Amazon EC2 Systems Manager Parameter Store gespeichert sind, müssen Sie diessm:GetParameters-Aktion auf Ihre CodeBuild Dienstrolle. Weitere Informationen finden Sie unter Erstellen einer CodeBuild--Servicerolle.

Alle Umgebungsvariablen, die Sie von Amazon EC2 Systems Manager Parameter Store abrufen, werden vorhandene Umgebungsvariablen ersetzen. Wenn das Docker-Image beispielsweise bereits eine Umgebungsvariable mit dem Namen MY_VAR und einem Wert von my_value enthält und Sie eine Umgebungsvariable mit dem Namen MY_VAR und einem Wert von other_value abrufen, wird my_value durch other_value ersetzt. Wenn das Docker-Image demgegenüber bereits eine Umgebungsvariable mit dem Namen PATH und einem Wert von /usr/local/sbin:/usr/local/bin enthält und Sie eine Umgebungsvariable mit dem Namen PATH und einem Wert von $PATH:/usr/share/ant/bin abrufen, wird /usr/local/sbin:/usr/local/bin durch den Literalwert $PATH:/usr/share/ant/bin ersetzt.

Speichern Sie keine Umgebungsvariable mit einem Namen, der mit CODEBUILD_ beginnt. Dieses Präfix ist zur internen Verwendung reserviert.

Wenn eine Umgebungsvariable mit identischem Namen an mehreren Orten definiert ist, wird der Wert folgendermaßen bestimmt:

env/secrets-manager

Erforderlich, wenn Sie benutzerdefinierte Umgebungsvariablen abrufen möchten, die inAWS Secrets Manageraus. Legen Sie einen Secrets Managerreference-keyVerwenden Sie das folgende Muster:

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

<key>

(Erforderlich) Der Name der lokalen Umgebungsvariablen. Verwenden Sie diesen Namen, um während des Builds auf die Variable zuzugreifen.

<secret-id>

(Erforderlich) Der Name oder Amazon-Ressourcenname (ARN), der als eindeutige ID für das Secret dient. Um auf ein Secret in Ihrem AWS-Konto zuzugreifen, geben Sie einfach den Secret-Namen an. Um auf ein Secret in einem anderen AWS-Konto zuzugreifen, geben Sie den ARN des Secrets an.

<json-key>

(Optional) Gibt den Schlüsselnamen des Secrets Manager Schlüssel/Wert-Paares an, dessen Wert Sie abrufen möchten. Wenn Sie keinenjson-keyruft CodeBuild den gesamten Secret-Text ab.

<version-stage>

(Optional) Gibt die Secret-Version an, die Sie über die der Version zugeordnete Staging-Kennzeichnung abrufen möchten. Staging-Kennzeichnungen werden verwendet, um während des Rotationsprozesses den Überblick über verschiedene Versionen zu behalten. Wenn Sie version-stage verwenden, geben Sie version-id nicht an. Wenn Sie keine Versionsstufe oder Versions-ID angeben, wird standardmäßig die Version mit dem Versionsstufenwert AWSCURRENT abgerufen.

<version-id>

(Optional) Gibt die eindeutige ID der Version des Secrets an, die Sie verwenden möchten. Wenn Sie version-id angeben, dürfen Sie version-stage nicht angeben. Wenn Sie keine Versionsstufe oder Versions-ID angeben, wird standardmäßig die Version mit dem Versionsstufenwert AWSCURRENT abgerufen.

Im folgenden BeispielTestSecretDer Name des Schlüssel/Wert-Paares, das im Secrets Manager gespeichert ist. Der Schlüssel fürTestSecretistMY_SECRET_VARaus. Sie greifen auf die Variable während des Builds mit demLOCAL_SECRET_VARName. 

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

Weitere Informationen finden Sie unter Was ist AWS Secrets Manager? im AWS Secrets Manager-Benutzerhandbuch.

env/exported-variables

Optionale Zuweisung. Wird verwendet, um Umgebungsvariablen aufzulisten, die Sie exportieren möchten. Geben Sie den Namen jeder Variable, die Sie exportieren möchten, unter exported-variables in einer separaten Zeile an. Die Variable, die Sie exportieren möchten, muss während des Builds in Ihrem Container verfügbar sein. Die Variable, die Sie exportieren, kann eine Umgebungsvariable sein.

Exportierte Umgebungsvariablen werden zusammen mitAWS CodePipeline, um Umgebungsvariablen aus der aktuellen Build-Phase in nachfolgende Phasen in der Pipeline zu exportieren. Weitere Informationen finden Sie unterArbeiten mit VariablenimAWS CodePipeline-Benutzerhandbuchaus.

Während eines Builds ist der Wert einer Variablen ab der install-Phase verfügbar. Er kann zwischen dem Beginn der install-Phase und dem Ende der post_build-Phase aktualisiert werden. Nach dem Ende der post_build-Phase kann sich der Wert der exportierten Variablen nicht ändern.

Anmerkung

Folgendes kann nicht exportiert werden:

  • Schlüssel zum Amazon EC2 Systems Manager Parameter Store, die im Build-Projekt angegeben sind.

  • Secrets Manager-Secrets

  • Umgebungsvariablen, die mit AWS_ beginnen.

env/git-Credential-Helfer

Optionale Zuweisung. Wird verwendet, um anzugeben, ob CodeBuild seinen Git-Hilfsprogramm für Anmeldeinformationen verwendet, um Git-Anmeldeinformationen bereitzustellen.yes, wenn es verwendet wird. Andernfalls no oder nicht angegeben. Weitere Informationen finden Sie unter gitcredentials auf der Git-Website.

Anmerkung

git-credential-helper wird für Builds, die von einem Webhook für ein öffentliches Git-Repository ausgelöst werden, nicht unterstützt.

proxy

Optionale Sequenz. Wird verwendet, um Einstellungen darzustellen, wenn Sie Ihren Build in einem expliziten Proxy-Server ausführen. Weitere Informationen finden Sie unter Ausführen von CodeBuild in einem expliziten Proxy-Server.

proxy/upload-artifacts

Optionale Zuweisung. Legen Sie diese auf yes fest, wenn Ihr Build in einem expliziten Proxy-Server Artefakte hochladen soll. Der Standardwert ist no.

proxy/logs

Optionale Zuweisung. Stellen Sie aufyesSie können Ihren Build in einem expliziten Proxy-Server verwenden, um CloudWatch Protokolle zu erstellen. Der Standardwert ist no.

phases

Erforderliche Sequenz. Steht für die Befehle, die CodeBuild während jeder Phase des Build ausführt.

Anmerkung

In der Build-Spezifikationsversion 0.1 führt CodeBuild jeden Befehl in einer separaten Instance der Standard-Shell in der Build-Umgebung aus. d. h., dass jeder Befehl unabhängig von allen anderen Befehlen ausgeführt wird. Daher können Sie standardmäßig keinen Einzelbefehl ausführen, der auf dem Status eines vorherigen Befehls basiert (beispielsweise beim Ändern von Verzeichnissen oder beim Einrichten von Variablen). Um diese Einschränkung zu umgehen, empfehlen wir die Nutzung von Version 0.2, die dieses Problem löst. Wenn Sie die Build-Spezifikation Version 0.1 verwenden müssen, empfehlen wir die Ansätze in Shells und Befehle in Build-Umgebungen.

phases/*/run-as

Optionale Sequenz. Verwenden Sie den Befehl in einer Build-Phase, um den Linux-Benutzer festzulegen, der die zugehörigen Befehle ausführt. Wenn zusätzlich zu Beginn der buildspec-Datei run-as global für alle Befehle angegeben wird, wird dem Benutzer auf Phasenebene Vorrang eingeräumt. Beispiel: Wenn run-as global User-1 angibt und in der install-Phase eine run-as-Anweisung User-2 definiert, werden alle Befehle in der buildspec-Datei als User-1 ausgeführt, bis auf die Befehle in der install-Phase, die als User-2 ausgeführt werden.

phases/*/bei Fehler

Optionale Sequenz. Gibt die Aktion an, die ausgeführt werden soll, wenn während der Phase ein Fehler auftritt. Dabei kann es sich um einen der folgenden Werte handeln:

  • ABORT- Bricht den Build ab.

  • CONTINUEFahren Sie mit der nächsten Phase fort.

Wenn diese Eigenschaft nicht angegeben ist, folgt der Fehlerprozess den Übergangsphasen, wie inÜbergang von Build-Phasenaus.

phases/*/finally

Optionaler Block. Befehle, die in einemfinally-Block werden nach Befehlen in dercommands-Block. Die Befehle in einemfinally-Block werden auch dann ausgeführt, wenn ein Befehl in dercommands-Block fehlschlägt. Zum Beispiel, wenn diecommands-Block enthält drei Befehle und der erste schlägt fehl, überspringt CodeBuild die verbleibenden zwei Befehle und führt jeden Befehl in derfinally-Block. Die Phase ist erfolgreich, wenn alle Befehle in den Blöcken commands und finally erfolgreich ausgeführt werden. Wenn ein Befehl in einer Phase fehlschlägt, schlägt die Phase fehl.

Die zulässigen Build-Phasennamen sind:

phases/install

Optionale Sequenz. Steht für die Befehle, falls vorhanden, die CodeBuild während der Installation ausführt. Wir empfehlen Ihnen, die Phase install nur für Installationspakete in der Build-Umgebung einzusetzen. Beispielsweise könnten sie diese Phase nutzen, um ein Code-Testframework wie Mocha oder RSpec zu installieren.

phases/install/runtime-versions

Optionale Sequenz. Eine Laufzeitversion wird mit dem Ubuntu-Standardabbild 2.0 oder höher und dem Amazon Linux 2 -Standardabbild 1.0 oder höher unterstützt. Wenn dieses Argument angegeben wird, muss mindestens eine Laufzeit in diesen Abschnitt aufgenommen werden. Geben Sie eine Laufzeit mit einer bestimmten Version an, eine Hauptversion gefolgt von.x, um anzugeben, dass CodeBuild diese Hauptversion mit der neuesten Nebenversion verwendet, oderlatest, um die neueste Haupt- und Nebenversion zu verwenden (z. B.java: openjdk11,ruby: 2.6,nodejs: 12.x, oderjava: latest) enthalten. Sie können die Laufzeit unter Verwendung einer Zahl oder einer Umgebungsvariablen angeben. Wenn Sie beispielsweise das Amazon Linux 2 -Standardabbild 2.0 verwenden, wird folgendermaßen angegeben, dass Version 8 von Java, die neueste Unterversion von Python Version 3 und eine in einer Umgebungsvariablen von Ruby enthaltene Version installiert sind. Weitere Informationen finden Sie unter Von CodeBuild bereitgestellte Docker-Images. 

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

Sie können eine oder mehrere Laufzeiten im Abschnitt runtime-versions Ihrer buildspec-Datei angeben. Wenn Ihre Laufzeit von einer anderen Laufzeit abhängig ist, können Sie auch die abhängige Laufzeit in der buildspec-Datei angeben. Wenn Sie keine Laufzeiten in der buildspec-Datei angeben, wählt CodeBuild die Standardlaufzeiten aus, die in dem verwendeten Image verfügbar sind. Wenn Sie eine oder mehrere Laufzeiten angeben, verwendet CodeBuild nur diese Laufzeiten. Wenn keine abhängige Laufzeit angegeben wird, versucht CodeBuild, die abhängige Laufzeit für Sie auszuwählen.

Wenn zwei angegebene Laufzeiten unvereinbar sind, schlägt der Build fehl. Beispiel: android: 29 und java: openjdk11 sind miteinander unvereinbar. Wenn beide angegeben werden, schlägt der Build fehl.

Weitere Hinweise zu den verfügbaren Laufzeiten finden Sie unterVerfügbare Laufzeitenaus.

Anmerkung

Wenn Sie eineruntime-versionsWenn Sie ein anderes Image als Ubuntu-Standardabbild 2.0 oder höher oder das Amazon Linux 2 (AL2) -Standardabbild 1.0 oder höher verwenden, gibt der Build die Warnung aus,“Skipping install of runtimes. Runtime version selection is not supported by this build image.“

phases/install/commands

Optionale Sequenz. Enthält eine Sequenz von Skalaren, wobei jeder Skalar für einen Einzelbefehl steht, den CodeBuild während der Installation ausführt. CodeBuild führt jeden Befehl aus, jeweils einzeln in der aufgeführten Reihenfolge, vom Anfang bis zum Ende.

phases/pre_build

Optionale Sequenz. Steht für die Befehle, falls vorhanden, die CodeBuild vor dem Build ausführt. Beispielsweise könnten sie diese Phase nutzen, um sich bei Amazon ECR anzumelden, oder Sie könnten npm-Abhängigkeiten installieren.

phases/pre_build/commands

Erforderliche Sequenz, wenn pre_build angegeben ist. Enthält eine Sequenz von Skalaren, wobei jeder Skalar für einen Einzelbefehl steht, den CodeBuild vor dem Build ausführt. CodeBuild führt jeden Befehl aus, jeweils einzeln in der aufgeführten Reihenfolge, vom Anfang bis zum Ende.

phases/build

Optionale Sequenz. Steht für die Befehle, falls vorhanden, die CodeBuild während des Build ausführt. Beispielsweise könnten sie diese Phase nutzen, um Mocha, RSpec oder sbt auszuführen.

phases/build/commands

Erforderlich, wennbuildangegeben ist. Enthält eine Sequenz von Skalaren, wobei jeder Skalar für einen Einzelbefehl steht, den CodeBuild während des Builds ausführt. CodeBuild führt jeden Befehl aus, jeweils einzeln in der aufgeführten Reihenfolge, vom Anfang bis zum Ende.

phases/post_build

Optionale Sequenz. Steht für die Befehle, falls vorhanden, die CodeBuild nach dem Build ausführt. Beispielsweise könnten Sie Maven verwenden, um die Build-Artefakte in eine Jar- oder WAR-Datei zu verpacken, oder Sie könnten ein Docker-Image in Amazon ECR verschieben. Dann können Sie eine Build-Benachrichtigung über Amazon SNS senden.

phases/post_build/commands

Erforderlich, wennpost_buildangegeben ist. Enthält eine Sequenz von Skalaren, wobei jeder Skalar für einen Einzelbefehl steht, den CodeBuild nach dem Build ausführt. CodeBuild führt jeden Befehl aus, jeweils einzeln in der aufgeführten Reihenfolge, vom Anfang bis zum Ende.

reports

report-group-name-or-arn

Optionale Sequenz. Gibt die Berichtsgruppe an, an die die Berichte gesendet werden. Ein Projekt kann maximal fünf Berichtsgruppen haben. Geben Sie den ARN für eine vorhandene Berichtsgruppe oder den Namen einer neuen Berichtsgruppe an. Wenn Sie einen Namen angeben, erstellt CodeBuild eine Berichtsgruppe unter Verwendung des Projektnamens und des im -Format angegebenen Namens.<project-name>-<report-group-name>aus. Weitere Informationen finden Sie unter Benennung von Berichtsgruppen.

reports/<report-group>/files

Erforderliche Sequenz. Stellt die Speicherorte dar, die die Rohdaten der vom Bericht generierten Testergebnisse enthalten. Enthält eine Sequenz von Skalaren, wobei jeder Skalar für einen einzelnen Speicherort steht, an dem CodeBuild in Bezug auf die ursprünglichen Build-Speicherorte finden kann, oder, sofern festgelegt, auf diebase-directoryaus. Speicherorte können Folgendes enthalten:

  • Eine Einzeldatei (z. B. my-test-report-file.json).

  • Eine einzelne Datei in einem Unterverzeichnis (Beispiel: my-subdirectory/my-test-report-file.json oder my-parent-subdirectory/my-subdirectory/my-test-report-file.json).

  • '**/*' steht rekursiv für alle Dateien.

  • my-subdirectory/* steht für alle Dateien in einem Unterverzeichnis mit Namen my-subdirectory.

  • my-subdirectory/**/* steht rekursiv für alle Dateien beginnend mit einem Unterverzeichnis mit Namen my-subdirectory.

reports/<report-group>/file-format

Optionale Zuweisung. Stellt das Berichtsdateiformat dar. Wenn nicht angegeben, wird JUNITXML verwendet. Bei diesem Wert wird nicht zwischen Kleinschreibung unterschieden. Die möglichen Werte sind:

Testberichte

CUCUMBERJSON

Cucumber JSON

JUNITXML

JUnit XML

NUNITXML

NUnit XML

NUNIT3XML

NUnit 3 XML

TESTNGXML

TestNG XML

VISUALSTUDIOTRX

Visual Studio TRX

Code-Abdeckungsberichte

CLOVERXML

Clover XML

COBERTURAXML

Cobertura XML

JACOCOXML

JaCoCo XML

SIMPLECOV

SimpleCov JSON

Anmerkung

CodeBuild akzeptiert JSON-Codeabdeckungsberichte, die vonsimplecov, nichtsimplecov-jsonaus.

reports/<report-group>/base-directory

Optionale Zuweisung. Stellt ein oder mehrere Verzeichnisse der obersten Ebene in Bezug auf den ursprünglichen Build-Speicherort dar, den CodeBuild verwendet, um zu ermitteln, wo die rohen Testdateien gefunden werden sollen.

reports/<report-group>/discard-paths

Optional. Gibt an, ob die Berichtsdateiverzeichnisse in der Ausgabe abgeflacht werden. Wenn dies nicht angegeben ist oder no enthält, werden Berichtsdateien mit intakter Verzeichnisstruktur ausgegeben. Wenn dies yes enthält, werden alle Testdateien im selben Ausgabeverzeichnis abgelegt. Wenn beispielsweise ein Pfad zu einem Testergebnis com/myapp/mytests/TestResult.xml lautet, wird die Datei durch Angabe von yes in /TestResult.xml gespeichert.

artifacts

Optionale Sequenz. Stellt Informationen darüber dar, wo CodeBuild die Build-Ausgabe finden kann, und wie CodeBuild diese auf den Upload zum S3-Ausgabe-Bucket vorbereitet. Diese Sequenz ist nicht erforderlich, wenn Sie beispielsweise ein Docker-Image erstellen und dies zu Amazon ECR verschieben, oder wenn Sie Einheitentests auf Ihrem Quellcode ausführen, dies jedoch nicht erstellen.

artifacts/files

Erforderliche Sequenz. Diese stellt die Speicherorte dar, die die Build-Ausgabeartefakte in der Build-Umgebung enthalten. Enthält eine Sequenz von Skalaren, wobei jeder Skalar für einen einzelnen Speicherort steht, an dem CodeBuild Build-Ausgabeartefakte in Bezug auf die ursprünglichen Build-Speicherorte finden kann, oder, sofern festgelegt, auf das Basisverzeichnis. Speicherorte können Folgendes enthalten:

  • Eine Einzeldatei (z. B. my-file.jar).

  • Eine einzelne Datei in einem Unterverzeichnis (Beispiel: my-subdirectory/my-file.jar oder my-parent-subdirectory/my-subdirectory/my-file.jar).

  • '**/*' steht rekursiv für alle Dateien.

  • my-subdirectory/* steht für alle Dateien in einem Unterverzeichnis mit Namen my-subdirectory.

  • my-subdirectory/**/* steht rekursiv für alle Dateien beginnend mit einem Unterverzeichnis mit Namen my-subdirectory.

Wenn Sie Speicherorte von Build-Ausgabeartefakten angeben, kann CodeBuild den ursprünglichen Build-Speicherort in der Build-Umgebung lokalisieren. Sie müssen die Speicherorte von Build-Ausgabeartefakten mit dem Pfad zu den ursprünglichen Build-Speicherorten nicht voranstellen oder angeben, ./ oder ähnliches. Wenn sie den Pfad zu diesem Speicherort wissen möchten, können Sie während eines Builds ein Befehl ausführen wie echo $CODEBUILD_SRC_DIR. Der Speicherort für jede Build-Umgebung kann geringfügig voneinander abweichen.

artifacts/name

Optionaler Name. Gibt einen Namen für Ihr Build-Artefakt an. Dieser Name wird verwendet, wenn eine der folgenden Bedingungen zutrifft.

  • Sie verwenden die CodeBuild API, um Ihre Builds zu erstellen und dieoverrideArtifactName-Flag auf derProjectArtifacts-Objekt, wenn ein Projekt aktualisiert wird, ein Projekt erstellt wird oder ein Build gestartet wird.

  • Sie verwenden die CodeBuild Konsole zum Erstellen Ihrer Builds, einen in der buildspec-Datei angegeben Namen, und wählenAktivieren von semantischen VersioningWenn Sie ein Projekt erstellen oder aktualisieren. Weitere Informationen finden Sie unter Erstellen Sie ein Build-Projekt (Konsole).

Sie können einen Namen in der Build-Spezifikationsdatei angeben, die zur Build-Zeit berechnet wird. Der in einer Build-Spezifikationsdatei angegebene Name verwendet die Shell-Befehlssprache. Beispielsweise können Sie dem Namen Ihres Artefakts ein Datum und eine Uhrzeit anhängen, damit dieser stets eindeutig ist. Eindeutige Artefakt-Namen verhindern, dass Artefakte überschrieben werden. Weitere Informationen finden Sie unter Shell-Befehlssprache.

  • Dies ist ein Beispiel für einen Artefakt-Namen, dem das Datum angefügt wurde, an dem das Artefakt erstellt wurde. 

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

  • Dies ist ein Beispiel für einen Artefakt-Namen, der eine CodeBuild Umgebungsvariable verwendet. Weitere Informationen finden Sie unter Umgebungsvariablen in Build-Umgebungen. 

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

  • Dies ist ein Beispiel für einen Artefakt-Namen, der eine CodeBuild Umgebungsvariable verwendet, und das Erstellungsdatum des Artefakts angefügt ist. 

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

Sie können dem Namen Pfadinformationen hinzufügen, sodass die benannten Artefakte in Verzeichnissen basierend auf dem Pfad im Namen platziert werden. Build-Artefakte werden in der Ausgabe unterbuilds/<build number>/my-artifactsaus. 

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

Optional. Gibt an, ob die Build-Artefaktnerzeichnisse in der Ausgabe abgeflacht werden. Wenn dies nicht angegeben ist oder no enthält, werden Build-Artefakte mit intakter Verzeichnisstruktur ausgegeben. Wenn yesenthalten ist, werden alle Build-Artefakte im selben Ausgabeverzeichnis platziert. Wenn beispielsweise ein Pfad zu einer Datei im Build-Ausgabeartefakt com/mycompany/app/HelloWorld.java ist, wird diese Datei durch Angabe von yes in /HelloWorld.java gespeichert.

artifacts/base-directory

Optionale Zuweisung. Stellt eines oder mehrere Verzeichnisse der obersten Ebene in Bezug auf den ursprünglichen Build-Speicherort dar, den CodeBuild verwendet, um zu ermitteln, welche Dateien und Unterverzeichnisse in das Build-Ausgabeartefakt aufgenommen werden. Gültige Werte sind:

  • Ein einziges Top-Level-Verzeichnis (z. B. my-directory).

  • 'my-directory*' stellt alle Top-Level-Verzeichnisse dar, deren Namen mit my-directory beginnen.

Die übereinstimmenden Top-Level-Verzeichnisse werden nicht in den Build-Ausgabeartefakt aufgenommen, sondern nur deren Dateien und Unterverzeichnisse.

Sie können files und discard-paths verwenden, um weiter zu beschränken, welche Dateien und Unterverzeichnisse aufgenommen werden. Wie zum Beispiel für die folgende Verzeichnisstruktur: 

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

Und für die folgende Sequenz artifacts : 

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

Das folgende Unterverzeichnis und die Datei werden in den Build-Ausgabeartefakt aufgenommen:

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

Während für die Sequenz artifacts Folgendes gilt: 

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

Die folgenden Dateien werden in den Build-Ausgabeartefakt aufgenommen:

.
├── my-file-1.txt
├── my-file-2.txt
└── my-file-3.txt
Artefakte/Ausschließen von Pfaden

Optionale Zuweisung. Stellt einen oder mehrere Pfade relativ zubase-directory, dass CodeBuild aus den Build-Artefakten ausschließt.

Artefakte/enable-Symlinks

Optional. Wenn der AusgabetypZIP, gibt an, ob interne symbolische Links in der ZIP-Datei erhalten bleiben. Wenn diesyes, werden alle internen symbolischen Links in der Quelle in der ZIP-Datei der Artefakte beibehalten.

Artefakte/s3-Präfix

Optional. Gibt ein Präfix an, das verwendet wird, wenn die Artefakte in einen Amazon S3 Bucket ausgegeben werden und der Namespace-TypBUILD_IDaus. Bei Verwendung ist der Ausgabepfad im Bucket<s3-prefix>/<build-id>/<name>.zipaus.

artifacts/secondary-artifacts

Optionale Sequenz. Repräsentiert einzelne oder mehrere Artefaktdefinitionen als Zuordnung zwischen einem Artefaktbezeichner und einer Artefaktdefinition. Jeder Artefaktbezeichner in diesem Block muss einem im Attribut secondaryArtifacts des Projekts definierten Artefakt entsprechen. Jede separate Definition hat die gleiche Syntax wie der artifacts-Block oben.

Anmerkung

Dieartifacts/filesSequenz ist immer erforderlich, auch wenn nur sekundäre Artefakte definiert sind.

Angenommen sei ein Projekt mit folgender Struktur:

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

Anschließend sieht die buildspec-Datei wie folgt aus:

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

Optionale Sequenz. Stellt Informationen darüber dar, wo CodeBuild die Dateien für das Hochladen des Caches in einen S3-Cache-Bucket vorbereiten kann. Diese Sequenz ist nicht erforderlich, wenn der Cache-Typ des Projekts No Cache ist.

cache/paths

Erforderliche Sequenz. Steht für die Speicherorte des Caches. Enthält eine Sequenz von Skalaren, wobei jeder Skalar für einen einzelnen Speicherort steht, an dem CodeBuild Build-Ausgabeartefakte in Bezug auf die ursprünglichen Build-Speicherorte finden kann, oder, sofern festgelegt, auf das Basisverzeichnis. Speicherorte können Folgendes enthalten:

  • Eine Einzeldatei (z. B. my-file.jar).

  • Eine einzelne Datei in einem Unterverzeichnis (Beispiel: my-subdirectory/my-file.jar oder my-parent-subdirectory/my-subdirectory/my-file.jar).

  • '**/*' steht rekursiv für alle Dateien.

  • my-subdirectory/* steht für alle Dateien in einem Unterverzeichnis mit Namen my-subdirectory.

  • my-subdirectory/**/* steht rekursiv für alle Dateien beginnend mit einem Unterverzeichnis mit Namen my-subdirectory.

Wichtig

Da es sich bei der Build-Spezifikationsdeklaration um eine gültige YAML handelt, ist die Formatierung in einer Build-Spezifikationsdeklaration wichtig. Wenn die Anzahl der Leerzeichen in der Build-Spezifikationsdeklaration unzulässig ist, können die Builds sofort fehlschlagen. Verwenden Sie eine YAML-Validierung, um zu testen, ob es sich bei Ihrer Build-Spezifikationsdeklaration um eine gültige YAML handelt.

Wenn sie die AWS CLI, oder die AWS-SDKs verwenden, um eine Build-Spezifikation bei der Erstellung oder Aktualisierung eines Build-Projekts zu deklarieren, muss die Build-Spezifikation aus einer einzigen Zeichenfolge im YAML-Format, zusammen mit den erforderlichen Escape-Zeichen für Leerzeichen und Zeilenumbruch bestehen. Es folgt ein Beispiel im nächsten Abschnitt.

Wenn Sie den CodeBuild oderAWS CodePipeline-Konsolen statt einer Datei buildspec.yml können Sie Befehle für diebuild-Phase. Statt die vorherige Syntax zu verwenden, geben Sie in einer einzigen Ziele sämtliche Befehle an, die Sie während der Build-Phase verwenden möchten. Bei mehreren Befehlen unterteilen Sie die einzelnen Befehle mit &&, (wie z. B. mvn test && mvn package).

Sie können die Konsolen CodeBuild oder CodePipeline anstelle einer Datei buildspec.yml verwenden, um die Speicherorte der Build-Ausgabeartefakte in der Build-Umgebung anzugeben. Statt die vorherige Syntax zu verwenden, geben Sie in einer einzigen Ziele sämtliche Speicherorte an. Bei mehreren Speicherorten trennen Sie die einzelnen Speicherorte durch ein Komma, (wie z. B. buildspec.yml, target/my-app.jar).

Beispiel für eine Build-Spezifikation

Hier finden Sie ein Beispiel für eine Datei 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/**/*'

Hier ist ein Beispiel der vorherigen Build-Spezifikation, ausgedrückt in einer einzigen Zeichenfolge für die Verwendung mit der AWS CLI oder den AWS-SDKs. 

"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/**/*'"

Hier sehen Sie ein Beispiel der Befehle in derbuild-Phase zur Verwendung mit den Konsolen CodeBuild oder CodePipeline. 

echo Build started on `date` && mvn install

In diesen Beispielen gilt:

  • Eine benutzerdefinierte Klartext-Umgebungsvariable mit dem Schlüssel JAVA_HOME und dem Wert /usr/lib/jvm/java-8-openjdk-amd64 wird eingerichtet.

  • Eine benutzerdefinierte Umgebungsvariable namensdockerLoginPasswordWenn Sie in Amazon EC2 Systems Manager Parameter Store gespeichert sind, wird später in Build-Befehlen mit dem SchlüsselLOGIN_PASSWORDaus.

  • Sie können diese Build-Phasennamen nicht ändern. Die Befehle, die in diesem Beispiel ausgeführt werden, sindapt-get update -yundapt-get install -y maven(um Apache Maven zu installieren),mvn install(um den Quellcode zu kompilieren, zu testen und in ein Build-Ausgabeartefakt zu verpacken und das Build-Ausgabeartefakt in seinem internen Repository zu installieren),docker login(um sich bei Docker mit dem Kennwort anzumelden, das dem Wert der benutzerdefinierten Umgebungsvariablen entsprichtdockerLoginPassword), die Sie im Amazon EC2 Systems Manager Parameter Store festgelegt haben.echo-Befehle. DieechoDiese Befehle werden hier aufgenommen, um zu zeigen, wie und in welcher Reihenfolge Befehle ausführt.

  • files stellt die Dateien dar, die in den Build-Ausgabespeicherort hochgeladen werden sollen. In diesem Beispiel lädt CodeBuild die Einzeldatei hochmessageUtil-1.0.jaraus. Die Datei messageUtil-1.0.jar ist in dem jeweiligen Verzeichnis mit Namen target in der Build-Umgebung zu finden. Da discard-paths: yes angegeben wird, wird messageUtil-1.0.jar direkt hochgeladen (und nicht an ein intermediäres Verzeichnis mit dem Namen target). Der Dateiname messageUtil-1.0.jar und der dazugehörige Verzeichnisname von target basiert auf der Weise, wie - nur für dieses Beispiel - unter den Apache Maven Build-Ausgabeartefakte erstellt und gespeichert werden. In Ihren eigenen Szenarios lauten diese Dateinamen und Verzeichnisse anders.

  • reports stellt zwei Berichtsgruppen dar, die während des Builds Berichte generieren:

    • arn:aws:codebuild:your-region:your-aws-account-id:report-group/report-group-name-1 gibt den ARN einer Berichtsgruppe an. Testergebnisse, die vom Test-Framework generiert werden, befinden sich im Verzeichnis target/tests/reports. Das Dateiformat ist JunitXml und der Pfad wird nicht aus den Dateien entfernt, die Testergebnisse enthalten.

    • reportGroupCucumberJson gibt eine neue Berichtsgruppe an. Wenn der Name des Projekts my-project lautet, wird beim Ausführen eines Builds eine Berichtsgruppe mit dem Namen my-project-reportGroupCucumberJson erstellt. Testergebnisse, die vom Test-Framework generiert werden, befinden sich in cucumber/target/cucumber-tests.xml. Das Testdateiformat ist CucumberJson und der Pfad wird aus den Dateien entfernt, die Testergebnisse enthalten.

Versionen der Build-Spezifikationen

In der folgenden Tabelle werden Versionen von Build-Spezifikationen und die Änderungen zwischen den Versionen aufgeführt.

Version Änderungen
0.2

  • environment_variables wurde umbenannt in env.

  • plaintext wurde umbenannt in variables.

  • Die type-Eigenschaft für artifacts ist veraltet.

  • In Version 0.1 führt AWS CodeBuild jeden Build-Befehl in einer separaten Instance der Standard-Shell in der Build-Umgebung aus. In Version 0.2 führt CodeBuild jeden Build-Befehl in derselben Instance der Standard-Shell in der Build-Umgebung aus.

0.1 Dies ist die erste Definition des Build-Spezifikationsformats.