Especificação de Build

A especificação de build contém as etapas e definições de build que o pipeline de build usa para executar um build.

A especificação de build é criada em YAML. Por padrão, a especificação de build é localizada na raiz do diretório de origem do build principal e é usada quando você executa um pipeline de build. O arquivo é nomeado como build_spec.yml ou build_spec.yaml. Se a especificação de build não estiver presente no diretório raiz, forneça um caminho relativo do arquivo ao adicionar o estágio de Build Gerenciado.

A especificação de build é organizada nas seguintes seções:

Configuração do executor do build.
Configuração das variáveis de ambiente.
Artefatos de entrada.
Etapas a serem executadas em sequência.
Artefatos de saída.

Sintaxe de Especificação de Build

version: 0.1
component: build
timeoutInSeconds: 10000
shell: bash
failImmediatelyOnError: true
env:
  variables:
    key: "value"
    key: "value"
  vaultVariables:
    key: "secret-id"
  exportedVariables:
    - variable
    - variable
    - variable

inputArtifacts:
  - name: artifact-name
    type: GENERIC_ARTIFACT
    artifactId: "artifact-ocid"
    registryId: OCID of the Artifact Registry
    path: path of the artifact in the Registry
    version: version of the artifact
    location: target-location
  - name: artifact-name
    type: STAGE_ARTIFACT
    location: target-location
  - name: artifact-name
    type: URL
    url: downloadable link
    location: target-location

steps:
  - type: Command
    name: step-name
    shell: shellType
    timeoutInSeconds: 650
    failImmediatelyOnError: true
    command: command
    onFailure:
      - type: Command
        command: |
          command
          command
        timeoutInSeconds: 400

  - type: Command
    name: step-name
    command: |
      command
      command
      command
    onFailure:
      - type: Command
        command: |
          command
        timeoutInSeconds: 400

outputArtifacts:
  - name: artifact-name
    type: artifact-type
    location: source-location

Observação

sudo não está disponível no host do executor de build. Se você precisar de permissões de superusuário, execute sua etapa de build como usuário raiz.

Parâmetros de Especificação de Build

Veja a seguir os parâmetros de especificação de build e seus detalhes:


Parâmetro	Descrição
`version`	Obrigatório. Indica a versão da especificação de build. Uma versão ausente ou inválida causa falha no estágio de Build. O valor suportado é `0.1`.
`component`	Obrigatório. Indica um componente específico no DevOps. Um valor ausente ou inválido causa falha no build. O valor suportado é `build`.
`timeoutInSeconds`	Opcional. Especifica o timeout para todo o arquivo de especificação de build. Cada 'etapa' também pode ter seu próprio valor de timeout. Se um valor não for especificado, o valor padrão de 8 horas será usado. O valor máximo permitido é 8 horas.
`shell`	Opcional. Especifica o shell a ser usado no nível global da especificação de build. O valor pode ser substituído no nível da 'etapa'. Os valores permitidos são `/bin/sh` e `bash`. Se não for especificado, o valor padrão `bash` será usado.
`failImmediatelyOnError`	Opcional. Especifica se o build deve continuar se qualquer comando na etapa falhar com um valor de saída diferente de zero. Se não for especificado, o valor padrão será `false` e a etapa continuará. Os valores permitidos são `true` e `false`. O OCI recomenda definir o valor desse atributo como `true`.
`env`	Opcional. Você pode definir variáveis personalizadas. Há suporte para três tipos de variáveis: env/variáveis: Opcional. A chave deve ser compatível com variáveis de ambiente de string e POSIX. O valor pode ser qualquer string. O escopo dessa variável é a execução do arquivo de especificação de build. Qualquer alteração no valor da variável estará visível nas etapas subsequentes. Essas variáveis estão disponíveis como variáveis de ambiente para todas as etapas do arquivo de especificação de build. Se o valor da variável tiver um caractere de nova linha (\n) ou de retorno de transporte (\r), ele será substituído por espaço nas etapas subsequentes. env/vaultVariables: Opcional. A chave deve ser compatível com variáveis de ambiente de string e POSIX. O valor deve ser um OCID do segredo do vault. O vault e o pipeline de build devem ser da mesma tenancy. A tenancy deve ter uma política apropriada para permitir que recursos do pipeline de build acessem o segredo. O escopo dessa variável é a execução do arquivo de especificação de build e está disponível para todas as etapas do arquivo. O valor dessas variáveis é recuperado do vault e disponibilizado como variáveis de ambiente para todas as etapas do arquivo de especificação de build. env/exportedVariables: Opcional. Uma lista de variáveis pode ser declarada aqui. O nome da variável deve ser compatível com uma variável de ambiente de string e POSIX. O valor pode ser designado em qualquer etapa dentro do arquivo de especificação de build. O escopo desta variável é o pipeline de build. Qualquer variável exportada está disponível nos estágios subsequentes do mesmo pipeline.
`inputArtifacts`	Opcional. Usado para definir uma lista de artefatos de entrada que são necessários para executar o estágio de Build atual. Oferece suporte aos seguintes tipos de artefatos de entrada: Artefatos de qualquer um dos estágios anteriores do build. Artefatos de qualquer URL HTTP externo para download. Artefatos genéricos do Artifact Registry. Os parâmetros são os seguintes: *inputArtifacts//url: Opcional. O URL HTTP externo para download do artefato de entrada deve ser informado. O URL deve estar disponível publicamente. No momento, não há suporte para a autenticação/autorização. inputArtifacts//name: Obrigatório. Se o URL não estiver presente, esse nome será usado para procurar os artefatos produzidos pelos estágios anteriores do Build no mesmo pipeline. Portanto, outputArtifacts/name e inputArtifacts/name devem corresponder para consumir um artefato específico produzido pelo estágio anterior do Build no pipeline. inputArtifacts//location: obrigatório. Um caminho de destino do sistema de arquivos local no qual o artefato de entrada precisa ser baixado. O caminho pode ser especificado em um destes métodos: `${OCI_PRIMARY_SOURCE_DIR}/pom.xml` `${OCI_WORKSPACE_DIR}/[source-name]/pom.xml` `/workspace/[source-name]/pom.xml` Caminho relativo do home do projeto, `pom.xml` Com qualquer um dos valores, é feito download do artefato de entrada para o diretório home de origem principal com um nome de arquivo, `pom.xml`. O local não suporta `exportedVariables` ou variáveis de pipeline. inputArtifacts//type: Obrigatório. O tipo do artefato de entrada que deve ser submetido a download. Os valores permitidos são `URL`, `STAGE_ARTIFACT` e `GENERIC_ARTIFACT`. inputArtifacts//artifactld: Obrigatório. O OCID do artefato. Se você tiver fornecido o OCID, o pipeline de build ignorará o registryId, o caminho e a versão. inputArtifacts//registryld: Obrigatório. O OCID do Artifact Registry. inputArtifacts//path: Obrigatório. O caminho de destino do artefato. inputArtifacts//version: Obrigatório. A versão do artefato. Observação:* Para o tipo `GENERIC_ARTIFACT` de artefato de entrada, você pode fornecer como um parâmetro obrigatório o OCID do artefato ou uma combinação de ID do registro, caminho e versão do artefato.
`steps`	Obrigatório. Esta seção define uma lista de etapas que precisam ser executadas. *steps/type: Obrigatório. Especifica o tipo da etapa. Suporta os seguintes valores: `Command` e `VulnerabilityAudit`. Para obter mais informações, consulte Tipos de Etapa. steps//name*: Opcional. Um nome amigável para a etapa.
`outputArtifacts`	Opcional. Especifica os artefatos produzidos pelo estágio de Build. Os artefatos produzidos como saída nesta seção são salvos durante a execução do build atual. Eles podem ser usados nos estágios subsequentes no pipeline de build. *outputArtifacts//name: Obrigatório. O nome pode conter letras minúsculas (a-z), letras maiúsculas (A-Z), sublinhado (_) e hifens (-). O nome é o identificador exclusivo do artefato de saída. Nos estágios posteriores do pipeline de build, o nome é usado para identificar um artefato. outputArtifacts//type: Obrigatório. Os valores permitidos são `BINARY` e `DOCKER_IMAGE`. BINARY: Especifica arquivos binários como artefatos de saída. outputArtifacts//location: Um caminho de origem do sistema de arquivos local no qual o artefato de saída pode ser encontrado. O caminho pode ser especificado em um destes métodos (suponha que o arquivo `pom.xml` esteja presente no diretório home de origem principal): `${OCI_PRIMARY_SOURCE_DIR}/pom.xml` `${OCI_WORKSPACE_DIR}/[source-name]/pom.xml` `/workspace/[source-name]/pom.xml` Caminho relativo do home do projeto, `pom.xml` Se o arquivo não for encontrado no local informado, o estágio de Build falhará. DOCKER_IMAGE: Especifica uma imagem do Docker como artefato de saída. outputArtifacts//location*: Uma tag de imagem do Docker criada em uma das etapas no arquivo de especificação do build. Por exemplo, se em qualquer uma das etapas do arquivo de especificação do build, uma imagem do Docker for criada como `docker build -t iad.ocir.io/id204we8d65n/hello-world:1.0`, o campo de local deverá conter `iad.ocir.io/id204we8d65n/hello-world:1.0` para produzir esse artefato. A imagem deve ser criada ou extraída, e disponibilizada em uma das etapas de especificação do build. Caso contrário, a etapa `outputArtifact` falhará e com isso o estágio do Build também falhará. O local não suporta `exportedVariables` ou variáveis de pipeline.

