Spécification de compilation

La spécification de compilation contient les étapes et les paramètres utilisés par le pipeline de compilation pour exécuter une compilation.

La spécification de compilation est écrite en YAML. Par défaut, la spécification de création est située à la racine du répertoire de la source de création principale et est utilisée lorsque vous exécutez un pipeline de création. Le nom du fichier est build_spec.yml ou build_spec.yaml. Si la spécification de compilation ne se trouve pas dans le répertoire racine, vous devez indiquer le chemin relatif du fichier lors de l'ajout de l'étape de compilation gérée.

La spécification de compilation se compose des sections suivantes :

Configuration de l'exécuteur de compilation.
Configuration des variables d'environnement.
Artefacts d'entrée.
Étapes à exécuter dans l'ordre.
Artefacts de sortie.

Syntaxe de la spécification de compilation

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

Note

sudo n'est pas disponible sur l'hôte de l'exécution de compilation. Si vous avez besoin des autorisations de superutilisateur, exécutez l'étape de compilation en tant qu'utilisateur racine.

Paramètres de la spécification de compilation

Voici la liste des paramètres de la spécification de compilation et leur description :


Paramètre	Description
`version`	Obligatoire. Indique la version de la spécification de compilation. Une version manquante ou non valide entraîne l'échec de l'étape de compilation. La valeur prise en charge est `0.1`.
`component`	Obligatoire. Indique un composant spécifique dans DevOps. Une valeur manquante ou non valide entraîne l'échec de la compilation. La valeur prise en charge est `build`.
`timeoutInSeconds`	Facultatif. Indique la temporisation pour l'ensemble du fichier de spécification de compilation. Chaque étape peut également avoir sa propre valeur de temporisation. Si aucune valeur n'est spécifiée, la valeur par défaut, 8 heures, est utilisée. La valeur maximale autorisée est 8 heures.
`shell`	Facultatif. Indique l'interpréteur de commandes à utiliser au niveau global de la spécification de compilation. Cette valeur peut éventuellement être remplacée au niveau de l'étape. Les valeurs autorisées sont `/bin/sh` et `bash`. Si aucune valeur n'est spécifiée, la valeur par défaut, `bash`, est utilisée.
`failImmediatelyOnError`	Facultatif. Indique si la compilation doit continuer si l'une des commandes de l'étape échoue avec une valeur de sortie différente de zéro. Si vous ne spécifiez pas de valeur, la valeur par défaut est `false` et l'étape continue. Les valeurs autorisées sont `true` et `false`. OCI recommande de régler la valeur de cet attribut à `true`.
`env`	Facultatif. Vous pouvez définir des variables personnalisées. Trois types de variable sont pris en charge : env/variables : Facultatif. La clé doit être une chaîne conforme aux variables d'environnement POSIX. La valeur peut être une chaîne quelconque. La portée de cette variable est l'exécution du fichier de spécification de compilation. Toute modification de la valeur de la variable est visible dans les étapes suivantes. Ces variables sont disponibles en tant que variables d'environnement pour toutes les étapes du fichier de spécification de compilation. Si la valeur de la variable contient un caractère de saut de ligne (\n) ou de retour de chariot (\r), il est remplacé par un espace dans les étapes suivantes. env/vaultVariables : Facultatif. La clé doit être une chaîne conforme aux variables d'environnement POSIX. La valeur doit être un OCID de clé secrète de la chambre forte. Le chambre forte et le pipeline de compilation doivent se trouver dans la même location. La location doit disposer d'une politique permettant aux ressources du pipeline de compilation d'accéder à la clé secrète. La portée de cette variable est l'exécution du fichier de spécification de compilation et elle est disponible pour toutes les étapes du fichier. La valeur de ces variables est extraite de la chambre forte et mise à disposition en tant que variable d'environnement pour toutes les étapes du fichier de spécification de compilation. env/exportedVariables : Facultatif. Vous pouvez déclarer une liste de variables. Le nom de la variable doit être une chaîne conforme aux variables d'environnement POSIX. La valeur peut être affectée dans une étape quelconque du fichier de spécification de compilation. La portée de cette variable est le pipeline de compilation. Toute variable exportée est disponible dans les étapes suivantes du même pipeline.
`inputArtifacts`	Facultatif. Sert à définir une liste des artefacts d'entrée requis pour exécuter l'étape de compilation courante. Prend en charge les types d'artefact d'entrée suivants : Artefacts provenant de l'une des étapes de compilation précédentes. Artefacts provenant d'une URL HTTP téléchargeable externe. Artefacts génériques du registre d'artefacts. Les paramètres sont les suivants : *inputArtifacts//url : Facultatif. L'URL HTTP téléchargeable externe de l'artefact d'entrée doit être fournie. L'URL doit être accessible au public. L'authentification/autorisation n'est pas prise en charge actuellement. inputArtifacts//name* : Obligatoire. Si l'URL n'est pas présente, elle est utilisée pour rechercher les artefacts produits par les étapes de compilation précédentes du même pipeline. Par conséquent, outputArtifacts/name et inputArtifacts/name doivent correspondre pour consommer un artefact spécifique produit par l'étape de compilation précédente du pipeline. *inputArtifacts//location : Obligatoire. Chemin de destination du système de fichiers local où l'artefact d'entrée doit être téléchargé. Le chemin peut être spécifié de l'une des façons suivantes : `${OCI_PRIMARY_SOURCE_DIR}/pom.xml` `${OCI_WORKSPACE_DIR}/[source-name]/pom.xml` `/workspace/[source-name]/pom.xml` Chemin relatif à partir du répertoire de base du projet, `pom.xml` Quelle que soit la valeur utilisée, l'artefact d'entrée est téléchargé dans le répertoire de base source principal avec un nom de fichier, `pom.xml`. L'emplacement ne prend pas en charge `exportedVariables` ni les variables de pipeline. inputArtifacts//type* : Obligatoire. Type de l'artefact d'entrée qui doit être téléchargé. Les valeurs autorisées sont `URL`, `STAGE_ARTIFACT` et `GENERIC_ARTIFACT`. *inputArtifacts//artifactld : Obligatoire. OCID de l'artefact. Si vous avez fourni l'OCID, le pipeline de compilation ignore l'ID registre, le chemin et la version. inputArtifacts//registryld* : obligatoire. OCID du registre d'artefacts. *inputArtifacts//path : Obligatoire. Chemin de destination de l'artefact. inputArtifacts//version* : Obligatoire. Version de l'artefact. Note : Pour le type d'artefact d'entrée `GENERIC_ARTIFACT`, vous pouvez fournir comme paramètre obligatoire l'OCID de l'artefact ou une combinaison d'ID registre, chemin et version d'artefact.
`steps`	Obligatoire. Cette section définit une liste d'étapes à exécuter. *steps//type : obligatoire. Indique le type d'étape. Prend en charge les valeurs suivantes : `Command`, `VulnerabilityAudit`. Pour plus d'informations, voir Types d'étape. steps//name* : Facultatif. Nom convivial de l'étape.
`outputArtifacts`	Facultatif. Indique les artefacts produits par l'étape de compilation. Les artefacts produits en tant que sortie dans cette section sont enregistrés pendant toute la durée de l'exécution de compilation courante. Ils peuvent être utilisés dans les étapes suivantes du pipeline de compilation. *outputArtifacts//name : Obligatoire. Le nom peut contenir des lettres minuscules (a-z), des lettres majuscules (A-Z), des traits de soulignement (_) et des tirets (-). Le nom est l'identificateur unique de l'artefact de sortie. Dans les étapes ultérieures du pipeline de compilation, le nom est utilisé pour identifier un objet. outputArtifacts//type* : Obligatoire. Les valeurs autorisées sont `BINARY` et `DOCKER_IMAGE`. BINARY : Spécifie des fichiers binaires en tant qu'artefacts de sortie. *outputArtifacts//location : Chemin source du système de fichiers local où se trouve l'artefact de sortie. Le chemin peut être spécifié de l'une des façons suivantes (en supposant que le fichier `pom.xml` se trouve dans le répertoire de base source principal) : `${OCI_PRIMARY_SOURCE_DIR}/pom.xml` `${OCI_WORKSPACE_DIR}/[source-name]/pom.xml` `/workspace/[source-name]/pom.xml` Chemin relatif à partir du répertoire de base du projet, `pom.xml` Si le fichier ne se trouve pas dans l'emplacement indiqué, l'étape de compilation échoue. DOCKER_IMAGE : Spécifie une image Docker en tant qu'artefact de sortie. outputArtifacts//location* : Marqueur de l'image Docker compilée lors d'une étape du fichier de spécification de compilation. Par exemple, si dans l'une des étapes du fichier de spécification de compilation, une image Docker est compilée en tant que `docker build -t iad.ocir.io/id204we8d65n/hello-world:1.0`, le champ d'emplacement doit contenir `iad.ocir.io/id204we8d65n/hello-world:1.0` pour que cet artefact soit produit. L'image doit être compilée ou extraite et mise à disposition dans l'une des étapes de la spécification de compilation. Sinon, l'étape `outputArtifact` échoue, ainsi que l'étape de compilation. L'emplacement ne prend pas en charge `exportedVariables` ni les variables de pipeline.

