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

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Referência de especificação de construção para CodeBuild

Este tópico fornece informações de referência importantes sobre os arquivos de especificação de compilação (buildspec). Um buildspec é uma coleção de comandos de compilação e configurações relacionadas, no formato YAML, CodeBuild usados 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 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 AWS região do 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 update-project comando AWS CLI create-project or, definindo o buildspec valor do caminho para o arquivo buildspec alternativo em relação ao valor da variável de ambiente integrada. CODEBUILD_SRC_DIR Você também pode fazer o equivalente com a create project operação no AWS SDKs. Para ter mais informações, consulte Criar um projeto de compilação ou Alterar as configurações do projeto de compilação.

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

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

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, o seguinte está oculto nos CodeBuild registros:

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 dekey/valuescalars, em que cada mapeamento representa uma única variável de ambiente personalizada em texto simples. keyé o nome da variável de ambiente personalizada e value é o valor dessa 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 simples usando ferramentas como o CodeBuild console e AWS CLI o. 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 da .

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

Obrigatório se env for especificado e você quiser recuperar variáveis de ambiente personalizadas armazenadas no Amazon EC2 Systems Manager Parameter Store. Contém um mapeamento dekey/valuescalars, 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 em seus comandos de compilação para se referir 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 and Walkthrough: Crie e teste um parâmetro de string (console) no Guia do usuário do Amazon EC2 Systems Manager.

Importante

CodeBuild Para permitir a recuperação de variáveis de ambiente personalizadas armazenadas no Amazon EC2 Systems Manager Parameter Store, você deve adicionar a ssm:GetParameters ação à sua função CodeBuild de serviço. Para obter mais informações, consulte CodeBuild Permitir interagir com outros AWS serviços.

Todas as variáveis de ambiente recuperadas do Amazon EC2 Systems Manager Parameter Store substituem 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 da .

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

Obrigatório se você quiser recuperar variáveis de ambiente personalizadas armazenadas em 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 AWS conta 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 umjson-key, CodeBuild recuperará todo o texto secreto.

<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 AWS CodePipeline a exportação de variáveis de ambiente do estágio de construçã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:

  • Amazon EC2 Systems Manager Parameter Armazene segredos especificados no projeto de construção.

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

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

ambiente/ git-credential-helper

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

nota

O git-credential-helper 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 Execute CodeBuild em um servidor 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 sua construção em um servidor proxy explícito para criar CloudWatch registros. O padrão é no.

phases

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

nota

