Documentation Oracle Cloud Infrastructure

Spécification de build

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

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

La spécification de build comprend les sections suivantes :

  • Configuration du programme d'exécution de build.
  • Configuration des variables d'environnement.
  • Artefacts d'entrée.
  • Etapes à exécuter dans l'ordre.
  • Artefacts de sortie.

Syntaxe de spécification 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
Remarque :

sudo n'est pas disponible sur l'hôte du programme d'exécution de création. Si vous avez besoin de droits d'accès de superutilisateur, exécutez l'étape de build en tant qu'utilisateur root.

Paramètres de spécification de build

Vous trouverez ci-dessous les paramètres de spécification de build et leurs détails :

Paramètre Description
version Obligatoire. Indique la version de la spécification de build. Une version manquante ou non valide entraîne l'échec de la phase de build.

La valeur prise en charge est 0.1.
component Obligatoire. Indique un composant particulier dans DevOps. Une valeur manquante ou non valide entraîne l'échec du build.

La valeur prise en charge est build.
timeoutInSeconds Facultatif. Indique le délai d'expiration pour l'ensemble du fichier de spécification de build. Chaque étape peut également avoir sa propre valeur de délai d'expiration.

Si aucune valeur n'est indiquée, la valeur par défaut est utilisée, soit 8 heures. La valeur maximale autorisée est 8 heures.
shell Facultatif. Indique le shell à utiliser au niveau global de la spécification de build. La valeur peut éventuellement être remplacée au niveau d'une étape.

Les valeurs autorisées sont /bin/sh et bash. Si aucune valeur n'est indiquée, la valeur par défaut bash est utilisée.
failImmediatelyOnError Facultatif. Indique si le build doit continuer lorsqu'une commande de l'étape échoue avec une valeur de sortie différente de zéro. Si aucune valeur n'est renseignée, la valeur par défaut est false et l'étape continue. Les valeurs autorisées sont true et false. OCI recommande de définir la valeur de cet attribut sur 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 et conforme à la variable d'envionnement POSIX. La valeur peut être n'importe quelle chaîne. La portée de cette variable est l'exécution du fichier de spécification de build. Toute modification apportée à 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 build.

    Si la valeur de la variable contient un caractère de nouvelle ligne (\n) ou de retour chariot (\r), celui-ci est remplacé par un espace dans les étapes suivantes.

  • env/vaultVariables : facultatif. La clé doit être une chaîne et conforme à la variable d'envionnement POSIX. La valeur doit être un OCID de la clé secrète du coffre. Le coffre et le pipeline de build doivent être dans la même location. Cette dernière doit disposer d'une stratégie appropriée pour autoriser les ressources de pipeline de build à accéder à la clé secrète.

    La portée de cette variable est l'exécution du fichier de spécification de build et est disponible pour toutes les étapes du fichier. Les valeurs de ces variables sont extraites du coffre et elles sont mises à disposition en tant que variables d'environnement pour toutes les étapes du fichier de spécification de build.

  • env/exportedVariables : facultatif. Vous pouvez déclarer la liste des variables ici. Le nom de la variable doit être une chaîne et conforme à la variable d'envionnement POSIX. La valeur peut être affectée à n'importe quelle étape du fichier de spécification de build. La portée de cette variable est le pipeline de build. Toute variable exportée est disponible dans les phases suivantes du même pipeline.
inputArtifacts

Facultatif. Utilisé afin de définir la liste des artefacts d'entrée requis pour exécuter la phase de build en cours.