Tipos de Etapa

Comando


Nome do atributo	Descrição
`command`	Há suporte para comandos de linha única e de várias linhas. Todos os comandos especificados em uma etapa são executados na mesma sessão de shell. Com base no valor `steps/*/shell`, os comandos podem ser shell ou bash. A falha rápida não está ativada. Para que a etapa seja bem-sucedida, a saída do último comando em uma etapa é considerada. Se o último código de saída do comando for 0, a etapa será considerada como bem-sucedida.
`timeoutInSeconds` (Opcional)	Especifica o timeout da etapa. Se não for informado, o valor será herdado do parâmetro `timeoutInSeconds` global. O valor máximo permitido é 8 horas.
`shell` (Opcional)	Especifica o tipo de shell da etapa atual. Se não for especificado, o valor será herdado do parâmetro `shell` global. Os valores permitidos são `/bin/sh` e `shell`.
`onFailure` (Opcional)	Uma lista de etapas que devem ser executadas em caso de falha na saída normal do estágio de build. Execute se a etapa correspondente falhar e, após a execução, a especificação de build for encerrada. O tratamento da falha não afeta o status do estágio do build. Se qualquer uma das etapas falhar, o status do estágio de build permanecerá `failed`, embora seja tratado usando o bloco `onFailure`.
`failImmediatelyOnError` (Opcional)	Especifica se o build deve continuar se qualquer comando na etapa falhar com um valor de saída diferente de zero. Se não for especificado, o valor padrão será `false` e a etapa continuará. Os valores permitidos são `true` e `false`. O OCI recomenda definir o valor desse atributo como `true`. O valor do atributo `failImmediatelyOnError` definido em `steps` tem precedência sobre o mesmo valor de atributo definido fora de `steps`.

Auditoria de Vulnerabilidade

Uma auditoria de vulnerabilidade descreve as vulnerabilidades do aplicativo e suas dependências. Quando você executa um build usando o serviço DevOps do OCI, pode iniciar uma verificação de código para obter um novo commit no repositório de código. A auditoria de vulnerabilidade acontece no estágio de Build Gerenciado.

