Especificación de la compilación

La especificación de compilación contiene los pasos y la configuración de compilación que utiliza el pipeline de compilación para ejecutar una compilación.

La especificación de compilación está escrita en YAML. Por defecto, la especificación de creación se encuentra en la raíz del directorio de origen de creación principal y se utiliza al ejecutar un pipeline de creación. El archivo se denomina build_spec.yml o build_spec.yaml. Si la especificación de compilación no está presente en el directorio raíz, debe proporcionar una ruta relativa del archivo al agregar la etapa Compilación gestionada.

La especificación de compilación se organiza en las siguientes secciones:

Configuración del programa de ejecución de compilación.
Configuración de las variables de entorno.
Artefactos de entrada.
Pasos para su ejecución en secuencia.
Artefactos de salida.

Sintaxis de especificación de compilación

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

Nota

sudo no está disponible en el host del ejecutor de compilación. Si necesita permisos de superusuario, ejecute el paso de compilación como usuario root.

Parámetros de especificación de compilación

A continuación, se muestran los parámetros de especificación de compilación y sus detalles:


Parámetro	Descripción
`version`	Obligatorio. Indica la versión de especificación de compilación. Una versión que falta o no es válida provoca un fallo en la etapa de compilación. El valor soportado es `0.1`.
`component`	Obligatorio. Indica un componente concreto en DevOps. Si falta un valor o no es válido, se produce un fallo de compilación. El valor soportado es `build`.
`timeoutInSeconds`	Opcional. Especifica el timeout para todo el archivo de especificación de compilación. Cada 'paso' también puede tener opcionalmente su propio valor de timeout. Si no se especifica un valor, se utiliza el valor por defecto de 8 horas. El valor máximo permitido es 8 horas.
`shell`	Opcional. Especifica el shell que se utilizará en el nivel global de especificación de compilación. El valor se puede sustituir opcionalmente en el nivel de 'paso'. Los valores permitidos son `/bin/sh` y `bash`. Si no se especifica, se utilizará el valor por defecto `bash`.
`failImmediatelyOnError`	Opcional. Especifica si la compilación debe continuar en caso de que falle algún comando del paso con un valor de salida distinto de cero. Si no se especifica, el valor por defecto es `false` y el paso continúa. Los valores permitidos son `true` y `false`. OCI recomienda definir el valor de este atributo en `true`.
`env`	Opcional. Puede definir variables personalizadas. Hay soportados tres tipos de variables: env/variables: opcional. La clave debe ser una cadena compatible con una variable de entorno POSIX. El valor puede ser cualquier cadena. El ámbito de esta variable es la ejecución del archivo de especificación de compilación. Cualquier cambio en el valor de la variable se puede ver en los pasos siguientes. Estas variables están disponibles como variables de entorno para todos los pasos dentro del archivo de especificación de compilación. Si el valor de la variable contiene el carácter de nueva línea (\n) o retorno de carro (\r), se sustituyen por un espacio en los pasos siguientes. env/vaultVariables: opcional. La clave debe ser una cadena compatible con una variable de entorno POSIX. El valor debe ser un OCID del secreto del almacén. El almacén y el pipeline de compilación deben ser del mismo arrendamiento. El arrendamiento debe tener la política adecuada para permitir a los recursos del pipeline de compilación acceder al secreto. El ámbito de esta variable es la ejecución del archivo de especificación de compilación y está disponible para todos los pasos del archivo. El valor de estas variables se recupera del almacén y está disponible como variables de entorno para todos los pasos dentro del archivo de especificación de compilación. env/exportedVariables: opcional. Aquí se puede declarar una lista de variables. El nombre de la variable debe ser una cadena compatible con una variable de entorno POSIX. El valor se puede asignar en cualquiera de los pasos dentro del archivo de especificación de compilación. El ámbito de esta variable es el pipeline de compilación. Cualquier variable exportada está disponible en etapas posteriores del mismo pipeline.
`inputArtifacts`	Opcional. Se utiliza para definir la lista de artefactos de entrada necesarios para ejecutar la etapa de compilación actual. Soporta los siguientes tipos de artefacto de entrada: Artefactos de cualquiera de las etapas de compilación anteriores. Artefactos de cualquier URL HTTP descargable externa. Artefactos genéricos de Artifact Registry. Los parámetros son los siguientes: *inputArtifacts//url: opcional. Se debe proporcionar la URL HTTP descargable externa del artefacto de entrada. La URL debe estar disponible públicamente. Actualmente no está soportada la autenticación/autorización. inputArtifacts//name: obligatorio. Si la URL no está presente, este nombre se utiliza para buscar los artefactos producidos por las etapas de compilación anteriores en el mismo pipeline. Por lo tanto, outputArtifacts/name e inputArtifacts/name deben coincidir para consumir un artefacto específico producido por la etapa de compilación anterior del pipeline. inputArtifacts//location: obligatorio. Ruta de destino del sistema de archivos local donde se debe descargar el artefacto de entrada. La ruta se puede especificar en uno de estos métodos: `${OCI_PRIMARY_SOURCE_DIR}/pom.xml` `${OCI_WORKSPACE_DIR}/[source-name]/pom.xml` `/workspace/[source-name]/pom.xml` Ruta relativa desde la página inicial del proyecto, `pom.xml` Con cualquiera de los valores, el artefacto de entrada se descarga en el directorio de inicio de origen principal con un nombre de archivo, `pom.xml`. La ubicación no soporta las variables de pipeline o `exportedVariables`. inputArtifacts//type: obligatorio. Tipo del artefacto de entrada que se debe descargar. Los valores permitidos son `URL`, `STAGE_ARTIFACT` y `GENERIC_ARTIFACT`. inputArtifacts//artifactld: obligatorio. OCID del artefacto. Si ha proporcionado el OCID, el pipeline de creación ignora registryId, la ruta y la versión. inputArtifacts//registryld: obligatorio. OCID de Artifact Registry. inputArtifacts//path: obligatorio. Ruta de destino del artefacto. inputArtifacts//version: obligatorio. Versión del artefacto. Nota:* Para el tipo `GENERIC_ARTIFACT` de artefacto de entrada, puede proporcionar como parámetro obligatorio el OCID del artefacto o una combinación del ID de registro, la ruta de acceso y la versión de artefacto.
`steps`	Obligatorio. En esta sección se define una lista de pasos que se deben ejecutar. *steps//type: obligatorio. Especifica el tipo de paso. Soporta los siguientes valores: `Command` y `VulnerabilityAudit`. Para obtener más información, consulte Tipos de pasos. steps//name*: Opcional. Nombre fácil de recordar para el paso.
`outputArtifacts`	Opcional. Especifica los artefactos producidos por la etapa de compilación. Los artefactos producidos como salida en esta sección se guardan durante la ejecución de la compilación actual. Se pueden utilizar en las etapas posteriores del pipeline de compilación. *outputArtifacts//name: obligatorio. El nombre puede contener letras minúsculas (a-z), letras mayúsculas (A-Z), guiones bajos (_) y guiones (-). El nombre es el identificador único del artefacto de salida. En las últimas etapas del pipeline de creación, el nombre se utiliza para identificar un artefacto. outputArtifacts//type: obligatorio. Los valores permitidos son `BINARY` y `DOCKER_IMAGE`. BINARY: especifica archivos binarios como artefactos de salida. outputArtifacts//location: ruta de origen del sistema de archivos local donde se puede encontrar el artefacto de salida. La ruta se puede especificar en cualquiera de estos métodos (se asume que el archivo `pom.xml` está presente en el directorio de inicio de origen principal): `${OCI_PRIMARY_SOURCE_DIR}/pom.xml` `${OCI_WORKSPACE_DIR}/[source-name]/pom.xml` `/workspace/[source-name]/pom.xml` Ruta relativa desde la página inicial del proyecto, `pom.xml` Si el archivo no se encuentra en la ubicación proporcionada, la etapa de compilación falla. DOCKER_IMAGE: especifica una imagen de Docker como artefacto de salida. outputArtifacts//location*: etiqueta de imagen de Docker creada sobre uno de los pasos del archivo de especificación de compilación. Por ejemplo, si en cualquiera de los pasos del archivo de especificación de compilación se crea una imagen de Docker como `docker build -t iad.ocir.io/id204we8d65n/hello-world:1.0`, el campo de ubicación debe contener `iad.ocir.io/id204we8d65n/hello-world:1.0` para producir este artefacto. La imagen se debe compilar u obtener y debe estar disponible en uno de los pasos de especificación de compilación. De lo contrario, el paso `outputArtifact` falla y, finalmente, también falla la etapa de compilación. La ubicación no soporta las variables de pipeline o `exportedVariables`.