Na versão 0.1 do buildspec, CodeBuild executa cada comando em uma instância separada 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- Tente novamente a compilação até 3 vezes com uma mensagem de erro que corresponda à expressão .* regular.

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

  • RETRY-regex- Tente novamente a compilação até 3 vezes e use 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.* RETRY-invalid+ e.

  • RETRY-count-regex- Repita a compilação por um determinado número de vezes, conforme representado porcount. Observe que count 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.* RETRY-8-invalid+ e.

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 on-failure atributo não é suportado ao usar a computação Lambda ou a capacidade reservada. Esse atributo só funciona com imagens EC2 computacionais 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 commands bloco contiver três comandos e o primeiro falhar, CodeBuild pulará os dois comandos restantes e executará qualquer comando no finally bloco. 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 comandos, se houver, que são CodeBuild executados 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 uma estrutura de teste de código, como Mocha ou 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 tempo de execução usando uma versão específica, uma versão principal seguida de .x para especificar que CodeBuild usa essa versão principal com sua versão secundária mais recente ou latest para usar a versão principal e secundária mais recente (por exemplo,ruby: 3.2,nodejs: 18.x, oujava: 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 por 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 tempo de execução no arquivo buildspec, CodeBuild escolhe os tempos de execução padrão que estão disponíveis na imagem que você usa. Se você especificar um ou mais tempos de execução, CodeBuild usará somente esses tempos de execução. Se um tempo de execução dependente não for especificado, CodeBuild tentará escolher o tempo de execução 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 runtime-versions seção 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, em que cada escalar representa um único comando CodeBuild executado durante a instalação. CodeBuild executa cada comando, um por vez, na ordem listada, do início ao fim.

phases/pre_build

Sequência opcional. Representa os comandos, se houver, que são CodeBuild executados 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, em que cada escalar representa um único comando CodeBuild executado antes da compilação. CodeBuildexecuta cada comando, um por vez, na ordem listada, do início ao fim.

phases/build

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

phases/build/commands

Necessário, se build for especificado. Contém uma sequência de escalares, em que cada escalar representa um único comando CodeBuild executado durante a construção. CodeBuild executa cada comando, um por vez, na ordem listada, do início ao fim.

phases/post_build

Sequência opcional. Representa os comandos, se houver, que são CodeBuild executados 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, em que cada escalar representa um único comando CodeBuild executado após a compilação. CodeBuild executa cada comando, um por vez, na ordem listada, do início ao fim.

relatórios

report-group-name-or-celeiro

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, CodeBuild cria um grupo de relatórios usando o nome do seu 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 CodeBuild pode encontrar arquivos de teste, em relação ao local de construção original 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 chamadomy-subdirectory.

  • my-subdirectory/**/*representa todos os arquivos recursivamente a partir de um subdiretório chamado. 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

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, em relação ao local de compilação original, CodeBuild usados para determinar onde encontrar 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 informações sobre onde é CodeBuild possível encontrar a saída da compilação e como ela é CodeBuild preparada para ser carregada 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 CodeBuild cabeçalho chamado x-amz-meta-codebuild-buildarn que contém o buildArn da CodeBuild compilação 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 chamadomy-subdirectory.

  • my-subdirectory/**/*representa todos os arquivos recursivamente a partir de um subdiretório chamado. my-subdirectory

Quando você especifica os locais dos artefatos de saída de compilação, CodeBuild pode localizar o local de construção original no ambiente de construçã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.

  • Você usa a CodeBuild API para criar suas compilações e a overrideArtifactName sinalização é definida no ProjectArtifacts objeto quando um projeto é atualizado, um projeto é criado ou uma construção é iniciada.

  • Você usa o CodeBuild console para criar suas compilações, um nome é especificado no arquivo buildspec e você seleciona Ativar controle de versão semântico 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)

  • Esse é um exemplo de nome de artefato que usa uma variável de CodeBuild ambiente. 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

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

    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, em relação ao local da compilação original, CodeBuild usados para determinar quais arquivos e subdiretórios incluir no artefato de saída da 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 abase-directory, que CodeBuild serão excluídos dos artefatos de construçã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 é CodeBuild possível preparar os arquivos para carregar o 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. CodeBuild faz uma correspondência exata para a chave primária.

Aqui está um exemplo da chave:

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

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

Aqui está um exemplo para as teclas de fallback:

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:

  • restoreque só restaura o cache sem salvar as atualizações.

  • saveque só salva o cache sem restaurar uma versão anterior.

Se nenhum valor for fornecido, o CodeBuild padrão é executar a restauração e o salvamento.

cache/paths

Sequência necessária. Representa os locais do cache. Contém uma sequência de escalares, com cada escalar representando um local separado onde é CodeBuild possível encontrar artefatos de saída de compilação, relativos ao local de construção original ou, se definido, ao 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 chamadomy-subdirectory.

  • my-subdirectory/**/*representa todos os arquivos recursivamente a partir de um subdiretório chamado. 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 o AWS CLI, ou o AWS SDKs para declarar um buildspec ao criar ou atualizar um projeto de compilação, o buildspec deverá ser uma única string expressa no formato YAML, junto com os espaços em branco necessários e os caracteres de escape de nova linha. Há um exemplo na próxima seção.

Se você usar os AWS CodePipeline consoles CodeBuild ou em vez de um arquivo buildspec.yml, poderá 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).

Você pode usar os CodePipeline consoles CodeBuild ou 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/**/*'

Aqui está um exemplo do buildspec anterior, expresso como uma única string, para uso com o AWS CLI ou o. 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/**/*'"

Aqui está um exemplo dos comandos na build fase, para uso com os CodePipeline consoles CodeBuild ou.

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 você armazenada no Amazon EC2 Systems Manager Parameter Store é referenciada posteriormente nos comandos de criação usando a chaveLOGIN_PASSWORD.

  • Não é possível alterar os nomes da fase de build. Os comandos que são 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 instalar o artefato de saída de compilação em seu repositório interno), docker login (para entrar no Docker com a senha que corresponde ao valor da variável de ambiente personalizada que você definiu no dockerLoginPassword Amazon EC2 Systems Manager Parameter Store) e vários comandos. echo Os echo comandos estão incluídos aqui para mostrar como os comandos são CodeBuild executados e a ordem em que são executados.

  • files representa os arquivos para upload para o local de saída do build. Neste exemplo, CodeBuild carrega o arquivo messageUtil-1.0.jar único. 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, AWS CodeBuild executa cada comando de compilação em uma instância separada do shell padrão no ambiente de compilação. Na versão 0.2, 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.