No arquivo de especificação de build, uma etapa de auditoria de vulnerabilidade do tipo VulnerabilityAudit é adicionada, que o pipeline de build do DevOps usa durante a execução de build para verificação de código. Os atributos desta etapa são listados da seguinte forma:


Nome do atributo	Descrição	Suporte de valor parametrizado
`name` (Opcional)	Nome da etapa.	N/D
`vulnerabilityAuditName` (Opcional)	Nome do recurso de auditoria de vulnerabilidade.	Sim
`vulnerabilityAuditCompartmentId` (Opcional) O padrão é `knowledgeBaseCompartmentId`	OCID do compartimento no qual o recurso de auditoria precisa ser criado.	Sim
`knowledgeBaseId` (Obrigatório)	OCID do placeholder/tag para manter detalhes do recurso de auditoria de vulnerabilidade. Recurso principal do recurso de auditoria de vulnerabilidade.	Sim
`configuration/buildType` (Obrigatório)	Tipo de ferramenta de build.	N/D
`configuration/pomFilePath` (Obrigatório)	Localização do arquivo pom.xml.	Sim
`configuration/packagesToIgnore` (Opcional)	Lista de pacotes Java a serem ignorados ao calcular o resultado da verificação ao fazer a auditoria de vulnerabilidade.	N/D
`configuration/maxPermissibleCvssV2Score` (Opcional) O padrão é 0.0	Pontuação máxima no CVSS v2, permitida para auditoria de vulnerabilidade. Tudo o que estiver acima dessa configuração deverá marcar o build como `Failed`.	N/D
`configuration/maxPermissibleCvssV3Score` (Opcional) O padrão é 0.0	Pontuação máxima no CVSS v3, permitida para auditoria de vulnerabilidade. Tudo o que estiver acima dessa configuração deverá marcar o build como `Failed`.	N/D
`freeFormTags` (Opcional)	Aceita o par chave/valor.	N/D

Variáveis Predefinidas do Sistema

O DevOps fornece um conjunto de variáveis de sistema predefinidas com valores padrão que você pode usar, como variáveis de ambiente na especificação do build.


Variável	Descrição
`OCI_STAGE_ID`	O OCID do estágio atual.
`OCI_PIPELINE_ID`	O OCID do pipeline de build atual.
`OCI_BUILD_RUN_ID`	O OCID da execução do build atual.
`OCI_TRIGGER_COMMIT_HASH`	Hash de confirmação do trigger atual.
`OCI_TRIGGER_SOURCE_BRANCH_NAME`	Ramificação que aciona o build.
`OCI_TRIGGER_SOURCE_URL`	URL do repositório que acionou o build
`OCI_TRIGGER_EVENT_TYPE`	Trigger que iniciou o evento.
`OCI_PRIMARY_SOURCE_DIR`	Diretório de trabalho padrão do build (diretório de trabalho de origem principal).
`OCI_WORKSPACE_DIR`	Valor do diretório de trabalho. Contém `/workspace` como valor padrão.
`${OCI_WORKSPACE_DIR}/<source-name>`	Caminho do diretório de origem do build. `source-name` é o nome da origem de build fornecida pelo usuário durante a criação do estágio de Build.
`OCI_BUILD_STAGE_NAME`	Nome do estágio de Build.
`OCI_PRIMARY_SOURCE_NAME`	Nome da origem de build principal.
`OCI_PRIMARY_SOURCE_COMMIT_HASH`	Hash de confirmação da origem do build principal usado na execução do build atual.
`OCI_PRIMARY_SOURCE_URL`	URL de origem do build principal.
`OCI_PRIMARY_SOURCE_BRANCH_NAME`	Ramificação de origem do build principal usada na execução do build atual.

Exemplos de Especificação de Build

Exemplo 1:

version: 0.1             
component: build
timeoutInSeconds: 1000
shell: bash           

steps:
  - type: Command
    name: "Build app"
    command: |
      mvn clean install

