Riferimento per le specifiche di compilazione per CodeBuild - AWS CodeBuild
Nome del file buildspec e posizione di storageSintassi buildspecEsempio di buildspecVersioni di buildspec

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Riferimento per le specifiche di compilazione per CodeBuild

Questo argomento fornisce importanti informazioni di riferimento sui file di specifiche di compilazione (buildspec). Una specifica di compilazione è una raccolta di comandi di compilazione e impostazioni correlate, in formato YAML, che CodeBuild utilizza per eseguire una compilazione. Puoi includere una buildspec come parte del codice sorgente oppure puoi definire una buildspec quando crei un progetto di compilazione. Per informazioni sul funzionamento di una specifica di build, consulta Come funziona CodeBuild.

Argomenti

Nome del file buildspec e posizione di storage

Se includi una buildspec come parte del codice sorgente, per impostazione predefinita il file deve essere denominato buildspec.yml e deve trovarsi nella root della directory di origine.

È possibile sostituire il nome e la posizione del file buildspec. Ad esempio, sono possibili le seguenti operazioni:

  • Utilizzare un file buildspec diverso per diverse build nello stesso repository, ad esempio buildspec_debug.yml e buildspec_release.yml.

  • Archiviare un file buildspec in una posizione diversa rispetto alla root della directory di origine, ad esempio config/buildspec.yml o in un bucket S3. Il bucket S3 deve trovarsi nella stessa regione AWS del progetto di build. Specificare il file buildspec utilizzando il relativo ARN (ad esempio, arn:aws:s3:::<my-codebuild-sample2>/buildspec.yml).

Puoi specificare solo una buildspec per ogni progetto di compilazione, indipendentemente dal nome del file buildspec.

Per sostituire il nome o la posizione predefiniti del file buildspec o entrambi, eseguire una delle seguenti operazioni:

  • Eseguire il comando AWS CLI create-project o update-project, impostando il valore buildspec sul percorso dell'altro file buildspec relativo al valore della variabile di ambiente integrata CODEBUILD_SRC_DIR. Si può anche utilizzare l'operazione create project nei kit SDK AWS. Per ulteriori informazioni, consultare Creazione di un progetto di compilazione o Modifica delle impostazioni di un progetto di compilazione.

  • Eseguire il comando AWS CLI start-build, impostando il valore buildspecOverride sul percorso dell'altro file buildspec relativo al valore della variabile di ambiente integrata CODEBUILD_SRC_DIR. Si può anche utilizzare l'operazione start build nei kit SDK AWS. Per ulteriori informazioni, consulta Esecuzione di una compilazione.

  • In un modello AWS CloudFormation, impostare la proprietà BuildSpec di Source in una risorsa di tipo AWS::CodeBuild::Project sul percorso dell'altro file buildspec relativo al valore della variabile di ambiente integrata CODEBUILD_SRC_DIR. Per ulteriori informazioni, consulta laBuildSpecproprietà inAWS CodeBuildfonte del progettonelAWS CloudFormationGuida per l'utente.

Sintassi buildspec

I file buildspec devono essere espressi in formato YAML.

