Crie a referência de especificação para o CodeBuild - AWS CodeBuild
Nome do arquivo buildspec e local de armazenamentoSintaxe de buildspecExemplo de buildspecVersões de buildspec

Crie a referência de especificação para o CodeBuild

Este tópico fornece informações de referência importantes sobre os arquivos de especificação de compilação (buildspec). buildspec é uma coleção de comandos de compilação e configurações relacionadas, no formato YAML, que o CodeBuild usa para executar uma compilação. É possível incluir um buildspec como parte do código-fonte ou defini-lo ao criar um projeto de compilação. Para obter informações sobre como uma build spec funciona, consulte Como o CodeBuild funciona.

Tópicos

Nome do arquivo buildspec e local de armazenamento

Se você incluir uma especificação de compilação como parte do código-fonte, por padrão, o arquivo buildspec deverá se chamar buildspec.yml e ser colocado na raiz do diretório de origem.

É possível substituir o nome e o local do arquivo buildspec padrão. Por exemplo, é possível:

  • Use um arquivo buildspec diferente para compilações diferentes no mesmo repositório, como buildspec_debug.yml e buildspec_release.yml.

  • Armazene um arquivo buildspec em um local que não seja a raiz de seu diretório de origem, como config/buildspec.yml, ou em um bucket do S3. O bucket do S3 deve estar na mesma região da AWS que seu projeto de compilação. Especifique o arquivo buildspec usando seu ARN (por exemplo, arn:aws:s3:::<my-codebuild-sample2>/buildspec.yml).

É possível especificar somente uma buildspec para um projeto de compilação, independentemente do nome do arquivo buildspec.

Para substituir o nome do arquivo buildspec padrão, o local ou ambos, faça o seguinte:

  • Execute o comando AWS CLI ou create-project da update-project definindo o valor buildspec como caminho para o arquivo buildspec alternativo em relação ao valor da variável de ambiente interna CODEBUILD_SRC_DIR. Você também pode fazer o equivalente com a operação create project nos SDKs da AWS. Para ter mais informações, consulte Criar um projeto de compilação ou Alterar as configurações do projeto de compilação.

  • Execute o comando AWS CLI da start-build definindo o valor buildspecOverride como caminho para o arquivo buildspec alternativo em relação ao valor da variável de ambiente interna CODEBUILD_SRC_DIR. Você também pode fazer o equivalente com a operação start build nos SDKs da AWS. Para obter mais informações, consulte Executar compilações manualmente.

  • Em um modelo do AWS CloudFormation, defina a propriedade do BuildSpec de Source em um recurso do tipo AWS::CodeBuild::Project como caminho para o arquivo buildspec alternativo em relação ao valor da variável de ambiente interna CODEBUILD_SRC_DIR. Para obter mais informações, consulte a propriedade BuildSpec em AWS CodeBuild project source no Guia do usuário do AWS CloudFormation.

Sintaxe de buildspec

Os arquivos buildspec devem ser expressos no formato YAML.

Se um comando contiver um caractere ou uma string de caracteres que não seja compatível com o YAML, coloque o comando entre aspas (“”). O comando a seguir está entre aspas porque um dois pontos (:) seguido por um espaço não é permitido no YAML. As aspas no comando são escapadas (\“).

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

A buildspec possui a seguinte sintaxe:

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:
  # build-fanout:
        
phases:
  install:
    run-as: Linux-user-name
    on-failure: ABORT | CONTINUE | RETRY | RETRY-count | RETRY-regex | RETRY-count-regex
    runtime-versions:
      runtime: version
      runtime: version
    commands:
      - command
      - command
    finally:
      - command
      - command
    
  pre_build:
    run-as: Linux-user-name
    on-failure: ABORT | CONTINUE | RETRY | RETRY-count | RETRY-regex | RETRY-count-regex
    commands:
      - command
      - command
    finally:
      - command
      - command
    
  build:
    run-as: Linux-user-name
    on-failure: ABORT | CONTINUE | RETRY | RETRY-count | RETRY-regex | RETRY-count-regex
    commands:
      - command
      - command
    finally:
      - command
      - command
    
  post_build:
    run-as: Linux-user-name
    on-failure: ABORT | CONTINUE | RETRY | RETRY-count | RETRY-regex | RETRY-count-regex
    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:
  key: key
  fallback-keys:
    - fallback-key
    - fallback-key
  action: restore | save
  paths:
    - path
    - path

A buildspec contém o seguinte:

version

Mapeamento necessário. Representa a versão de buildspec. Recomendamos usar o 0.2.

nota

Embora a versão 0.1 ainda tenha suporte, recomendamos que você use a versão 0.2 sempre que possível. Para obter mais informações, consulte Versões de buildspec.

run-as