Types d'étape

Commande


Nom de l'attribut	Description
`command`	Les commandes à une seule ligne et à plusieurs lignes sont prises en charge. Toutes les commandes spécifiées dans une étape sont exécutées dans la même session de l'interpréteur de commandes. Selon la valeur de `steps/*/shell`, il peut s'agir de commandes shell ou bash. L'interruption immédiate n'est pas activée. Pour que l'étape réussisse, la sortie de la dernière commande d'une étape est prise en compte. Si le code de sortie de la dernière commande est 0, l'étape est considérée comme réussie.
`timeoutInSeconds` (Facultatif)	Indique la temporisation de l'étape. Si elle n'est pas indiquée, la valeur est héritée du paramètre `timeoutInSeconds` global. La valeur maximale autorisée est 8 heures.
`shell` (Facultatif)	Indique le type d'interpréteur de commandes de l'étape courante. Si elle n'est pas spécifiée, la valeur est héritée du paramètre `shell` global. Les valeurs autorisées sont `/bin/sh` et `shell`.
`onFailure` (Facultatif)	Liste d'étapes à exécuter en cas d'échec pour quitter correctement l'étape de compilation. Elles sont exécutées si l'étape correspondante échoue, et suivies de la sortie de la spécification de compilation. La gestion de l'échec n'a aucune incidence sur le statut de l'étape de compilation. Si l'une des étapes échoue, le statut de l'étape de compilation reste `failed`, mais elle est traitée par le bloc `onFailure`.
`failImmediatelyOnError` (Facultatif)	Indique si la compilation doit continuer si l'une des commandes de l'étape échoue avec une valeur de sortie différente de zéro. Si vous ne spécifiez pas de valeur, la valeur par défaut est `false` et l'étape continue. Les valeurs autorisées sont `true` et `false`. OCI recommande de régler la valeur de cet attribut à `true`. La valeur de l'attribut `failImmediatelyOnError` définie sous `steps` a priorité sur la valeur du même attribut définie en dehors de `steps`.