Exemplo 2:

version: 0.1
component: build
timeoutInSeconds: 6000
shell: bash
failImmediatelyOnError: true
env:
  exportedVariables:
    - BuildServiceDemoVersion

steps:
  - type: Command
    name: "Build Source"
    timeoutInSeconds: 4000
    failImmediatelyOnError: true
    command: |
      echo $PATH
      mvn clean install
  - type: Command
    timeoutInSeconds: 400
    name: "Dockerizer"
    command: |
      BuildServiceDemoVersion=`echo ${OCI_BUILD_RUN_ID} | rev | cut -c 1-7`
      echo $BuildServiceDemoVersion
      docker build -t build-service-demo

  - type: VulnerabilityAudit
    name: "Scan my maven repo"
    vulnerabilityAuditName: Report-${buildRunId}
    vulnerabilityAuditCompartmentId: ocid1.compartment.oc1.iad.restoftheocid
    knowledgeBaseId: ocid1.knowledgebase.oc1.iad.restoftheocid
    configuration:
      buildType: maven
      pomFilePath: ./pom.xml
      packagesToIgnore:
        - "oracle.jdbc.*"
        - "org.apache.logging.log4j:1.2"
      maxPermissibleCvssV2Score: 5.0  
      maxPermissibleCvssV3Score: 5.1
      freeFormTags:
                  key1: value1
                  key2: value2

outputArtifacts:
  - name: build-service-demo
    type: DOCKER_IMAGE
    location: build-service-demo
  - name: build-service-demo-kube-manifest
    type: BINARY
    location: deployment/app.yml

Exemplo 3:

version: 0.1
component: build
timeoutInSeconds: 6000
shell: bash

# Variables
env:
  variables:
    "testEnv" : "testValue1"
  vaultVariables:
    docker_registry_password : <secret-ocid>
  exportedVariables:
    - patch_number
    - build_Result

inputArtifacts:
  - name: hello-dev-jar 
    type: STAGE_ARTIFACT
    location: /workspace/Source/hello123.class
  - name: public-artifact
    type: URL
    url: https://raw.githubusercontent.com/apache/kafka/trunk/README.md  #URL must be publicly accessible
    location: /workspace/Source/readme.md
  - name: shell_script
    type: GENERIC_ARTIFACT
    artifactId: ocid1.genericartifact.oc1.iad.0.restoftheocid #appropriate policy is required for access
    location: /workspace/Source/script.sh
  - name: shell_script
    type: GENERIC_ARTIFACT
    registryId: ocid1.artifactrepository.oc1.iad.0.restoftheocid #appropriate policy is required for access
    path: some_script.sh
    version: 2.0
    location: /workspace/Source/script.sh

steps:
  - type: Command
    name: "Build Source"
    timeoutInSeconds: 4000
    shell: /bin/sh
    command: |
      # oci cli pre configured with build pipeline resource principal
      oci os ns get
      javac HelloWorld.java
    onFailure:
      - type: Command
        timeoutInSeconds: 400
        shell: /bin/sh
        command: |
          echo "Handling Failure"
          build_result=FAILURE
          echo "Failure successfully handled"
        timeoutInSeconds: 400
  - type: Command
    timeoutInSeconds: 400
    name: "Dockerizer & Test"
    command: |
      docker build -t test-image .
    onFailure:
      - type: Command
        command: |
          echo "Handling Failure"
          build_result=FAILURE
          echo "Failure successfully handled"
        timeoutInSeconds: 400
  - type: Command
    timeoutInSeconds: 400
    name: "Dockerizer & Test"
    command: |
      build_result=SUCCESS
      patch_number==`echo ${OCI_BUILD_RUN_ID} | rev | cut -c 1-7`
        
outputArtifacts:
  - name: kube-manifest
    type: BINARY
    location: ${OCI_WORKSPACE_DIR}/Source/app.yml
  - name: hello-dev-image
    type: DOCKER_IMAGE
    location: test-image