Sequência opcional. Disponível somente para usuários do Linux. Especifica um usuário do Linux que executa comandos nesse arquivo buildspec. O run-as concede ao usuário especificado permissões de leitura e execução. Quando você especificar run-as na parte superior do arquivo buildspec globalmente, ele se aplicará a todos os comandos. Se não quiser especificar um arquivo buildspec para todos os comandos, você pode especificar um para comandos em uma fase usando run-as em um dos blocos phases. Se run-as não for especificado, todos os comandos serão executados como raiz.

env

Sequência opcional. Representa informações para uma ou mais variáveis de ambiente personalizadas.

nota

Para proteger informações confidenciais, os seguintes itens ficam ocultos nos logs do CodeBuild:

env/shell

Sequência opcional. Especifica o shell compatível com os sistemas operacionais Linux ou Windows.

Para sistemas operacionais Linux, as tags de shell compatíveis são:

  • bash

  • /bin/sh

Para sistemas operacionais Windows, as tags de shell compatíveis são:

  • powershell.exe

  • cmd.exe

env/variables

Necessário caso env seja especificado e você queira definir variáveis de ambiente personalizadas em texto sem formatação. Contém um mapeamento de escalares de chave/valor em que cada mapeamento representa uma única variável de ambiente personalizada em texto simples. chave é o nome da variável de ambiente personalizada, e valor é o valor da variável.

Importante

Não recomendamos o armazenamento de valores confidenciais em variáveis de ambiente. As variáveis de ambiente podem ser exibidas em texto sem formatação com ferramentas, como o console do CodeBuild e a AWS CLI. Para valores confidenciais, recomendamos usar o mapeamento parameter-store ou secrets-manager, conforme descrito posteriormente nesta seção.

Qualquer variável de ambiente definida por você substituem variáveis de ambiente existentes. Por exemplo, se a imagem de Docker já contiver uma variável de ambiente chamada MY_VAR com um valor de my_value e você definir uma variável de ambiente chamada MY_VAR com um valor de other_value, my_value será substituído por other_value. Da mesma maneira, se a imagem de Docker já contiver uma variável de ambiente chamada PATH com um valor de /usr/local/sbin:/usr/local/bin e você definir uma variável de ambiente chamada PATH com um valor de $PATH:/usr/share/ant/bin, /usr/local/sbin:/usr/local/bin será substituído pelo valor literal $PATH:/usr/share/ant/bin.

Não defina nenhuma variável de ambiente com um nome que comece com CODEBUILD_. Este prefixo está reservado para uso interno.

Se uma variável de ambiente com o mesmo nome é definida em vários locais, o valor será determinado como se segue:

env/parameter-store

Necessário caso env seja especificado e você queira recuperar variáveis de ambiente personalizadas armazenadas no Amazon EC2 Systems Manager Parameter Store. Contém um mapeamento de escalares key/value, em que cada mapeamento representa uma única variável de ambiente personalizada armazenada no Amazon EC2 Systems Manager Parameter Store. key é o nome que você usa posteriormente nos comandos de compilação para fazer referência a essa variável de ambiente personalizada, e value é o nome da variável de ambiente personalizada armazenada no Amazon EC2 Systems Manager Parameter Store. Para armazenar valores confidenciais, consulte Systems Manager Parameter Store e Walkthrough: Create and test a String parameter (console) no Guia do usuário do Amazon EC2 Systems Manager.

Importante

Para permitir que o CodeBuild recupere variáveis de ambiente personalizadas armazenadas no Amazon EC2 Systems Manager Parameter Store, é necessário adicionar a ação ssm:GetParameters ao perfil de serviço do CodeBuild. Para obter mais informações, consulte Permitir que o CodeBuild interaja com outros serviços da AWS.

Todas as variáveis de ambiente recuperadas do Amazon EC2 Systems Manager Parameter Store substituirão as variáveis de ambiente existentes. Por exemplo, se a imagem de Docker já contiver uma variável de ambiente chamada MY_VAR com um valor de my_value e você recuperar uma variável de ambiente chamada MY_VAR com um valor de other_value, my_value será substituído por other_value. Da mesma maneira, se a imagem de Docker já contiver uma variável de ambiente chamada PATH com um valor de /usr/local/sbin:/usr/local/bin e você recuperar uma variável de ambiente chamada PATH com um valor de $PATH:/usr/share/ant/bin, /usr/local/sbin:/usr/local/bin será substituído pelo valor literal $PATH:/usr/share/ant/bin.

Não armazene nenhuma variável de ambiente com um nome que comece com CODEBUILD_. Este prefixo está reservado para uso interno.

Se uma variável de ambiente com o mesmo nome é definida em vários locais, o valor será determinado como se segue:

env/secrets-manager