Tipos de paso

Comando


Nombre de atributo	Descripción
`command`	Están soportados tanto comandos de una sola línea como de varias líneas. Todos los comandos especificados en un paso se ejecutan en la misma sesión de shell. Según el valor `steps/*/shell`, los comandos pueden ser shell o bash. Error rápido no está activado. Para que el paso se realice correctamente, se tiene en cuenta la salida del último comando en un paso. Si el último código de salida del comando es 0, el paso se considera correcto.
`timeoutInSeconds` (opcional)	Especifica el timeout del paso. Si no se proporciona, el valor se hereda del parámetro global `timeoutInSeconds`. El valor máximo permitido es 8 horas.
`shell` (opcional)	Especifica el tipo de shell del paso actual. Si no se especifica, el valor se hereda del parámetro global `shell`. Los valores permitidos son `/bin/sh` y `shell`.
`onFailure` (opcional)	Lista de pasos que se deben ejecutar en caso de fallo para salir correctamente de la etapa de compilación. Se ejecuta si falla el paso correspondiente y, después de la ejecución, se sale de la especificación de compilación. El manejo del fallo no afecta al estado de la etapa de compilación Si alguno de los pasos falla, el estado de la etapa de compilación sigue siendo `failed`, aunque se maneja mediante el bloque `onFailure`
`failImmediatelyOnError` (opcional)	Especifica si la compilación debe continuar en caso de que falle algún comando del paso con un valor de salida distinto de cero. Si no se especifica, el valor por defecto es `false` y el paso continúa. Los valores permitidos son `true` y `false`. OCI recomienda definir el valor de este atributo en `true`. El valor de atributo `failImmediatelyOnError` definido en `steps` tiene prioridad sobre el mismo valor de atributo definido fuera de `steps`.