Recherche de vulnérabilités

Une audit de vulnérabilité décrit les vulnérabilités de l'application et de ses dépendances. Lorsque vous exécutez une compilation à l'aide du service OCI DevOps, vous pouvez démarrer un balayage de code pour effectuer une nouvelle validation du référentiel de code. La recherche de vulnérabilités se produit à l'étape de compilation gérée.

Dans le fichier de spécification de compilation, une étape de recherche de vulnérabilités de type VulnerabilityAudit est ajoutée, que le pipeline de compilation DevOps utilise lors de l'exécution de la compilation pour le balayage de code. Les attributs de cette étape sont les suivants :


Nom de l'attribut	Description	Prise en charge de valeurs paramétrées
`name` (Facultatif)	Nom de l'étape.	S. O.
`vulnerabilityAuditName` (Facultatif)	Nom de la ressource de recherche de vulnérabilités.	Oui
`vulnerabilityAuditCompartmentId` (Facultatif) Par défaut : `knowledgeBaseCompartmentId`.	OCID du compartiment dans lequel la ressource de vérification doit être créée.	Oui
`knowledgeBaseId` (Obligatoire)	OCID du paramètre fictif/marqueur utilisé pour tenir à jour les détails des ressources de recherche de vulnérabilités. Ressource parent de la ressource de recherche de vulnérabilités.	Oui
`configuration/buildType` (Obligatoire)	Type d'outil de compilation.	S. O.
`configuration/pomFilePath` (Obligatoire)	Emplacement du fichier pom.xml.	Oui
`configuration/packagesToIgnore` (Facultatif)	Liste des ensembles Java à ignorer lors du calcul du résultat du balayage pendant la recherche de vulnérabilités.	S. O.
`configuration/maxPermissibleCvssV2Score` (Facultatif) Par défaut : 0.0	Note CVSS v2 maximale admissible pour la recherche de vulnérabilités. Toute valeur supérieure à cette configuration doit marquer la compilation comme `Failed`.	S. O.
`configuration/maxPermissibleCvssV3Score` (Facultatif) Par défaut : 0.0	Note CVSS v3 maximale admissible pour la recherche de vulnérabilités. Toute valeur supérieure à cette configuration doit marquer la compilation comme `Failed`.	S. O.
`freeFormTags` (Facultatif)	Accepte une paire clé-valeur.	S. O.