Prend en charge les types d'artefact d'entrée suivants :
  • Artefacts des phases de build précédentes.
  • Artefacts de toute URL HTTP téléchargeable externe.
  • Artefacts génériques provenant d'Artifact Registry.

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 publique. L'authentification/autorisation n'est pas prise en charge pour le moment.
  • inputArtifacts/*/name : obligatoire. Si aucune URL n'est indiquée, ce nom est utilisé pour rechercher les artefacts produits par les phases de build précédentes dans le même pipeline. Par conséquent, les éléments outputArtifacts/name et inputArtifacts/name doivent correspondre pour consommer un artefact spécifique produit par la phase de build précédente dans le pipeline.
  • inputArtifacts/*/location : obligatoire. Chemin de destination du système de fichiers local vers lequel l'artefact d'entrée doit être téléchargé. Le chemin peut être indiqué à l'aide de l'une des méthodes suivantes :
    • ${OCI_PRIMARY_SOURCE_DIR}/pom.xml
    • ${OCI_WORKSPACE_DIR}/[source-name]/pom.xml
    • /workspace/[source-name]/pom.xml
    • Chemin relatif à partir de l'accueil du projet, pom.xml

    Peu importe la valeur utilisée, l'artefact d'entrée est téléchargé vers le répertoire de base de la source principale avec le nom de fichier pom.xml.

    L'emplacement ne prend pas en charge exportedVariables ou les variables de pipeline.

  • inputArtifacts/*/type : obligatoire. Type de l'artefact d'entrée à télécharger. 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 build ignore les paramètres registryId, path et 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.

Remarque: Pour le type d'artefact d'entrée GENERIC_ARTIFACT, vous pouvez fournir en tant que paramètre obligatoire l'OCID de l'artefact ou une combinaison de l'ID de registre, du chemin et de la version de l'artefact.
steps

Obligatoire. Cette section définit la liste des étapes à exécuter.

  • steps/*/type : obligatoire. Indique le type d'étape. Prend en charge les valeurs suivantes : Command et VulnerabilityAudit. Pour plus d'informations, reportez-vous à Types d'étape.
  • steps/*/name : facultatif. Nom convivial de l'étape.
outputArtifacts

Facultatif. Indique les artefacts produits par la phase de build. Les artefacts produits en tant que sortie dans cette section sont enregistrés pendant toute la durée de vie de l'exécution de build en cours. Ils peuvent être utilisés dans les phases suivantes du pipeline de build.

  • outputArtifacts/*/name : obligatoire. Le nom peut contenir des minuscules (a-z), des majuscules (A-Z), des traits de soulignement (_) et des traits d'union (-). Le nom est l'identificateur unique de l'artefact de sortie. Dans les phases ultérieures du pipeline de build, le nom est utilisé pour identifier un artefact.
  • outputArtifacts/*/type : obligatoire. Les valeurs autorisées sont BINARY et DOCKER_IMAGE.

    BINARY : indique les fichiers binaires comme artefacts de sortie.

    outputArtifacts/*/location : chemin source du système de fichiers local dans lequel se trouve l'artefact de sortie. Le chemin peut être indiqué via l'une des méthodes suivantes (en supposant que le fichier pom.xml se trouve dans le répertoire de base de la source principale) :

    • ${OCI_PRIMARY_SOURCE_DIR}/pom.xml
    • ${OCI_WORKSPACE_DIR}/[source-name]/pom.xml
    • /workspace/[source-name]/pom.xml
    • Chemin relatif à partir de l'accueil du projet, pom.xml

    Si le fichier est introuvable à l'emplacement indiqué, la phase de build échoue.

    DOCKER_IMAGE : indique une image Docker en tant qu'artefact de sortie.

    outputArtifacts/*/location : balise d'image Docker de build créée à l'une des étapes du fichier de spécification de build.

    Par exemple, si à l'une des étapes du fichier de spécification de build, une image Docker est créé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 produire cet artefact.

    L'image doit être créée ou extraite, et rendue disponible dans l'une des étapes de spécification de build. Sinon, l'étape outputArtifact échoue et entraîne l'échec de la phase de build.

    L'emplacement ne prend pas en charge exportedVariables ou les variables de pipeline.

Types d'étape

Commande :

Nom de l'attribut Description
command Les commandes sur une seule ligne et sur plusieurs lignes sont prises en charge. Toutes les commandes indiquées dans une étape sont exécutées dans la même session de shell. En fonction de la valeur steps/*/shell, les commandes peuvent être shell ou bash.

L'échec rapide n'est pas activé. La sortie de la dernière commande d'une étape est prise en compte dans la réussite de l'étape. Si le code de sortie de la dernière commande est 0, l'étape est considérée comme réussie.
timeoutInSeconds (facultatif) Indique le délai d'expiration de l'étape. Si aucune valeur n'est fournie, la valeur est héritée du paramètre timeoutInSeconds global. La valeur maximale autorisée est 8 heures.
shell (facultatif) Indique le type de shell de l'étape en cours. Si aucune valeur n'est indiquée, la valeur est héritée du paramètre shell global. Les valeurs autorisées sont /bin/sh et shell.
onFailure (facultatif) Liste des étapes à exécuter en cas d'échec pour sortir progressivement de la phase de build. Si l'étape correspondante échoue, exécutez ces étapes. Après l'exécution, la spécification de build se ferme.

La gestion de l'échec n'affecte pas le statut de la phase de build. En cas d'échec de l'une des étapes, le statut de la phase de build reste failed, même si le bloc onFailure est utilisé pour gérer l'échec.
failImmediatelyOnError (facultatif) Indique si le build doit continuer lorsqu'une commande de l'étape échoue avec une valeur de sortie différente de zéro. Si aucune valeur n'est renseignée, la valeur par défaut est false et l'étape continue. Les valeurs autorisées sont true et false. OCI recommande de définir la valeur de cet attribut sur true.

