Riferimento alle specifiche di costruzione 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 alle specifiche di costruzione per CodeBuild

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

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, puoi:

  • 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 del progetto di build. AWS Specificate il file buildspec usando its 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:

  • Esegui il update-project comando AWS CLI create-project or, impostando il buildspec valore sul percorso del file buildspec alternativo relativo al valore della variabile di ambiente incorporata. CODEBUILD_SRC_DIR È inoltre possibile eseguire l'equivalente con l'create projectoperazione in. AWS SDKs Per ulteriori informazioni, consulta Creazione di un progetto di compilazione o Modificare le impostazioni del progetto di costruzione.

  • Eseguite il AWS CLI start-build comando, impostando il buildspecOverride valore del percorso del file buildspec alternativo relativo al valore della variabile di ambiente incorporata. CODEBUILD_SRC_DIR È inoltre possibile eseguire l'equivalente con l'start buildoperazione in. AWS SDKs Per ulteriori informazioni, consulta Esegui le build manualmente.

  • In un AWS CloudFormation modello, imposta la BuildSpec proprietà di Source in una risorsa di tipo AWS::CodeBuild::Project sul percorso del file buildspec alternativo relativo al valore della variabile di ambiente incorporata. CODEBUILD_SRC_DIR Per ulteriori informazioni, consultate la BuildSpec proprietà nel codice sorgente del AWS CodeBuild progetto nella Guida per l'utente.AWS CloudFormation

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 daYAML, è necessario racchiudere il comando tra virgolette («»). Il comando seguente è racchiuso tra virgolette perché non è consentito inserire i due punti (:)) seguiti da uno spazio. 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
    
  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

Il file buildspec contiene quanto segue:

version

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, nei log sono nascoste le seguenti informazioni: CodeBuild

env/ shell

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 key/value scalari, in cui ogni mappatura rappresenta una singola variabile di ambiente personalizzata in testo semplice. key è il nome della variabile di ambiente personalizzata e value è il valore di quella variabile.

Importante

Sconsigliamo vivamente la memorizzazione di valori sensibili nelle variabili di ambiente. Le variabili di ambiente possono essere visualizzate in testo semplice utilizzando strumenti come la CodeBuild console e il 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

Obbligatorio se env è specificato e desideri recuperare variabili di ambiente personalizzate archiviate in Amazon EC2 Systems Manager Parameter Store. Contiene una mappatura di key/value scalari, in cui ogni mappatura rappresenta una singola variabile di ambiente personalizzata memorizzata in Amazon EC2 Systems Manager Parameter Store. key è il nome che utilizzerai più avanti nei comandi di build per fare riferimento a questa variabile di ambiente personalizzata, e value è il nome della variabile di ambiente personalizzata memorizzata in Amazon EC2 Systems Manager Parameter Store. Per memorizzare valori sensibili, consulta Systems Manager Parameter Store and Walkthrough: Create and test a String parameter (console) nella Amazon EC2 Systems Manager User Guide.

Importante

CodeBuild Per consentire il recupero di variabili di ambiente personalizzate archiviate in Amazon EC2 Systems Manager Parameter Store, devi aggiungere l'ssm:GetParametersazione al tuo ruolo CodeBuild di servizio. Per ulteriori informazioni, consulta Consentono CodeBuild di interagire con altri AWS servizi.

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 in. AWS Secrets Manager Specificate un Secrets Manager reference-key utilizzando 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 AWS account, specifica il segretoARN.

<json-key>

(Facoltativo) Specificate il nome della chiave della coppia chiave-valore di Secrets Manager di cui desiderate recuperare il valore. Se non si specifica ajson-key, CodeBuild recupera l'intero testo 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 per TestSecret è. MY_SECRET_VAR Si accede alla variabile durante la compilazione utilizzando il LOCAL_SECRET_VAR nome.

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 AWS CodePipeline a per esportare le variabili di ambiente dalla fase di compilazione corrente alle fasi successive della pipeline. Per ulteriori informazioni, consulta Lavorare con le variabili nella Guida per l'AWS CodePipeline 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 EC2 di Amazon Systems Manager Parameter Store specificati nel progetto di compilazione.

  • Secrets Manager: segreti specificati nel progetto di compilazione

  • Variabili di ambiente che iniziano con AWS_.

env/ git-credential-helper

Mappatura opzionale. Usato per indicare se CodeBuild utilizza il suo helper di credenziali Git per fornire le credenziali Git. yesse è usato. 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 Esegui 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 creazione di un server proxy esplicito per la creazione di CloudWatch registri. Il valore predefinito è no.

phases

Sequenza obbligatoria. Rappresenta i comandi CodeBuild eseguiti durante ogni fase della compilazione.

Nota