Necessário caso você queira recuperar variáveis de ambiente personalizadas armazenadas no AWS Secrets Manager. Especifique uma reference-key do Secrets Manager usando o seguinte padrão:

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

<key>

(Obrigatório) O nome da variável de ambiente local. Use esse nome para acessar a variável durante a compilação.

<secret-id>

(Obrigatório) O nome ou o nome do recurso da Amazon (ARN) que serve como identificador exclusivo para o segredo. Para acessar um segredo em sua conta da AWS, basta especificar o nome secreto. Para acessar um segredo em uma conta da AWS diferente, especifique o ARN secreto.

<json-key>

(Opcional) Especifica o nome da chave do par de chave-valor cujo valor você deseja recuperar. Se você não especificar um json-key, o CodeBuild recuperará todo o texto do segredo.

<version-stage>

(Opcional) Especifica a versão do segredo que você deseja recuperar pelo rótulo temporário anexado à versão. Rótulos temporários são usados para acompanhar diferentes versões durante o processo de rodízio. Se você usar version-stage, não especifique version-id. Se você não especificar um estágio de versão ou um ID de versão, o padrão será recuperar a versão com o valor do estágio de versão de AWSCURRENT.

<version-id>

(Opcional) Especifica o identificador exclusivo da versão do segredo que você deseja usar. Se você especificar version-id, não especifique version-stage. Se você não especificar um estágio de versão ou um ID de versão, o padrão será recuperar a versão com o valor do estágio de versão de AWSCURRENT.

No exemplo a seguir, TestSecret é o nome do par chave-valor armazenado no Secrets Manager. A chave para TestSecret é MY_SECRET_VAR. Você acessa a variável durante a compilação usando o nome LOCAL_SECRET_VAR.

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

Para obter mais informações, consulte O que é o AWS Secrets Manager no Guia do usuário do AWS Secrets Manager.

env/exported-variables

Mapeamento opcional. Usado para listar as variáveis de ambiente que você deseja exportar. Especifique o nome de cada variável que você deseja exportar em uma linha separada em exported-variables. A variável que você deseja exportar deve estar disponível no contêiner durante a compilação. A variável exportada pode ser uma variável de ambiente.

As variáveis de ambiente exportadas são usadas em conjunto com o AWS CodePipeline para exportar variáveis de ambiente do estágio de compilação atual para os estágios subsequentes no pipeline. Para obter mais informações, consulte Working with variables no Guia do usuário do AWS CodePipeline.

Durante uma compilação, o valor de uma variável está disponível a partir da fase install. Ele pode ser atualizado entre o início da fase install e o final da fase post_build. Após o término da fase post_build, o valor de variáveis exportadas não pode ser alterado.

nota

Não é possível exportar o seguinte:

  • Os segredos do Amazon EC2 Systems Manager Parameter Store especificados no projeto de compilação.

  • Segredos do Secrets Manager especificados no projeto de compilação

  • Variáveis de ambiente que começam com AWS_.

env/git-credential-helper

Mapeamento opcional. Usado para indicar se o CodeBuild usa o auxiliar de credenciais do Git para fornecer credenciais do Git. yes se ele for usado. Caso contrário, no ou não especificado. Para obter mais informações, consulte gitcredentials no site do Git.

nota

git-credential-helperO não é compatível com compilações acionadas por um webhook para um repositório Git público.

proxy

Sequência opcional. Usado para representar configurações se você executar a compilação em um servidor de proxy explícito. Para obter mais informações, consulte Executar o CodeBuild em um servidor de proxy explícito.

proxy/upload-artifacts

Mapeamento opcional. Defina como yes se você quiser que a compilação em um servidor de proxy explícito faça upload de artefatos. O padrão é “”. no.

proxy/logs

Mapeamento opcional. Defina como yes para a compilação em um servidor de proxy explícito para criar logs do CloudWatch. O padrão é “”. no.

phases

Sequência necessária. Representa os comandos que o CodeBuild executa durante cada fase da compilação.

nota

No buildspec versão 0.1, o CodeBuild executa cada comando em uma instância à parte do shell padrão no ambiente de compilação. Isso significa que cada comando é executado isoladamente em relação aos outros comandos. Portanto, por padrão, não é possível executar um comando que dependa do estado de algum comando anterior (por exemplo, mudança de diretórios ou configuração de variáveis de ambiente). Para resolver essa limitação, recomendamos usar a versão 0.2, que resolve o problema. Caso seja necessário usar a buildspec versão 0.1 por algum motivo, recomendamos as abordagens em Shells e comandos em ambientes de compilação.