La valeur de l'attribut failImmediatelyOnError définie sous steps est prioritaire par rapport à la valeur de ce même attribut définie en dehors de steps.

Audit de vulnérabilité

Un audit de vulnérabilité décrit les vulnérabilités de l'application et de ses dépendances. Lorsque vous exécutez un build à l'aide du service OCI DevOps, vous pouvez démarrer une analyse de code pour une nouvelle validation dans le référentiel de code. L'audit de vulnérabilité est effectué lors de la phase de build géré.

Dans le fichier de spécification de build, une étape d'audit de vulnérabilité de type VulnerabilityAudit est ajoutée. Le pipeline de build DevOps utilise cette étape lors de l'exécution de build pour l'analyse de code. Les attributs de cette étape sont répertoriés comme suit :

Nom de l'attribut Description Prise en charge de la valeur paramétrée
name (facultatif) Nom de l'étape. N/A
vulnerabilityAuditName (facultatif) Nom de la ressource d'audit de vulnérabilité. Oui
vulnerabilityAuditCompartmentId (facultatif)

Valeur par défaut : knowledgeBaseCompartmentId

 OCID du compartiment dans lequel la ressource d'audit doit être créée. Oui
knowledgeBaseId (obligatoire) OCID de l'espace réservé/de la balise permettant de tenir à jour les détails de la ressource d'audit de vulnérabilité. Ressource parent de la ressource d'audit de vulnérabilité. Oui
configuration/buildType (obligatoire) Type d'outil de build. N/A
configuration/pomFilePath (obligatoire) Emplacement du fichier pom.xml. Oui
configuration/packagesToIgnore (facultatif) Liste des packages Java à ignorer lors du calcul du résultat de l'analyse pendant l'audit des vulnérabilités. N/A
configuration/maxPermissibleCvssV2Score (facultatif)

Valeur par défaut : 0.0

 Score CVSS v2 maximal autorisé pour l'audit de vulnérabilité. Tout élément situé au-dessus de cette configuration doit marquer le build comme Failed. N/A
configuration/maxPermissibleCvssV3Score (facultatif)

Valeur par défaut : 0.0

 Score CVSS v3 maximal autorisé pour l'audit de vulnérabilité. Tout élément situé au-dessus de cette configuration doit marquer le build comme Failed. N/A
freeFormTags (facultatif) Accepte une paire clé-valeur. N/A

Variables système prédéfinies

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

Variable Description
OCI_STAGE_ID OCID de la phase en cours.
OCI_PIPELINE_ID OCID du pipeline de build en cours.
OCI_BUILD_RUN_ID OCID de l'exécution de build en cours.
OCI_TRIGGER_COMMIT_HASH Hachage de validation du déclencheur en cours.
OCI_TRIGGER_SOURCE_BRANCH_NAME Branchement qui déclenche le build.
OCI_TRIGGER_SOURCE_URL URL de référentiel qui a déclenché le build.
OCI_TRIGGER_EVENT_TYPE Déclencheur qui a démarré l'événement.
OCI_PRIMARY_SOURCE_DIR Répertoire de travail par défaut du build (répertoire de travail de la source principale).
OCI_WORKSPACE_DIR Valeur du répertoire de travail. Contient /workspace comme valeur par défaut.
${OCI_WORKSPACE_DIR}/<source-name> Chemin de répertoire de la source de build.

source-name est le nom de la source de build indiqué par l'utilisateur lors de la création de la phase de build.
OCI_BUILD_STAGE_NAME Nom de la phase de build.
OCI_PRIMARY_SOURCE_NAME Nom de la source de build principale.
OCI_PRIMARY_SOURCE_COMMIT_HASH Hachage de validation de la source de build principale utilisé dans l'exécution de build en cours.
OCI_PRIMARY_SOURCE_URL URL de la source de build principale.
OCI_PRIMARY_SOURCE_BRANCH_NAME Branchement de la source de build principale utilisé dans l'exécution de build en cours.

Exemples de spécification de build

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
Remarque

Pour créer des applications Java hautes performances, vous pouvez utiliser Oracle GraalVM dans le pipeline de build. Pour installer et utiliser Oracle GraalVM dans le pipeline de build DevOps, vous devez mettre à jour le fichier de spécification de build. Pour plus d'informations et des exemples, reportez-vous à Utilisation d'Oracle GraalVM dans les pipelines de build DevOps.