Se un comando contiene un carattere, o una stringa di caratteri, che non è supportato da YAML, è necessario racchiudere il comando tra virgolette (""). Il seguente comando è racchiuso tra virgolette perché un segno di due punti (:) seguito da uno spazio non è consentito in YAML. La virgoletta nel comando è escape (\").

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

Buildspec presenta la seguente sintassi:

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

Il file buildspec contiene quanto segue:

versione

Mappatura obbligatoria. Rappresenta la versione buildspec. Ti consigliamo di utilizzare 0.2.

Nota

Anche se la versione 0.1 è ancora supportata, consigliamo di utilizzare la versione 0.2 ogni volta che è possibile. Per ulteriori informazioni, consulta Versioni di buildspec.

run-as

Sequenza opzionale. Disponibile per gli utenti Linux. Speciifica un utente Linux che esegue i comandi in questo file buildspec.run-asconcede all'utente specificato le autorizzazioni di lettura ed esecuzione. Quando specifichi run-as nella parte superiore del file buildspec, viene applicato globalmente a tutti i comandi. Se non vuoi specificare un utente per tutti i comandi del file buildspec, puoi specificarne uno per i comandi di una fase utilizzando run-as in uno dei blocchi phases. Se run-as non è specificato, tutti i comandi vengono eseguiti come utente root.

env

Sequenza opzionale. Rappresenta le informazioni su una o più variabili di ambiente personalizzate.

Nota

Per proteggere le informazioni riservate, i seguenti sono nascosti nei log CodeBuild:

env/guscio

Sequenza opzionale. Speciifica la shell supportata per i sistemi operativi Linux o Windows.

Per i sistemi operativi Linux, i tag shell supportati sono:

  • bash

  • /bin/sh

Per i sistemi operativi Windows, i tag shell supportati sono:

  • powershell.exe

  • cmd.exe

env/variables

Obbligatorio se è specificato env e si desidera definire variabili di ambiente personalizzate in testo normale. Contiene una mappatura di scalari chiave/valore, in cui ogni mappatura rappresenta una sola variabile di ambiente personalizzata in testo normale. chiave è il nome della variabile di ambiente personalizzata e valore è il valore della variabile.

Importante

Sconsigliamo vivamente la memorizzazione di valori sensibili nelle variabili di ambiente. Le variabili di ambiente possono essere visualizzate come testo normale utilizzando strumenti come la console CodeBuild e la AWS CLI. Per i valori sensibili, consigliamo di utilizzare la mappatura parameter-store o secrets-manager, come descritto più avanti in questa sezione.

Tutte le variabili di ambiente impostate sostituiscono quelle esistenti. Ad esempio, se l'immagine Docker contiene già una variabile di ambiente denominata MY_VAR con un valore di my_value, e si imposta una variabile di ambiente denominata MY_VAR con un valore di other_value, il valore my_value viene sostituito da other_value. Allo stesso modo, se l'immagine Docker contiene già una variabile di ambiente denominata PATH con un valore di /usr/local/sbin:/usr/local/bin, e si imposta una variabile di ambiente denominata PATH con un valore di $PATH:/usr/share/ant/bin, il valore di /usr/local/sbin:/usr/local/bin viene sostituito dal valore letterale $PATH:/usr/share/ant/bin.

Non impostare variabili di ambiente con nomi che iniziano con CODEBUILD_. Questo prefisso è riservato per l'uso interno .

Se una variabile di ambiente con lo stesso nome viene definita in più luoghi, il valore viene determinato come segue:

env/parameter-store

Richiesto seenvè specificato e desideri recuperare le variabili di ambiente personalizzate archiviate in Amazon EC2 Systems Manager Parameter Store. Contiene una mappatura dichiave/valorescalari, dove ogni mappatura rappresenta una singola variabile di ambiente personalizzata memorizzata in Amazon EC2 Systems Manager Parameter Store.chiaveè il nome che utilizzerai più avanti nei comandi di build per fare riferimento a questa variabile di ambiente personalizzata evaloreè il nome della variabile di ambiente personalizzata memorizzata in Amazon EC2 Systems Manager Parameter Store. Per memorizzare valori sensibili, vediArchivio dei parametri di Systems ManagereProcedura dettagliata: creazione e test di un parametro String (console)nelGuida per l'utente di Amazon EC2 Systems Manager.

Importante

ConsentireCodeBuildper recuperare le variabili di ambiente personalizzate archiviate in Amazon EC2 Systems Manager Parameter Store, è necessario aggiungere ilssm:GetParametersazione al tuoCodeBuildruolo di servizio. Per ulteriori informazioni, consulta Crea un ruolo CodeBuild di servizio.

Tutte le variabili di ambiente recuperate da Amazon EC2 Systems Manager Parameter Store sostituiscono le variabili di ambiente esistenti. Ad esempio, se l'immagine Docker contiene già una variabile di ambiente denominata MY_VAR con un valore di my_value e si recupera una variabile di ambiente denominata MY_VAR con un valore di other_value, il valore my_value viene sostituito da other_value. Allo stesso modo, se l'immagine Docker contiene già una variabile di ambiente denominata PATH con un valore di /usr/local/sbin:/usr/local/bin e si recupera una variabile di ambiente denominata PATH con un valore di $PATH:/usr/share/ant/bin, il valore di /usr/local/sbin:/usr/local/bin viene sostituito dal valore letterale $PATH:/usr/share/ant/bin.

Non archiviare variabili di ambiente con nomi che iniziano con CODEBUILD_. Questo prefisso è riservato per l'uso interno .

Se una variabile di ambiente con lo stesso nome viene definita in più luoghi, il valore viene determinato come segue:

env/secrets-manager

Obbligatorio se desideri recuperare variabili di ambiente personalizzate memorizzate inAWS Secrets Manager. Specificare un Secrets Managerreference-keyutilizzando il seguente schema:

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

<key>

(Obbligatorio) Il nome della variabile di ambiente locale. Usa questo nome per accedere alla variabile durante la compilazione.

<secret-id>

(Obbligatorio) Il nome o Amazon Resource Name (ARN) che funge da identificatore univoco per il segreto. Per accedere a un segreto nel tuo account AWS, devi semplicemente specificare il nome segreto. Per accedere a un segreto in un altro account AWS, specifica l'ARN segreto.

<json-key>

(Facoltativo) Specificate il nome della chiave della coppia chiave-valore di Secrets Manager di cui desiderate recuperare il valore. Se non specifichi json-key, CodeBuild recupera tutto il testo del segreto.

<version-stage>

(Facoltativo) Specificate la versione segreta che desiderate recuperare tramite l'etichetta temporanea allegata alla versione. Le etichette temporanee sono utilizzate per tenere traccia di differenti versioni durante il processo di rotazione. Se utilizzi version-stage, non specificare version-id. Se non specifichi una fase o un ID di versione, l'impostazione predefinita è recuperare la versione con il valore di fase di versione AWSCURRENT.

<version-id>

(Facoltativo) Specificate l'identificatore univoco della versione del segreto che desiderate utilizzare. Se specifichi version-id, non specificare version-stage. Se non specifichi una fase o un ID di versione, l'impostazione predefinita è recuperare la versione con il valore di fase di versione AWSCURRENT.

Nell'esempio seguente,TestSecretè il nome della coppia chiave-valore memorizzata in Secrets Manager. La chiave perTestSecretèMY_SECRET_VAR. Si accede alla variabile durante la compilazione utilizzando ilLOCAL_SECRET_VARnome.

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

Per ulteriori informazioni, consulta Che cos'è AWS Secrets Manager? nella Guida per l'utente di AWS Secrets Manager.

env/exported-variables

Mappatura opzionale. Utilizzato per elencare le variabili di ambiente che si desidera esportare. Specificare il nome di ogni variabile che si desidera esportare su una riga separata sotto exported-variables. La variabile che si desidera esportare deve essere disponibile nel contenitore durante la compilazione. La variabile esportata può essere una variabile di ambiente.

Le variabili di ambiente esportate vengono utilizzate insieme aAWS CodePipelineper esportare le variabili di ambiente dalla fase di compilazione corrente alle fasi successive della pipeline. Per ulteriori informazioni, vedereLavorare con le variabilinelAWS CodePipelineGuida per l'utente.

Durante una compilazione, il valore di una variabile è disponibile a partire dalla fase install. Può essere aggiornato tra l'inizio della fase install e la fine della fase post_build. Al termine della fase post_build, il valore delle variabili esportate non può cambiare.

Nota

Non è possibile esportare quanto segue:

  • I segreti di Amazon EC2 Systems Manager Parameter Store specificati nel progetto di compilazione.

  • Segreti di Secrets Manager specificati nel progetto di compilazione

  • Variabili di ambiente che iniziano con AWS_.

env/git-credential-helper

Mappatura opzionale. Utilizzato per indicare se CodeBuild utilizza l'assistente credenziali Git per fornire le credenziali Git. yes se viene utilizzato. In caso contrario, no o non specificato. Per ulteriori informazioni, consulta gitcredentials sul sito Web Git.

Nota

git-credential-helper non è supportato per le compilazioni attivate da un webhook per un repository Git pubblico.

proxy

Sequenza opzionale. Utilizzato per rappresentare le impostazioni se esegui la compilazione in un server proxy esplicito. Per ulteriori informazioni, consulta Esecuzione di CodeBuild in un server proxy esplicito.

proxy/upload-artifacts

Mappatura opzionale. Imposta su yes se desideri che la compilazione in un server proxy esplicito carichi artefatti. Il valore predefinito è no.

proxy/logs

Mappatura opzionale. Imposta su yes per la compilazione in un server proxy esplicito per creare log CloudWatch. Il valore predefinito è no.

phases

Sequenza obbligatoria. Rappresenta i comandi eseguiti da CodeBuild in ogni fase della build.

Nota

Nella versione 0.1 di buildspec, CodeBuild esegue ogni comando in un'istanza separata della shell predefinita nell'ambiente di build Questo significa che ogni comando viene eseguito separatamente da tutti gli altri comandi. Pertanto, come impostazione predefinita, non è possibile eseguire un singolo comando che si basa sullo stato di qualsiasi comando precedente (per esempio, modificare le directory o impostare le variabili di ambiente). Per aggirare questo limite, suggeriamo di utilizzare la versione 0.2, che risolve questo problema. Se devi utilizzare la versione 0.1 di buildspec, ti consigliamo gli approcci indicati in Shell e comandi negli ambienti di compilazione.

phases/*/run-as

Sequenza opzionale. Viene utilizzato in una fase di compilazione per specificare un utente Linux che esegue i comandi. Se run-as è specificato anche a livello globale per tutti i comandi nella parte superiore del file buildspec, l'utente a livello di fase ha la priorità. Ad esempio, se globalmente run-as specifica User-1 e per la fase install solo una istruzione run-as specifica User-2, tutti i comandi nel file buildspec vengono eseguiti come User-1 eccetto i comandi nella fase install che vengono eseguiti come User-2.

fasi/*/in caso di guasto

Sequenza opzionale. Speciifica l'azione da intraprendere se si verifica un errore durante la fase. Può essere uno dei seguenti valori:

  • ABORT- Interrompi la compilazione.

  • CONTINUE- Passa alla fase successiva.

Se questa proprietà non è specificata, il processo di errore segue le fasi di transizione, come illustrato inTransizioni delle fasi della compilazione.

fasi/*/finalmente

Blocco opzionale. Comandi specificati in afinallyil blocco viene eseguito dopo i comandi incommandsbloccare. I comandi in unfinallyil blocco viene eseguito anche se è presente un comando incommandsil blocco fallisce. Ad esempio, se il blocco commands contiene tre comandi e il primo non va a buon fine, CodeBuild ignora i due comandi restanti ed esegue tutti i comandi nel blocco finally. La fase va a buon fine quando l'esecuzione di tutti i comandi nei blocchi commands e finally vengono completata. Se uno qualunque dei comandi nella fase non va a buon fine, la fase non va a buon fine:

I nomi delle fasi di build ammessi sono:

phases/install

Sequenza opzionale. Rappresenta i comandi eseguiti da CodeBuild, se presenti, durante l'installazione. Ti consigliamo di utilizzare la fase install solo per installare pacchetti nell'ambiente di build. Ad esempio, puoi utilizzare questa fase per installare un framework di test del codice come Mocha o RSpec.

phases/install/runtime-versions

Sequenza opzionale. Una versione runtime è supportata con l'immagine standard di Ubuntu 5.0 o successiva e l'immagine standard Amazon Linux 2 4.0 o successiva. Se specificata, almeno un runtime deve essere incluso in questa sezione. Specificate un runtime utilizzando una versione specifica, una versione principale seguita da.xper specificarloCodeBuildutilizza quella versione principale con la sua versione secondaria più recente, oppurelatestper utilizzare la versione principale e secondaria più recente (ad esempio,ruby: 3.2,nodejs: 18.x, oppurejava: latest). Puoi specificare il runtime utilizzando un numero o una variabile di ambiente. Ad esempio, se utilizzi l'immagine standard 4.0 di Amazon Linux 2, quanto segue specifica che è installata la versione 17 di Java, l'ultima versione secondaria di python versione 3 e una versione contenuta in una variabile di ambiente di Ruby. Per ulteriori informazioni, consulta Immagini Docker fornite da CodeBuild. 

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

È possibile specificare uno o più runtime nella sezione runtime-versions del file buildspec. Se il runtime dipende da un altro runtime, è anche possibile specificarne il runtime dipendente nel file buildspec. Se non si specifica alcun runtime nel file buildspec, CodeBuild scegliere i runtime predefiniti disponibili nell'immagine utilizzata. Se si specifica uno o più runtime, CodeBuild utilizza solo tali runtime. Se non viene specificato un runtime dipendente, CodeBuild tenta di scegliere il runtime dipendente per l'utente.

Se due runtime specificati sono in conflitto, la compilazione ha esito negativo. Ad esempio, android: 29 e java: openjdk11 sono in conflitto, perciò, se vengono specificati entrambi, la compilazione non riesce.

Per ulteriori informazioni sui runtime disponibili, consultaRuntime disponibili.

Nota

Se si specifica unruntime-versionsseziona e usa un'immagine diversa da Ubuntu Standard Image 2.0 o successiva o dall'immagine standard Amazon Linux 2 (AL2) 1.0 o successiva, la build emette l'avviso»Skipping install of runtimes. Runtime version selection is not supported by this build image».»

phases/install/commands

Sequenza opzionale. Contiene una sequenza di scalari, in cui ogni scalare rappresenta un singolo comando cheCodeBuildviene eseguito durante l'installazione. CodeBuildesegue ogni comando, uno alla volta, nell'ordine elencato, dall'inizio alla fine.

phases/pre_build

Sequenza opzionale. Rappresenta i comandi eseguiti da CodeBuild, se presenti, prima della build. Ad esempio, potresti utilizzare questa fase per accedere ad Amazon ECR o installare npm dependencies.

phases/pre_build/commands

Sequenza obbligatoria se viene specificato pre_build. Contiene una sequenza di scalari, in cui ogni scalare rappresenta un singolo comando cheCodeBuildviene eseguito prima della compilazione. CodeBuildesegue ogni comando, uno alla volta, nell'ordine elencato, dall'inizio alla fine.

phases/build

Sequenza opzionale. Rappresenta i comandi eseguiti da CodeBuild, se presenti, durante la build. Ad esempio, puoi utilizzare questa fase per eseguire Mocha, RSpec o sbt.

phases/build/commands

Obbligatorio sebuildè specificato. Contiene una sequenza di scalari, in cui ogni scalare rappresenta un singolo comando cheCodeBuildviene eseguito durante la compilazione. CodeBuildesegue ogni comando, uno alla volta, nell'ordine elencato, dall'inizio alla fine.

phases/post_build

Sequenza opzionale. Rappresenta i comandi eseguiti da CodeBuild, se presenti, dopo la build. Ad esempio, puoi usare Maven per impacchettare gli artefatti di compilazione in un file JAR o WAR oppure puoi inserire un'immagine Docker in Amazon ECR. Quindi puoi inviare una notifica di build tramite Amazon SNS.

phases/post_build/commands

Obbligatorio sepost_buildè specificato. Contiene una sequenza di scalari, in cui ogni scalare rappresenta un singolo comando cheCodeBuildviene eseguito dopo la compilazione. CodeBuildesegue ogni comando, uno alla volta, nell'ordine elencato, dall'inizio alla fine.

reports

report-group-name-or-arn

Sequenza opzionale. Specifica il gruppo di report a cui vengono inviati i report. Un progetto può annoverare al massimo cinque gruppi di report. Specificare l'ARN di un gruppo di report esistente o il nome di un nuovo gruppo di report. Se si specifica un nome, CodeBuild crea un gruppo di report utilizzando il nome del progetto e il nome specificato nel formato <project-name>-<report-group-name>. Per ulteriori informazioni, consulta Denominazione dei gruppi di report.

reports/<report-group>/files

Sequenza obbligatoria. Rappresenta le collocazioni dei dati grezzi afferenti ai risultati di test generati dal report. Contiene una sequenza di scalari, ognuno dei quali rappresenta una posizione diversa dove CodeBuild può trovare i file di test rispetto alla collocazione della compilazione originale o, se impostata, alla base-directory. Le posizioni possono includere quanto segue:

  • Un solo file (ad esempio my-test-report-file.json).

  • Un solo file in una sottodirectory (ad esempio my-subdirectory/my-test-report-file.json o my-parent-subdirectory/my-subdirectory/my-test-report-file.json).

  • '**/*' rappresenta tutti i file in modo ricorsivo.

  • my-subdirectory/* rappresenta tutti i file in una sottodirectory denominata my-subdirectory.

  • my-subdirectory/**/* rappresenta in modo ricorsivo tutti i file a partire da una sottodirectory denominata my-subdirectory.

reports/<report-group>/file-format

Mappatura opzionale. Rappresenta il formato del file di report. In assenza di specifica, viene utilizzato JUNITXML. Questo valore non fa distinzione tra maiuscole e minuscole. I valori possibili sono:

Rapporti sui test
CUCUMBERJSON

Cucumber JSON

JUNITXML

JUnit XML

NUNITXML

NUnit XML

NUNIT3XML

NUnit 3 XML

TESTNGXML

TestNG XML

VISUALSTUDIOTRX

Visual Studio TRX

Rapporti sulla copertura del codice
CLOVERXML

Clover XML

COBERTURAXML

Copertura XML

JACOCOXML

JaCoCoXML

SIMPLECOV

SimpleCovJSON

Nota

CodeBuildaccetta i report sulla copertura del codice JSON generati dasimplecov, nonsimplecov-json.

reports/<report-group>/base-directory

Mappatura opzionale. Rappresenta una o più directory di primo livello, relative alla posizione di compilazione originale, che CodeBuild utilizza per determinare dove trovare i file di test non elaborati.

reports/<report-group>/discard-paths

Facoltativo. Specifica se le directory dei file di report vengono appiattite nell'output. Se non è specificato o contiene no, i file di report vengono generati con la loro struttura di directory intatta. Se contiene yes, tutti i file di test vengono inseriti nella stessa directory di output. Ad esempio, se un percorso di un risultato del test è com/myapp/mytests/TestResult.xml, specificando yes questo file verrà posizionato in /TestResult.xml.

artefatti

Sequenza opzionale. Rappresenta le informazioni su dove CodeBuild può trovare l'output della build e su come CodeBuild lo prepara per il caricamento sul bucket di output S3. Questa sequenza non è necessaria se, ad esempio, stai creando e inviando un'immagine Docker ad Amazon ECR oppure esegui test unitari sul tuo codice sorgente, ma non lo compili.

Nota

I metadati di Amazon S3 hanno unCodeBuildintestazione denominatax-amz-meta-codebuild-buildarnche contiene ilbuildArndelCodeBuildbuild che pubblica artefatti su Amazon S3. LabuildArnviene aggiunto per consentire il tracciamento della fonte delle notifiche e per fare riferimento alla build da cui viene generato l'artefatto.

artifacts/files

Sequenza obbligatoria. Rappresenta le posizioni contenenti gli artefatti di output della build nell'ambiente della build. Contiene una sequenza di scalari, ognuno dei quali rappresenta una posizione diversa dove CodeBuild può trovare gli artefatti dell'output della build rispetto alla posizione della build originale o, se impostata, alla directory di base. Le posizioni possono includere quanto segue:

  • Un solo file (ad esempio my-file.jar).

  • Un solo file in una sottodirectory (ad esempio my-subdirectory/my-file.jar o my-parent-subdirectory/my-subdirectory/my-file.jar).

  • '**/*' rappresenta tutti i file in modo ricorsivo.

  • my-subdirectory/* rappresenta tutti i file in una sottodirectory denominata my-subdirectory.

  • my-subdirectory/**/* rappresenta in modo ricorsivo tutti i file a partire da una sottodirectory denominata my-subdirectory.

Quando specifichi le posizioni degli artefatti dell'output della build, CodeBuild può individuare la posizione della build originale nell'ambiente della build. Non occorre anteporre le posizioni dell'output dell'artefatto della build al percorso verso la posizione della build originale, né specificare ./ o valori simili. Se vuoi conoscere il percorso verso la posizione, puoi eseguire un comando come echo $CODEBUILD_SRC_DIR durante una build. La posizione di ciascun ambiente di build può essere leggermente diversa.

artifacts/name

Nome opzionale. Specifica un nome per l'artefatto della build. Questo nome si usa quando una delle seguenti affermazioni è vera.

  • Utilizzi l'API CodeBuild per creare le build e la flag overrideArtifactName è impostata sull'oggetto ProjectArtifacts quando un progetto è aggiornato o creato o quando una build viene avviata.

  • Puoi utilizzare la console CodeBuild per creare le build, un nome viene specificato nel file buildspec e selezionare Enable semantic versioning (Abilita funzione Versioni multiple semantica) quando crei o aggiorni un progetto. Per ulteriori informazioni, consulta Creare un progetto di compilazione (console).

Puoi specificare un nome nel file buildspec calcolato in fase di creazione. Il nome specificato nel file buildspec utilizza il linguaggio di comando Shell. Ad esempio, è possibile aggiungere una data e un'ora al nome dell'artefatto in modo che sia sempre univoco. I nomi di artefatto univoci impediscono che gli artefatti vengano sovrascritti. Per ulteriori informazioni, consulta Linguaggio di comando Shell.

  • Questo è un esempio di un nome di artefatto a cui viene aggiunta la data di creazione dell'artefatto. 

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

  • Questo è un esempio di nome di artefatto che utilizza una variabile di ambiente CodeBuild. Per ulteriori informazioni, consulta Variabili di ambiente degli ambienti di compilazione. 

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

  • Questo è un esempio di nome di artefatto che utilizza una variabile di ambiente CodeBuild e a cui viene aggiunta la data di creazione dell'artefatto. 

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

È possibile aggiungere informazioni sul percorso al nome in modo che gli artefatti denominati vengano inseriti nelle directory in base al percorso contenuto nel nome. In questo esempio, gli artefatti della build vengono inseriti nell'output sottobuilds/<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

Facoltativo. Specifica se le directory degli artefatti di build vengono appiattite nell'output. Se non è specificato, o contiene no, gli artefatti di build vengono generati con la loro struttura di directory intatta. Se contiene yes, tutti gli artefatti di build vengono inseriti nella stessa directory di output. Ad esempio, se un percorso di un file nell'artefatto di output della build è com/mycompany/app/HelloWorld.java, specificando yes il file verrà posizionato in /HelloWorld.java.

artifacts/base-directory

Mappatura opzionale. Rappresenta una o più directory di primo livello relative alla posizione della build originale, utilizzate da CodeBuild per determinare quali file e sottodirectory includere nell'artefatto dell'output della build. I valori validi includono:

  • Una sola directory di primo livello (ad esempio my-directory).

  • 'my-directory*' rappresenta tutte le directory di primo livello i cui nomi iniziano con my-directory.

Le directory di primo livello corrispondenti non sono incluse nell'artefatto dell'output della build, ma solo i file e le sottodirectory.

Puoi utilizzare files e discard-paths per limitare ulteriormente i file e le sottodirectory inclusi. Ad esempio, per la seguente struttura di directory: 

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

E per la seguente sequenza artifacts:

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

Nell'artefatto di output della build sarebbero compresi la seguente sottodirectory e il seguente file:

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

Mentre per la seguente sequenza artifacts:

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

Nell'artefatto di output della build sarebbero compresi i seguenti file:

.
├── my-file-1.txt
├── my-file-2.txt
└── my-file-3.txt
artefatti/percorsi di esclusione

Mappatura opzionale. Rappresenta uno o più percorsi, relativi abase-directory, quelloCodeBuildescluderà dalla build gli artefatti. L'asterisco (*) individua zero o più caratteri di un componente del nome entro i limiti della cartella. Un doppio asterisco (**) corrisponde a zero o più caratteri di un componente del nome in tutte le directory.

Di seguito sono riportati alcuni esempi di percorsi di esclusione:

  • Per escludere un file da tutte le directory:"**/file-name/**/*"

  • Per escludere tutte le cartelle dot:"**/.*/**/*"

  • Per escludere tutti i file dot:"**/.*"

Facoltativo. Se il tipo di output èZIP, specifica se i collegamenti simbolici interni vengono conservati nel file ZIP. Se questo contieneyes, tutti i collegamenti simbolici interni nel codice sorgente verranno conservati nel file ZIP degli artefatti.

artefatti/prefisso s3

Facoltativo. Speciifica un prefisso utilizzato quando gli artefatti vengono inviati a un bucket Amazon S3 e il tipo di namespace èBUILD_ID. Quando viene utilizzato, il percorso di uscita nel bucket è<s3-prefix>/<build-id>/<name>.zip.

artifacts/secondary-artifacts

Sequenza opzionale. Rappresenta una o più definizioni di artefatto come mappatura tra un identificatore dell'artefatto e una sua definizione. Ciascun identificatore di artefatto in questo blocco deve corrispondere a un artefatto definito nell'attributo secondaryArtifacts del progetto. Ogni diversa definizione presenta la stessa sintassi del blocco artifacts illustrato in precedenza.

Nota

Ilartifacts/filesla sequenza è sempre obbligatoria, anche quando sono definiti solo artefatti secondari.

Ad esempio, se un progetto presenta la seguente struttura:

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

Il buildspec avrà il seguente aspetto:

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

Sequenza opzionale. Rappresenta le informazioni su dove CodeBuild può preparare i file per caricare la cache su un bucket di cache S3. Questa sequenza non è obbligatoria se il tipo di cache del progetto è No Cache.

cache/paths

Sequenza obbligatoria. Rappresenta le posizioni della cache. Contiene una sequenza di scalari, ognuno dei quali rappresenta una posizione diversa dove CodeBuild può trovare gli artefatti dell'output della build rispetto alla posizione della build originale o, se impostata, alla directory di base. Le posizioni possono includere quanto segue:

  • Un solo file (ad esempio my-file.jar).

  • Un solo file in una sottodirectory (ad esempio my-subdirectory/my-file.jar o my-parent-subdirectory/my-subdirectory/my-file.jar).

  • '**/*' rappresenta tutti i file in modo ricorsivo.

  • my-subdirectory/* rappresenta tutti i file in una sottodirectory denominata my-subdirectory.

  • my-subdirectory/**/* rappresenta in modo ricorsivo tutti i file a partire da una sottodirectory denominata my-subdirectory.

Importante

Poiché una dichiarazione del file buildspec deve essere uno YAML valido, in una dichiarazione buildspec è importante la spaziatura. Se il numero di spazi nella dichiarazione buildspec non è valido, la build potrebbe non andare a buon fine immediatamente. È possibile usare un convalidatore YAML per verificare se le dichiarazioni buildspec sono YAML valide.

Se utilizzi la AWS CLI o i kit SDK AWS per dichiarare una buildspec quando crei o aggiorni un progetto di build, la specifica deve essere una sola stringa espressa in formato YAML, insieme allo spazio vuoto e ai caratteri di nuova riga. Un esempio è riportato nella sezione successiva.

Se utilizzi le console CodeBuild o AWS CodePipeline al posto di un file buildspec.yml, puoi inserire solo i comandi per la fase build. Invece di utilizzare la sintassi precedente, si elencano in una sola riga tutti i comandi da eseguire in fase di build. In caso di più comandi, separa ogni comando con && (ad esempio mvn test && mvn package).

Puoi utilizzare le console CodeBuild o CodePipeline al posto di un file buildspec.yml per specificare le posizioni degli artefatti di output della build nell'ambiente di build. Invece di utilizzare la sintassi precedente, si elencano in una sola riga tutte le posizioni. Per più posizioni, separarne ognuna con una virgola (per esempio, buildspec.yml, target/my-app.jar).

Esempio di buildspec

Ecco un esempio di file 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/**/*'

Ecco un esempio di buildspec precedente, espressa come stringa singola, da utilizzare con la AWS CLI o con i kit 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/**/*'"

Ecco un esempio dei comandi nella fase build da utilizzare con le console CodeBuild o CodePipeline.

echo Build started on `date` && mvn install

In questi esempi:

  • È impostata una variabile di ambiente personalizzata, in testo normale, con chiave JAVA_HOME e valore /usr/lib/jvm/java-8-openjdk-amd64.

  • Una variabile di ambiente personalizzata denominatadockerLoginPassworda cui si fa riferimento in Amazon EC2 Systems Manager Parameter Store in un secondo momento nei comandi di compilazione utilizzando la chiaveLOGIN_PASSWORD.

  • Non è possibile modificare questi nomi di fase della build. I comandi che vengono eseguiti in questo esempio sonoapt-get update -yeapt-get install -y maven(per installare Apache Maven),mvn install(per compilare, testare e impacchettare il codice sorgente in un elemento di output della build e installare l'elemento di output della build nel suo repository interno),docker login(per accedere a Docker con la password che corrisponde al valore della variabile di ambiente personalizzatadockerLoginPasswordimpostato in Amazon EC2 Systems Manager Parameter Store) e diversiechocomandi. I comandi echo sono qui inclusi per mostrare in che modo CodeBuild esegue i comandi e in quale ordine.

  • files rappresenta i file da caricare nella posizione dell'output della build. In questo esempio, CodeBuild carica il file singolo messageUtil-1.0.jar. Il file messageUtil-1.0.jar si trova nella relativa directory denominata target nell'ambiente di build. Poiché è specificato discard-paths: yes, messageUtil-1.0.jar viene caricato direttamente (non su una directory target intermedia). Il nome del file messageUtil-1.0.jar e il nome della relativa directory target sono basati sul modo in cui Apache Maven crea e archivia artefatti di output della build unicamente per questo esempio. Nei tuoi scenari, questi nomi di file e directory saranno differenti.

  • reports rappresenta due gruppi di report che generano report durante la compilazione:

    • arn:aws:codebuild:your-region:your-aws-account-id:report-group/report-group-name-1 specifica l'ARN di un gruppo di report. I risultati dei test generati dal framework di test si trovano nella directory target/tests/reports. Il formato dei file è JunitXml e il percorso non viene rimosso dai file contenenti i risultati dei test.

    • reportGroupCucumberJson specifica un nuovo gruppo di report. Se il nome del progetto è my-project, nel momento in cui si esegue una compilazione viene creato un gruppo di report denominato my-project-reportGroupCucumberJson. I risultati dei test generati dal framework di test si trovano in cucumber/target/cucumber-tests.xml. Il formato dei file di test è CucumberJson e il percorso non viene rimosso dai file contenenti i risultati dei test.

Versioni di buildspec

La seguente tabella elenca le versioni delle buildspec e le modifiche tra le versioni.

Versione Modifiche
0.2

  • environment_variables è stato rinominato in env.

  • plaintext è stato rinominato in variables.

  • La proprietà type per artifacts è obsoleta.

  • Nella versione 0.1, AWS CodeBuild esegue ogni comando di build in un'istanza separata della shell predefinita nell'ambiente di build. Nella versione 0.2, CodeBuild esegue tutti i comandi di build nella stessa istanza della shell predefinita nell'ambiente di build.
0.1 Questa è la definizione iniziale del formato della specifica di build.