phases/*/run-as

Sequência opcional. Use em uma fase de compilação para especificar um usuário do Linux que executa seus comandos. Se run-as também for especificado globalmente para todos os comandos na parte superior do arquivo buildspec, o usuário em nível de fase terá precedência. Por exemplo, se run-as especificar globalmente User-1 e, para a fase install apenas uma instrução run-as especificar User-2, todos os comandos no arquivo buildspec serão executados como User-1, exceto os comandos na fase install, que serão executados como User-2.

phases/*/on-failure

Sequência opcional. Especifica a ação a ser realizada se ocorrer uma falha durante a fase. Pode ter um dos valores a seguir:

  • ABORT: anule a compilação.

  • CONTINUE: vá para a próxima fase.

  • RETRY: tentar novamente a compilação até três vezes com uma mensagem de erro que corresponda à expressão regular .*.

  • RETRY-count: tentar novamente a compilação por um número especificado de vezes, conforme representado pela contagem com uma mensagem de erro que corresponde à expressão regular .*. A contagem deve estar entre 0 e 100. Por exemplo, os valores válidos incluem RETRY-4 e RETRY-8.

  • RETRY-regex: tentar novamente a compilação até três vezes e usar regex para incluir uma expressão regular que corresponda a uma mensagem de erro especificada. Por exemplo, os valores válidos incluem Retry-.*Error: Unable to connect to database.* e RETRY-invalid+.

  • RETRY-count-regex: tentar novamente a compilação por determinado número de vezes, conforme representado pela contagem. A contagem deve estar entre 0 e 100. Você também pode usar regex para incluir uma expressão regular que corresponda à mensagem de erro. Por exemplo, os valores válidos incluem Retry-3-.*connection timed out.* e RETRY-8-invalid+.

Se essa propriedade não for especificada, o processo de falha seguirá as fases de transição, conforme mostrado em Transições de fase de compilação.

Importante

O atributo on-failure não é compatível ao usar a computação do Lambda ou a capacidade reservada. Esse atributo só funciona com imagens de computação do EC2 fornecidas pelo CodeBuild.