Nella versione 0.1 di buildspec, CodeBuild esegue ogni comando in un'istanza separata della shell predefinita nell'ambiente di compilazione. 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.

phases/*/ in caso di errore

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 illustrate inTransizioni delle fasi della compilazione.

fasi/*/ infine

Blocco opzionale. I comandi specificati in un finally blocco vengono eseguiti dopo i comandi nel blocco. commands I comandi in un finally blocco vengono eseguiti anche se un comando nel commands blocco ha esito negativo. Ad esempio, se il commands blocco contiene tre comandi e il primo ha esito negativo, CodeBuild ignora i due comandi rimanenti ed esegue tutti i comandi del finally blocco. 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 gli eventuali comandi che vengono CodeBuild eseguiti durante l'installazione. Ti consigliamo di utilizzare la fase install solo per installare pacchetti nell'ambiente di build. Ad esempio, è possibile utilizzare questa fase per installare un framework di test del codice come Mocha oRSpec.

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 .x da specificare che CodeBuild utilizza quella versione principale con la versione secondaria più recente o latest per utilizzare la versione principale e secondaria più recente (ad esempioruby: 3.2,nodejs: 18.x, ojava: latest). Puoi specificare il runtime utilizzando un numero o una variabile di ambiente. Ad esempio, se utilizzi l'immagine standard di Amazon Linux 2 4.0, 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 specifichi alcun runtime nel file buildspec, CodeBuild sceglie i runtime predefiniti disponibili nell'immagine che usi. Se specificate uno o più runtime, utilizza solo tali runtime. CodeBuild Se non viene specificato un runtime dipendente, CodeBuild tenta di scegliere automaticamente il runtime dipendente.

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, vedereRuntime disponibili.

Nota

Se specifichi una runtime-versions sezione e usi un'immagine diversa da Ubuntu Standard Image 2.0 o versione 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 che CodeBuild viene eseguito durante l'installazione. CodeBuild esegue ogni comando, uno alla volta, nell'ordine elencato, dall'inizio alla fine.

phases/pre_build

Sequenza opzionale. Rappresenta gli eventuali comandi CodeBuild eseguiti prima della compilazione. 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 che CodeBuild viene eseguito prima della compilazione. CodeBuildesegue ogni comando, uno alla volta, nell'ordine elencato, dall'inizio alla fine.

phases/build

Sequenza opzionale. Rappresenta gli eventuali comandi CodeBuild eseguiti durante la compilazione. Ad esempio, è possibile utilizzare questa fase per eseguire Mocha o RSpec sbt.

phases/build/commands

Obbligatorio se build specificato. Contiene una sequenza di scalari, in cui ogni scalare rappresenta un singolo comando che CodeBuild viene eseguito durante la compilazione. CodeBuild esegue ogni comando, uno alla volta, nell'ordine elencato, dall'inizio alla fine.

phases/post_build

Sequenza opzionale. Rappresenta gli eventuali comandi che vengono CodeBuild eseguiti dopo la compilazione. Ad esempio, potresti usare Maven per impacchettare gli artefatti di build in un WAR file JAR or oppure potresti inviare un'immagine Docker in Amazon. ECR Quindi puoi inviare una notifica di build tramite AmazonSNS.

phases/post_build/commands

Obbligatorio se post_build specificato. Contiene una sequenza di scalari, in cui ogni scalare rappresenta un singolo comando che CodeBuild viene eseguito dopo la compilazione. CodeBuild esegue 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 il nome ARN di un gruppo di report esistente o il nome di un nuovo gruppo di report. Se specificate un nome, CodeBuild crea un gruppo di report utilizzando il nome del progetto e il nome specificato nel formato<project-name>-<report-group-name>. Il nome del gruppo di report può anche essere impostato utilizzando una variabile di ambiente nel buildspec, ad esempio. $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, con ogni scalare che rappresenta una posizione separata in cui è CodeBuild possibile trovare i file di test, rispetto alla posizione di build originale o, se impostata, a. 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 tutti i file in modo ricorsivo 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

Cetriolo JSON

JUNITXML

JUnit XML

NUNITXML

NUnit XML

NUNIT3XML

NUnit3 XML

TESTNGXML

TestNG XML

VISUALSTUDIOTRX

Visual Studio TRX

Rapporti sulla copertura del codice
CLOVERXML

Trifoglio XML

COBERTURAXML

Cobertura XML

JACOCOXML

JaCoCo XML

SIMPLECOV

SimpleCov JSON

Nota

CodeBuild accetta report sulla copertura JSON del codice generati da simplecov, non da simplecov-json.

reports/<report-group>/base-directory