Variables de système prédéfinies

DevOps fournit un jeu de variables de système prédéfinies avec des valeurs par défaut que vous pouvez utiliser, telles que des variables d'environnement dans la spécification de compilation.


Variable	Description
`OCI_STAGE_ID`	OCID de l'étape courante.
`OCI_PIPELINE_ID`	OCID du pipeline de compilation courant.
`OCI_BUILD_RUN_ID`	OCID de l'exécution de compilation courante.
`OCI_TRIGGER_COMMIT_HASH`	Code de hachage de validation du déclencheur courant.
`OCI_TRIGGER_SOURCE_BRANCH_NAME`	Branche qui déclenche la compilation.
`OCI_TRIGGER_SOURCE_URL`	URL du référentiel qui a déclenché la compilation.
`OCI_TRIGGER_EVENT_TYPE`	Déclencheur qui a démarré l'événement.
`OCI_PRIMARY_SOURCE_DIR`	Répertoire de travail par défaut de la compilation (répertoire de travail source principal).
`OCI_WORKSPACE_DIR`	Valeur du répertoire de travail. Contient `/workspace` comme valeur par défaut.
`${OCI_WORKSPACE_DIR}/<source-name>`	Chemin du répertoire source de la compilation. `source-name` est le nom de la source de compilation indiquée par l'utilisateur lors de la création de l'étape de compilation.
`OCI_BUILD_STAGE_NAME`	Nom de l'étape de compilation.
`OCI_PRIMARY_SOURCE_NAME`	Nom de la source de compilation principale.
`OCI_PRIMARY_SOURCE_COMMIT_HASH`	Code de hachage de validation de la source de compilation principale utilisé pour l'exécution de compilation courante.
`OCI_PRIMARY_SOURCE_URL`	URL de la source de compilation principale.
`OCI_PRIMARY_SOURCE_BRANCH_NAME`	Branche de la source de compilation principale utilisée pour l'exécution de compilation courante.

Exemples de spécification de compilation

Exemple 1 :

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

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

exemple 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

exemple 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