phases/*/finally

Bloco opcional. Os comandos especificados em um bloco finally são executados após os comandos no bloco commands. Os comandos em um bloco finally são executados mesmo quando um comando no bloco commands falha. Por exemplo, se o bloco commands contiver três comandos e o primeiro falhar, o CodeBuild ignorará os dois comandos restantes e executará os comandos no bloco finally. A fase é bem-sucedida quando todos os comandos nos blocos commands e finally são executados com êxito. Se algum comando em uma fase falhar, a fase falhará.

Os nomes permitidos para as fases de build são:

phases/install

Sequência opcional. Representa os eventuais comandos que o CodeBuild executa durante a instalação. Recomendamos que você use a fase install somente para pacotes de instalação no ambiente de compilação. Por exemplo, você pode usar essa fase para instalar um framework de teste de código como o Mocha ou o RSpec.

phases/install/runtime-versions

Sequência opcional. Uma versão do runtime é compatível com a imagem padrão 5.0 do Ubuntu ou posterior e a imagem padrão 4.0 ou posterior do Amazon Linux 2. Se especificado, pelo menos um tempo de execução deve ser incluído nessa seção. Especifique um runtime usando uma versão específica, uma versão principal seguida de .x para especificar que o CodeBuild usa essa versão principal com a versão secundária mais recente ou latest para usar a versão principal e a secundária mais recente (por exemplo ruby: 3.2, nodejs: 18.x ou java: latest). Você pode especificar o tempo de execução usando um número ou uma variável de ambiente. Por exemplo, se você usar a imagem padrão 4.0 do Amazon Linux 2, o seguinte especificará que a versão 17 do Java, a versão secundária mais recente do python versão 3 e uma versão contida em uma variável de ambiente do Ruby sejam instaladas. Para obter mais informações, consulte Imagens do Docker fornecidas pelo CodeBuild. 

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

Você pode especificar um ou mais runtimes na seção runtime-versions do arquivo buildspec. Se o runtime depender de outro runtime, você também poderá especificar seu runtime dependente no arquivo buildspec. Se você não especificar nenhum runtime no arquivo buildspec, o CodeBuild escolherá os runtimes padrão disponíveis na imagem usada. Se você especificar um ou mais runtimes, o CodeBuild usará somente esses runtimes. Se um runtime dependente não for especificado, o CodeBuild tentará escolher o runtime dependente para você.

Se dois tempos de execução especificados entrarem em conflito, ocorrerá uma falha na compilação. Por exemplo, há um conflito entre android: 29 e java: openjdk11, portanto, se ambos forem especificados, ocorrerá uma falha na compilação.

Para obter mais informações sobre runtimes disponíveis, consulte Runtimes disponíveis.

nota

Se você especificar uma seção runtime-versions e usar uma imagem diferente do Ubuntu Standard Image 2.0 ou posterior, ou da imagem padrão do Amazon Linux 2 (AL2) 1.0 ou posterior, a compilação emitirá o aviso "Skipping install of runtimes. Runtime version selection is not supported by this build image”.

phases/install/commands

Sequência opcional. Contém uma sequência de escalares, na qual cada escalar representa um único comando que o CodeBuild executa durante a instalação. O CodeBuild executa cada comando individualmente, na ordem indicada, do início ao fim.

phases/pre_build

Sequência opcional. Representa os eventuais comandos que o CodeBuild executa antes da compilação. Por exemplo, você poderia usar essa fase para fazer login no Amazon ECR ou instalar dependências npm.

phases/pre_build/commands

Sequência necessária, se pre_build for especificado. Contém uma sequência de escalares, na qual cada escalar representa um único comando que o CodeBuild executa antes da compilação. O CodeBuild executa cada comando individualmente, na ordem indicada, do início ao fim.

phases/build

Sequência opcional. Representa os eventuais comandos que o CodeBuild executa durante a compilação. Por exemplo, você pode usar essa fase para executar o Mocha, o RSpec ou o sbt.

phases/build/commands

Necessário, se build for especificado. Contém uma sequência de escalares, na qual cada escalar representa um único comando que o CodeBuild executa durante a compilação. O CodeBuild executa cada comando individualmente, na ordem indicada, do início ao fim.

phases/post_build

Sequência opcional. Representa os eventuais comandos que o CodeBuild executa após a compilação. Por exemplo, é possível usar o Maven para empacotar os artefatos de compilação em um arquivo JAR ou WAR, ou enviar uma imagem do Docker ao Amazon ECR. Depois, é possível enviar uma notificação de compilação pelo Amazon SNS.

phases/post_build/commands

Necessário, se post_build for especificado. Contém uma sequência de escalares, na qual cada escalar representa um único comando que o CodeBuild executa depois da compilação. O CodeBuild executa cada comando individualmente, na ordem indicada, do início ao fim.

relatórios

report-group-name-or-arn

Sequência opcional. Especifica o grupo de relatórios para o qual os relatórios são enviados. Um projeto pode ter, no máximo, cinco grupos de relatórios. Especifique o ARN de um grupo de relatórios existente ou o nome de um novo grupo de relatórios. Se você especificar um nome, o CodeBuild criará um grupo de relatórios usando o nome do projeto e o nome especificado no formato <project-name>-<report-group-name>. O nome do grupo de relatórios também pode ser definido usando uma variável de ambiente no buildspec, como $REPORT_GROUP_NAME. Para obter mais informações, consulte Nomenclatura do grupo de relatórios.

reports/<report-group>/files

Sequência necessária. Representa os locais que contêm os dados brutos dos resultados do teste gerados pelo relatório. Contém uma sequência de escalares, com cada escalar representando um local separado onde o CodeBuild pode encontrar arquivos de teste, relativos ao local original de compilação ou, se definido, o base-directory. Os locais podem ser os seguintes:

  • Um único arquivo (por exemplo, my-test-report-file.json).

  • Um único arquivo em um subdiretório (por exemplo, my-subdirectory/my-test-report-file.json ou my-parent-subdirectory/my-subdirectory/my-test-report-file.json).

  • '**/*' representa todos os arquivos recursivamente.

  • my-subdirectory/* representa todos os arquivos em um subdiretório denominado my-subdirectory.

  • my-subdirectory/**/* representa todos os arquivos que se iniciam recursivamente em um subdiretório denominado my-subdirectory.

reports/<report-group>/file-format

Mapeamento opcional. Representa o formato do arquivo do relatório. Se não especificado, JUNITXML será usado. Esse valor não diferencia letras maiúsculas de minúsculas. Os valores possíveis são:

Relatórios de teste
CUCUMBERJSON

Cucumber JSON

JUNITXML

JUnit XML

NUNITXML

NUnit XML

NUNIT3XML

NUnit 3 XML

TESTNGXML

TestNG XML

VISUALSTUDIOTRX

Visual Studio TRX

Relatórios de cobertura de código
CLOVERXML

Clover XML

COBERTURAXML

Cobertura XML

JACOCOXML

JaCoCo XML

SIMPLECOV

SimpleCov JSON

nota

O CodeBuild aceita relatórios de cobertura de código JSON gerados pelo simplecov, não pelo simplecov-json.

reports/<report-group>/base-directory

Mapeamento opcional. Representa um ou mais diretórios de nível superior, relativos ao local de compilação original, que o CodeBuild usa para determinar onde localizar os arquivos de teste brutos.

reports/<report-group>/discard-paths