Mappatura opzionale. Rappresenta una o più directory di primo livello, relative alla posizione di build originale, che vengono CodeBuild utilizzate 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 informazioni su dove CodeBuild è possibile trovare l'output della build e su come CodeBuild prepararlo per il caricamento nel bucket di output S3. Questa sequenza non è necessaria se, ad esempio, stai creando e inviando un'immagine Docker ad Amazon ECR o stai eseguendo test unitari sul tuo codice sorgente, ma non lo stai creando.

Nota

I metadati di Amazon S3 hanno un' CodeBuild intestazione denominata x-amz-meta-codebuild-buildarn che contiene la CodeBuild build che pubblica gli buildArn artefatti su Amazon S3. buildArnViene aggiunto per consentire il tracciamento della fonte per le 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, ciascuno dei quali rappresenta una posizione separata in cui è CodeBuild possibile trovare gli artefatti di output della build, rispetto alla posizione di 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 tutti i file in modo ricorsivo a partire da una sottodirectory denominata my-subdirectory.

Quando specificate le posizioni degli artefatti di output della build, CodeBuild potete individuare la posizione di compilazione originale nell'ambiente di compilazione. 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.

  • Lo usi CodeBuild API per creare le tue build e il overrideArtifactName flag viene impostato sull'ProjectArtifactsoggetto quando un progetto viene aggiornato, creato un progetto o viene avviata una build.

  • Si utilizza la CodeBuild console per creare le build, viene specificato un nome nel file buildspec e si seleziona Abilita il controllo delle versioni semantiche quando si crea o si aggiorna 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 CodeBuild ambiente a cui è 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 sotto. builds/<build number>/my-artifacts

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

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 di compilazione originale, che CodeBuild vengono utilizzate per determinare quali file e sottodirectory includere nell'elemento di 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 a, che CodeBuild escluderanno gli base-directory artefatti della build. 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 contieneyes, tutti i collegamenti simbolici interni nel codice sorgente verranno conservati nel file degli artefatti. ZIP

artefatti/ prefisso s3

Facoltativo. Speciifica un prefisso utilizzato quando gli artefatti vengono emessi in un bucket Amazon S3 e il tipo di namespace è. BUILD_ID Quando viene utilizzato, il percorso di output 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

La artifacts/filessequenza è 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 informazioni su dove CodeBuild è possibile preparare i file per il caricamento della cache in 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, ciascuno dei quali rappresenta una posizione separata in cui CodeBuild trovare gli artefatti di output della build, rispetto alla posizione di 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 tutti i file in modo ricorsivo a partire da una sottodirectory denominata my-subdirectory.

Importante

Poiché una dichiarazione buildspec deve essere validaYAML, la spaziatura in una dichiarazione buildspec è importante. Se il numero di spazi nella dichiarazione buildspec non è valido, la build potrebbe non andare a buon fine immediatamente. Puoi usare un YAML validatore per verificare se le tue dichiarazioni buildspec sono valide. YAML

Se si utilizza il AWS CLI, or the AWS SDKs per dichiarare un buildspec quando si crea o si aggiorna un progetto di build, il buildspec deve essere una singola stringa espressa nel formato, insieme agli spazi bianchi e ai caratteri di escape di nuova riga richiesti. YAML Un esempio è riportato nella sezione successiva.

Se utilizzate le AWS CodePipeline console CodeBuild or invece di un file buildspec.yml, potete inserire comandi solo 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 usare CodeBuild or CodePipeline consoles invece di un file buildspec.yml per specificare le posizioni degli artefatti di output della build nell'ambiente di compilazione. 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 del precedente buildspec, espresso come una singola stringa, da utilizzare con o. AWS CLI 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/**/*'"

Ecco un esempio dei comandi della build fase, da utilizzare con le console or. CodeBuild 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 denominata dockerLoginPassword you memorizzata in Amazon EC2 Systems Manager Parameter Store viene referenziata più avanti nei comandi di compilazione utilizzando la chiaveLOGIN_PASSWORD.

  • Non è possibile modificare questi nomi di fase della build. I comandi eseguiti in questo esempio sono apt-get update -y and apt-get install -y maven (per installare Apache Maven), mvn install (per compilare, testare e impacchettare il codice sorgente in un elemento di output di compilazione 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 personalizzata impostata in dockerLoginPassword Amazon Systems Manager EC2 Parameter Store) e diversi comandi. echo I echo comandi sono inclusi qui per mostrare come vengono CodeBuild eseguiti i comandi e l'ordine in cui vengono eseguiti.

  • files rappresenta i file da caricare nella posizione dell'output della build. In questo esempio, CodeBuild carica il singolo filemessageUtil-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-1specifica il tipo 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 compilazione in un'istanza separata della shell predefinita nell'ambiente di compilazione. Nella versione 0.2, CodeBuild esegue tutti i comandi di compilazione nella stessa istanza della shell predefinita nell'ambiente di compilazione.
0.1 Questa è la definizione iniziale del formato della specifica di build.