Auditoría de vulnerabilidad

Una auditoría de vulnerabilidad describe las vulnerabilidades de la aplicación y sus dependencias. Al ejecutar una compilación mediante el servicio DevOps de OCI, puede iniciar una exploración de código para una nueva confirmación en el repositorio de código. La auditoría de vulnerabilidad se desarrolla en la etapa Compilación gestionada.

En el archivo de especificación de compilación, se agrega un paso de auditoría de vulnerabilidad de tipo VulnerabilityAudit, que el pipeline de compilación de DevOps utiliza durante la ejecución de la compilación para la exploración de código. Los atributos de este paso se muestran de la siguiente manera:


Nombre de atributo	Descripción	Soporte de valor parametrizado
`name` (opcional)	Nombre del paso.	NA
`vulnerabilityAuditName` (opcional)	Nombre del recurso de auditoría de vulnerabilidad.	Sí
`vulnerabilityAuditCompartmentId` (opcional) El valor por defecto es `knowledgeBaseCompartmentId`	OCID del compartimento en el que se debe crear el recurso de auditoría.	Sí
`knowledgeBaseId` (obligatorio)	OCID del marcador de posición/etiqueta para mantener los detalles del recurso de auditoría de vulnerabilidad. Recurso principal del recurso de auditoría de vulnerabilidad.	Sí
`configuration/buildType` (obligatorio)	Tipo de herramienta de compilación.	NA
`configuration/pomFilePath` (obligatorio)	Ubicación del archivo pom.xml.	Sí
`configuration/packagesToIgnore` (opcional)	Lista de paquetes de Java que deben ignorarse al calcular el resultado de la exploración mientras se lleva a cabo la auditoría de vulnerabilidad.	NA
`configuration/maxPermissibleCvssV2Score` (opcional) El valor por defecto es 0,0	Puntuación de CVSS v2 máxima que se permite para la auditoría de vulnerabilidad. Cualquier valor por encima de esta configuración marcará la compilación como `Failed`.	NA
`configuration/maxPermissibleCvssV3Score` (opcional) El valor por defecto es 0,0	Puntuación de CVSS v3 máxima que se permite para la auditoría de vulnerabilidad. Cualquier valor por encima de esta configuración marcará la compilación como `Failed`.	NA
`freeFormTags` (opcional)	Acepta el par de clave-valor.	NA

Variables del sistema predefinidas

DevOps proporciona un juego de variables predefinidas del sistema con valores por defecto que puede utilizar como variables de entorno en la especificación de compilación.


Variable	Descripción
`OCI_STAGE_ID`	OCID de la etapa actual.
`OCI_PIPELINE_ID`	OCID del pipeline de compilación actual.
`OCI_BUILD_RUN_ID`	OCID de la ejecución de compilación actual.
`OCI_TRIGGER_COMMIT_HASH`	Confirme el hash del disparador actual.
`OCI_TRIGGER_SOURCE_BRANCH_NAME`	Rama que dispara la compilación.
`OCI_TRIGGER_SOURCE_URL`	URL de repositorio que ha disparado la compilación
`OCI_TRIGGER_EVENT_TYPE`	Disparador que ha iniciado el evento.
`OCI_PRIMARY_SOURCE_DIR`	Directorio de trabajo por defecto de la compilación (directorio de trabajo de origen principal).
`OCI_WORKSPACE_DIR`	Valor del directorio de trabajo. Contiene `/workspace` como valor por defecto.
`${OCI_WORKSPACE_DIR}/<source-name>`	Ruta del directorio del origen de compilación. `source-name` es el nombre del origen de compilación proporcionado por el usuario al crear la etapa de compilación.
`OCI_BUILD_STAGE_NAME`	Nombre de etapa de compilación.
`OCI_PRIMARY_SOURCE_NAME`	Nombre de origen de compilación principal.
`OCI_PRIMARY_SOURCE_COMMIT_HASH`	Hash de confirmación de origen de compilación principal utilizado en la ejecución de compilación actual.
`OCI_PRIMARY_SOURCE_URL`	URL de origen de compilación principal.
`OCI_PRIMARY_SOURCE_BRANCH_NAME`	Rama de origen de compilación principal utilizada en la ejecución de compilación actual.

Ejemplos de especificación de compilación

Ejemplo1:

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

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

Ejemplo2:

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

Ejemplo3:

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

Nota

Para crear aplicaciones Java de alto rendimiento, puede utilizar Oracle GraalVM en el pipeline de creación. Para instalar y utilizar Oracle GraalVM en el pipeline de compilación DevOps, debe actualizar el archivo de especificación de compilación. Para obtener más información y ejemplos, consulte Uso de Oracle GraalVM en DevOps Pipelines de compilación.

Documentación de Oracle Cloud Infrastructure Probar cuenta gratuita