Opcional. Especifica se os diretórios de arquivos de relatório são nivelados na saída. Se isso não for especificado, ou contiver no, os arquivos de relatório serão exibidos com sua estrutura de diretório intacta. Se contiver yes, todos os arquivos de teste serão colocados no mesmo diretório de saída. Por exemplo, se um caminho para um resultado de teste for com/myapp/mytests/TestResult.xml, especificar yes colocará esse arquivo em /TestResult.xml.

Artefatos

Sequência opcional. Representa as informações sobre onde o CodeBuild pode encontrar a saída da compilação e como o CodeBuild a prepara para fazer upload no bucket de saída do S3. Essa sequência não será necessária se, por exemplo, você estiver compilando e enviando uma imagem do Docker ao Amazon ECR, ou se estiver executando testes de unidade no código-fonte, porém não o compilando.

nota

Os metadados do Amazon S3 têm um cabeçalho do CodeBuild denominado x-amz-meta-codebuild-buildarn que contém o buildArn da compilação do CodeBuild que publica artefatos no Amazon S3. O buildArn é adicionado para permitir o rastreamento da fonte para notificações e para referenciar de qual compilação o artefato é gerado.

artifacts/files

Sequência necessária. Representa os locais que contêm os artefatos de saída da compilação, no ambiente de compilação. Contém uma sequência de escalares, com cada escalar representando um local à parte onde o CodeBuild pode encontrar artefatos de saída de compilação, relativos ao local de compilação original ou, caso definido, o diretório base. Os locais podem ser os seguintes:

  • Um único arquivo (por exemplo, my-file.jar).

  • Um único arquivo em um subdiretório (por exemplo, my-subdirectory/my-file.jar ou my-parent-subdirectory/my-subdirectory/my-file.jar).

  • '**/*' representa todos os arquivos recursivamente.

  • my-subdirectory/* representa todos os arquivos em um subdiretório denominado my-subdirectory.

  • my-subdirectory/**/* representa todos os arquivos que se iniciam recursivamente em um subdiretório denominado my-subdirectory.

Quando você especifica locais de artefatos de saída de compilação, o CodeBuild pode encontrar o local de compilação original no ambiente de compilação. Não é preciso preceder os locais de saída do artefato de build com o caminho do local de build original, ou especificar ./ ou similar. Se quiser saber o caminho para esse local, você pode executar um comando como echo $CODEBUILD_SRC_DIR, durante um build. O local para cada ambiente de build poderia ser um pouco diferente.

artifacts/name

Nome opcional. Especifica um nome para o artefato de compilação. Esse nome é usado quando ocorre uma das seguintes situações.

  • Use a API do CodeBuild para criar as compilações, e o sinalizador overrideArtifactName é definido no objeto ProjectArtifacts quando um projeto é atualizado, um projeto é criado ou uma compilação é iniciada.

  • Use o console do CodeBuild para criar as compilações, um nome é especificado no arquivo buildspec e selecione Habilitar o versionamento de versões ao criar ou atualizar um projeto. Para obter mais informações, consulte Criar um projeto de compilação (console).

É possível especificar um nome no arquivo buildspec que é calculado no momento da compilação. O nome especificado em um arquivo buildspec usa a linguagem de comandos do Shell. Por exemplo, você pode anexar uma data e hora ao nome do artefato para que ele seja sempre exclusivo. Os nomes de artefato exclusivos impedem que os artefatos sejam substituídos. Para obter mais informações, consulte Shell command language.

  • Este é um exemplo de um nome de artefato anexado com a data em que o artefato é criado. 

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

  • Este é um exemplo de nome de artefato que usa uma variável de ambiente do CodeBuild. Para obter mais informações, consulte Variáveis de ambiente em ambientes de compilação. 

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

  • Este é um exemplo de nome de artefato que usa uma variável de ambiente do CodeBuild com a data de criação do artefato anexada a ele. 

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

É possível adicionar informações de caminho ao nome para que os artefatos nomeados sejam colocados em diretórios com base no caminho no nome. Neste exemplo, artefatos de compilação são colocados na saída abaixo de builds/<build number>/my-artifacts.

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

Opcional. Especifica se os diretórios de artefatos de compilação são nivelados na saída. Se isso não for especificado, ou contiver no, os artefatos de compilação serão exibidos com sua estrutura de diretório intacta. Se contiver yes, todos os artefatos de compilação serão colocados no mesmo diretório de saída. Por exemplo, se um caminho para um arquivo no artefato de saída da compilação for com/mycompany/app/HelloWorld.java, especificar yes colocará esse arquivo em /HelloWorld.java.

artifacts/base-directory

Mapeamento opcional. Representa um ou mais diretórios de nível superior, relativos ao local de compilação original, que o CodeBuild utiliza para determinar quais arquivos e subdiretórios serão incluídos no artefato de saída de compilação. Os valores válidos são:

  • Um único diretório de nível superior (por exemplo, my-directory).

  • 'my-directory*' representa todos os diretórios de nível superior com nomes iniciados com my-directory.

Diretórios de nível superior correspondentes não estão incluídos no artefato de saída de build, somente seus arquivos e subdiretórios.

Você pode usar files e discard-paths para restringir que arquivos e subdiretórios serão incluídos. Por exemplo, para a seguinte estrutura de diretório: 

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

E para a seguinte sequência artifacts:

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

Os seguintes subdiretório e arquivo seriam incluídos no artefato de saída de build:

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

Enquanto para a seguinte sequência artifacts:

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

Os seguintes arquivos seriam incluídos no artefato de saída de build:

.
├── my-file-1.txt
├── my-file-2.txt
└── my-file-3.txt
artifacts/exclude-paths

Mapeamento opcional. Representa um ou mais caminhos, em relação ao base-directory, que o CodeBuild excluirá dos artefatos de compilação. O caractere de asterisco (*) corresponde a zero ou mais caracteres de um componente de nome sem cruzar limites da pasta. Um asterisco duplo (**) corresponde a zero ou mais caracteres de um componente de nome em todos os diretórios.

São exemplos de exclude-paths:

  • Para excluir um arquivo de todos os diretórios: "**/file-name/**/*"

  • Para excluir todas as pastas de pontos: "**/.*/**/*"

  • Para excluir todos os arquivos de pontos: "**/.*"

Opcional. Caso o tipo de saída seja ZIP, especifica se os links simbólicos internos são preservados no arquivo ZIP. Se contiver yes, todos os links simbólicos internos na origem serão preservados no arquivo ZIP dos artefatos.

artifacts/s3-prefix

Opcional. Especifica um prefixo usado quando os artefatos são enviados a um bucket do Amazon S3 e o tipo de namespace é BUILD_ID. Quando usado, o caminho de saída no bucket é <s3-prefix>/<build-id>/<name>.zip.

artifacts/secondary-artifacts

Sequência opcional. Representa uma ou mais definições de artefato como um mapeamento entre um identificador e uma definição de artefato. Cada identificador de artefato deste bloco deve corresponder a um artefato definido no atributo secondaryArtifacts do seu projeto. Cada definição separada tem a mesma sintaxe que o bloco artifacts acima.

nota

A sequência artifacts/files é sempre necessária, mesmo quando há somente artefatos secundários definidos.

Por exemplo, se o projeto tem a seguinte estrutura:

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

O arquivo buildspec se parece ao seguinte:

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

Sequência opcional. Representa informações sobre onde o CodeBuild pode preparar os arquivos para fazer upload do cache em um bucket de cache do S3. Essa sequência não será necessária se o tipo de cache do projeto for No Cache.

cache/chave

Sequência opcional. Representa a chave primária usada ao pesquisar ou restaurar um cache. O CodeBuild faz uma correspondência exata para a chave primária.

Veja um exemplo da chave:

key: npm-key-$(codebuild-hash-files package-lock.json) }
cache/chaves de reserva

Sequência opcional. Representa uma lista de chaves de reserva usadas sequencialmente quando um cache não pode ser encontrado usando a chave primária. Até cinco chaves de reserva são compatíveis, e cada uma é combinada usando uma pesquisa de prefixo. Essa sequência será ignorada se a chave não for fornecida.

Veja um exemplo de chaves de reserva:

fallback-keys:
    - npm-key-$(codebuild-hash-files package-lock.json) }
    - npm-key-
    - npm-
cache/ação

Sequência opcional. Especifica a ação a ser executada no cache. Os valores válidos são:

  • restore, que só restaura o cache sem salvar as atualizações.

  • save, que só salva o cache sem restaurar uma versão anterior.

Se nenhum valor for fornecido, o CodeBuild realizará tanto a restauração como o salvamento por padrão.

cache/paths

Sequência necessária. Representa os locais do cache. Contém uma sequência de escalares, com cada escalar representando um local à parte onde o CodeBuild pode encontrar artefatos de saída de compilação, relativos ao local de compilação original ou, caso definido, o diretório base. Os locais podem ser os seguintes:

  • Um único arquivo (por exemplo, my-file.jar).

  • Um único arquivo em um subdiretório (por exemplo, my-subdirectory/my-file.jar ou my-parent-subdirectory/my-subdirectory/my-file.jar).

  • '**/*' representa todos os arquivos recursivamente.

  • my-subdirectory/* representa todos os arquivos em um subdiretório denominado my-subdirectory.

  • my-subdirectory/**/* representa todos os arquivos que se iniciam recursivamente em um subdiretório denominado my-subdirectory.

Importante

Como a declaração de buildspec deve corresponder ao YAML, o espaçamento na declaração de buildspec é importante. Se o número de espaços em sua declaração de buildspec for inválido, poderá haver falhas nas compilações imediatamente. É possível usar um validador YAML para testar se as declarações de buildspec são válidas conforme o YAML.

Se você usar a AWS CLI ou os AWS SDKs para declarar uma buildspec ao criar ou atualizar um projeto de compilação, a buildspec deverá ser uma única string expressada em formato YAML com caracteres de escape de nova linha e espaço em branco obrigatórios. Há um exemplo na próxima seção.

Se você usa os consoles do CodeBuild ou do AWS CodePipeline em vez de um arquivo buildspec.yml, é possível inserir comandos somente para a fase build. Em vez de usar a sintaxe anterior, você lista, em uma única linha, todos os comandos que deseja executar durante a fase de compilação. Para vários comandos, separe-os com && (por exemplo, mvn test && mvn package).

É possível usar os consoles do CodeBuild ou do CodePipeline em vez de um arquivo buildspec.yml para especificar os locais dos artefatos de saída da compilação, no ambiente de compilação. Em vez de usar a sintaxe anterior, você lista, uma única linha, todos os locais. Para vários locais, separe-os com uma vírgula (por exemplo, buildspec.yml, target/my-app.jar).

Exemplo de buildspec

Eis um exemplo de arquivo 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/**/*'

Veja a seguir um exemplo da buildspec anterior, expressa como uma única string, a ser usada com a AWS CLI ou os 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/**/*'"

Veja um exemplo dos comandos na fase build para uso com os consoles do CodeBuild ou do CodePipeline.

echo Build started on `date` && mvn install

Nestes exemplos:

  • É definida uma variável de ambiente personalizada, em texto simples, com a chave de JAVA_HOME e o valor de /usr/lib/jvm/java-8-openjdk-amd64.

  • Uma variável de ambiente personalizada chamada dockerLoginPassword armazenada no Amazon EC2 Systems Manager Parameter Store é referenciada posteriormente em comandos de compilação usando a chave LOGIN_PASSWORD.

  • Não é possível alterar os nomes da fase de build. Os comandos executados neste exemplo são apt-get update -y e apt-get install -y maven (para instalar o Apache Maven), mvn install (para compilar, testar e empacotar o código-fonte em um artefato de saída de compilação e para instalar o artefato de saída de compilação no repositório interno), docker login (para fazer login no Docker com a senha correspondente ao valor da variável de ambiente personalizada dockerLoginPassword definida no Amazon EC2 Systems Manager Parameter Store) e diversos comandos echo. Os comandos echo são incluídos aqui para mostrar como o CodeBuild executa comandos e em que ordem.

  • files representa os arquivos para upload para o local de saída do build. Neste exemplo, o CodeBuild faz upload do arquivo único messageUtil-1.0.jar. O arquivo messageUtil-1.0.jar pode ser encontrado no diretório relativo denominado target, no ambiente de build. Como discard-paths: yes está especificado, messageUtil-1.0.jar é carregado diretamente (e não em um diretório target intermediário). O nome de arquivo messageUtil-1.0.jar e o nome do diretório relativo do target são baseados na maneira como o Apache Maven cria e armazena os artefatos de saída de build somente para este exemplo. Em seus próprios cenários, esses nomes de arquivos e diretórios serão diferentes.

  • reports representa dois grupos de relatórios que geram relatórios durante a compilação:

    • arn:aws:codebuild:your-region:your-aws-account-id:report-group/report-group-name-1 especifica o ARN de um grupo de relatórios. Os resultados do teste gerados pela estrutura de teste estão no diretório target/tests/reports. O formato de arquivo é JunitXml e o caminho não é removido dos arquivos que contêm resultados de teste.

    • reportGroupCucumberJson especifica um novo grupo de relatórios. Se o nome do projeto for my-project, um grupo de relatórios com o nome my-project-reportGroupCucumberJson será criado quando uma compilação for executada. Os resultados do teste gerados pela estrutura de teste estão em cucumber/target/cucumber-tests.xml. O formato do arquivo de teste é CucumberJson e o caminho é removido dos arquivos que contêm resultados de teste.

Versões de buildspec

A tabela a seguir lista as versões de buildspec e as alterações entre versões.

Versão Alterações
0.2

  • environment_variables foi renomeado para env.

  • plaintext foi renomeado para variables.

  • A propriedade type do artifacts foi desativada.

  • Na versão 0.1, o AWS CodeBuild executa cada comando de compilação em uma instância à parte do shell padrão no ambiente de compilação. Na versão 0.2, o CodeBuild executa todos os comandos de compilação na mesma instância do shell padrão no ambiente de compilação.
0.1 Esta é a definição inicial do formato de especificação da compilação.