Oracle Cloud Infrastructure-Dokumentation

Build-Spezifikation

Die Build-Spezifikation enthält Build-Schritte und -Einstellungen, die von der Build-Pipeline zum Ausführen eines Builds verwendet werden.

Die Build-Spezifikation wird in YAML geschrieben. Die Build-Spezifikation wird standardmäßig im Root-Verzeichnis der primären Build-Quelle gespeichert und bei einer Build-Pipeline verwendet. Der Name der Datei lautet "build_spec.yml" oder "build_spec.yaml". Wenn die Build-Spezifikation im Root-Verzeichnis nicht vorhanden sind, müssen Sie beim Hinzufügen der Phase "Verwalteter Build" einen relativen Pfad für die Datei angeben.

Die Build-Spezifikation ist in folgende Abschnitte unterteilt:

  • Konfiguration des Build Runners
  • Setup der Umgebungsvariablen
  • Eingabeartefakte
  • Schritte, die sequenziell ausgeführt werden müssen
  • Ausgabeartefakte

Build-Spezifikationssyntax

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
Hinweis

sudo ist auf dem Build-Runner-Host nicht verfügbar. Wenn Sie Superuser-Berechtigungen benötigen, führen Sie den Build-Schritt als Root-Benutzer aus.

Build-Spezifikationsparameter

Im Folgenden sind die Build-Spezifikationsparameter und die zugehörigen Details aufgeführt:

Parameter Beschreibung
version Obligatorisch. Gibt die Version der Build-Spezifikation an. Eine fehlende oder ungültige Version führt zu einem Fehler in der Build-Phase.

Der unterstützte Wert lautet 0.1.
component Obligatorisch. Gibt eine bestimmte Komponente in DevOps an. Ein fehlender oder ungültiger Wert führt zu einem Build-Fehler.

Der unterstützte Wert lautet build.
timeoutInSeconds Optional. Gibt den Timeout für die gesamte Build-Spezifikationsdatei an. Jeder "Schritt" kann optional auch einen eigenen Timeoutwert haben.

Wenn kein Wert angegeben ist, wird der Standardwert "8 Stunden" verwendet. Der maximal zulässige Wert beträgt 8 Stunden.
shell Optional. Gibt die Shell an, die auf der globalen Ebene der Build-Spezifikation verwendet werden soll. Der Wert kann optional auf Schrittebene überschrieben werden.

Zulässige Werte sind /bin/sh und bash. Wenn kein Wert angegeben ist, wird der Standardwert bash verwendet.
failImmediatelyOnError Optional. Gibt an, ob der Build fortgesetzt werden muss, wenn ein Befehl im Schritt mit einem Exit-Wert ungleich Null nicht erfolgreich verläuft. Wenn kein Wert angegeben ist, lautet der Standardwert false, und der Schritt wird fortgesetzt. Zulässige Werte sind true und false. OCI empfiehlt, den Wert dieses Attributs auf true zu setzen.
env

Optional. Sie können benutzerdefinierte Variablen definieren. Drei Variablentypen werden unterstützt:

  • env/variables: Optional. Der Schlüssel muss eine Zeichenfolge und mit POSIX-Umgebungsvariablen konform sein. Der Wert kann eine beliebige Zeichenfolge sein. Der Geltungsbereich dieser Variablen ist die Ausführung der Build-Spezifikationsdatei. Eine Änderung des Variablenwertes ist in den nachfolgenden Schritten sichtbar. Diese Variablen sind als Umgebungsvariablen für alle Schritte innerhalb der Build-Spezifikationsdatei verfügbar.

    Wenn der Wert der Variablen Zeilenvorschub- (\n) oder Zeilenschaltungszeichen (\r) enthält, werden diese in den folgenden Schritten durch Leerzeichen ersetzt.

  • env/vaultVariables: Optional. Der Schlüssel muss eine Zeichenfolge und mit POSIX-Umgebungsvariablen konform sein. Der Wert muss eine OCID des Secrets aus dem Vault sein. Der Vault und die Build-Pipeline müssen demselben Mandanten angehören. Der Mandant muss über die entsprechende Policy verfügen, damit Build-Pipelineressourcen auf das Secret zugreifen können.

    Der Geltungsbereich dieser Variablen ist die Ausführung der Build-Spezifikationsdatei und steht in allen Schritten in der Datei zur Verfügung. Die Werte für diese Variablen werden aus dem Vault abgerufen und als Umgebungsvariablen für alle Schritte in der Build-Spezifikationsdatei zur Verfügung gestellt.

  • env/exportedVariables: Optional. Eine Liste der Variablen kann hier deklariert werden. Der Name der Variablen muss eine Zeichenfolge und mit POSIX-Umgebungsvariablen konform sein. Der Wert kann in einem der Schritte in der Build-Spezifikationsdatei zugewiesen werden. Der Geltungsbereich dieser Variablen ist die Build-Pipeline. Exportierte Variablen sind in den nachfolgenden Phasen dieser Pipeline verfügbar.
inputArtifacts

Optional. Wird verwendet, um eine Liste der Eingabeartefakte zu definieren, die für die Ausführung der aktuellen Build-Phase erforderlich sind.

Unterstützt die folgenden Typen von Eingabeartefakten:
  • Artefakte aus einer der vorherigen Build-Phasen
  • Artefakte aus externen herunterladbaren HTTP-URLs
  • Generische Artefakte aus Artifact Registry

Folgende Parameter sind verfügbar:

  • inputArtifacts/*/url: Optional. Die externe herunterladbare HTTP-URL des Eingabeartefakts muss angegeben werden. Die URL muss öffentlich verfügbar sein. Die Authentifizierung/Autorisierung wird derzeit nicht unterstützt.
  • inputArtifacts/*/name: Obligatorisch. Wenn die URL nicht vorhanden ist, wird dieser Name verwendet, um nach den Artefakten zu suchen, die von den vorherigen Build-Phasen in dieser Pipeline erstellt wurden. Daher müssen "outputArtifacts/name" und "inputArtifacts/name" übereinstimmen, um ein bestimmtes Artefakt zu konsumieren, das von der vorherigen Build-Phase in der Pipeline erzeugt wurde.
  • inputArtifacts/*/location: Erforderlich. Ein Zielpfad des lokalen Dateisystems, in den das Eingabeartefakt heruntergeladen werden muss. Der Pfad kann mit einer der folgenden Methoden angegeben werden:
    • ${OCI_PRIMARY_SOURCE_DIR}/pom.xml
    • ${OCI_WORKSPACE_DIR}/[source-name]/pom.xml
    • /workspace/[source-name]/pom.xml
    • Relativer Pfad vom Projekt-Home, pom.xml

    Mit jedem der Werte wird das Eingabeartefakt mit dem Dateinamen pom.xml in das primäre Quell-Home-Verzeichnis heruntergeladen.

    Der Speicherort unterstützt keine exportedVariables oder Pipelinevariablen.

  • inputArtifacts/*/type: Obligatorisch. Der Typ des Eingabeartefakts, das heruntergeladen werden muss. Zulässige Werte sind URL, STAGE_ARTIFACT und GENERIC_ARTIFACT.
  • inputArtifacts/*/artifactld: Erforderlich. Die OCID des Artefakts. Wenn Sie die OCID angegeben haben, ignoriert die Build-Pipeline "registryId", "path" und "version".
  • inputArtifacts/*: Erforderlich. Die OCID der Artefakt-Registry.
  • inputArtifacts/*/path: Obligatorisch. Der Zielpfad des Artefakts.
  • inputArtifacts/*/version: Obligatorisch. Die Version des Artefakts.

Hinweis: Für den Eingabeartefakttyp GENERIC_ARTIFACT können Sie als obligatorischen Parameter entweder die OCID des Artefakts oder eine Kombination aus Registry-ID, Pfad und Artefaktversion angeben.
steps

Obligatorisch. In diesem Abschnitt wird eine Liste der Schritte definiert, die ausgeführt werden müssen.

  • steps/*/type: Obligatorisch. Gibt den Schritttyp an. Unterstützt die folgenden Werte: Command, VulnerabilityAudit. Weitere Informationen finden Sie unter Schritttypen.
  • steps/*/name: Optional. Ein benutzerfreundlicher Name für den Schritt.
outputArtifacts

Optional. Gibt die Artefakte an, die in der Build-Phase erzeugt werden. Die in diesem Abschnitt als Ausgabe erzeugten Artefakte werden für die Gültigkeitsdauer der aktuellen Build-Ausführung gespeichert. Sie können in den nachfolgenden Phasen der Build-Pipeline verwendet werden.

  • outputArtifacts/*/name: Obligatorisch. Der Name kann Kleinbuchstaben (a-z), Großbuchstaben (A-Z), Unterstriche (_) und Bindestriche (-) enthalten. Der Name ist die eindeutige ID für das Ausgabeartefakt. In den späteren Phasen der Build-Pipeline wird der Name verwendet, um ein Artefakt zu identifizieren.
  • outputArtifacts/*/type: Erforderlich. Zulässige Werte sind BINARY und DOCKER_IMAGE.

    BINARY: Gibt Binärdateien als Ausgabeartefakte an.

    outputArtifacts/*/location: Ein Quellpfad des lokalen Dateisystems, in dem das Ausgabeartefakt gefunden werden kann. Der Pfad kann mit einer dieser Methoden angegeben werden (vorausgesetzt, die Datei pom.xml ist im primären Quell-Home-Verzeichnis vorhanden):

    • ${OCI_PRIMARY_SOURCE_DIR}/pom.xml
    • ${OCI_WORKSPACE_DIR}/[source-name]/pom.xml
    • /workspace/[source-name]/pom.xml
    • Relativer Pfad vom Projekt-Home, pom.xml

    Wenn die Datei am angegebenen Speicherort nicht gefunden wird, ist die Build-Phase nicht erfolgreich.

    DOCKER_IMAGE: Gibt ein Docker-Image als Ausgabeartefakt an.

    outputArtifacts/*/location: Ein Docker-Imagetag, das basierend auf einem der Schritte in der Build-Spezifikationsdatei erstellt wird.

    Beispiel: Wenn in einem der Schritte in der Build-Spezifikationsdatei ein Docker-Image basierend auf docker build -t iad.ocir.io/id204we8d65n/hello-world:1.0 erstellt wird, muss das Speicherortfeld iad.ocir.io/id204we8d65n/hello-world:1.0 enthalten, damit dieses Artefakt erzeugt wird.

    Das Image muss erstellt oder abgerufen und in einem der Build-Spezifikationsschritte zur Verfügung gestellt werden. Andernfalls verläuft der Schritt outputArtifact nicht erfolgreich, und die Build-Phase kann möglicherweise auch nicht erfolgreich ausgeführt werden.

    Der Speicherort unterstützt keine exportedVariables oder Pipelinevariablen.

Schritttypen

Befehl

Attributname Beschreibung
command Sowohl einzeilige als auch mehrzeilige Befehle werden unterstützt. Alle in einem Schritt angegebenen Befehle werden in derselben Shell-Session ausgeführt. Basierend auf dem Wert steps/*/shell kann es sich um Shell- oder Bash-Befehle handeln.

Fail-Fast ist nicht aktiviert. Damit der Schritt erfolgreich verläuft, wird die Ausgabe des letzten Befehls in einem Schritt berücksichtigt. Wenn der Exitcode des letzten Befehls 0 ist, wird der Schritt als erfolgreich betrachtet.
timeoutInSeconds (Optional) Gibt den Timeout für den Schritt an. Ist kein Wert angegeben, wird der Wert vom globalen timeoutInSeconds-Parameter übernommen. Der maximal zulässige Wert beträgt 8 Stunden.
shell (Optional) Gibt den Shell-Typ des aktuellen Schritts an. Ist kein Wert angegeben, wird der Wert vom globalen shell-Parameter übernommen. Zulässige Werte sind /bin/sh und shell.
onFailure (Optional) Eine Liste der Schritte, die bei einem Fehler ausgeführt werden müssen, damit die Build-Phase ordnungsgemäß beendet wird. Diese Schritte werden ausgeführt, wenn der entsprechende Schritt nicht erfolgreich verläuft, und nachdem die Ausführung der Build-Spezifikation beendet wurde.

Die Bearbeitung des Fehlers wirkt sich nicht auf den Status der Build-Phase aus. Wenn einer der Schritte nicht erfolgreich verläuft, verbleibt die Build-Phase im Status failed, obwohl der Fehler mit dem onFailure-Block bearbeitet wurde.
failImmediatelyOnError (Optional) Gibt an, ob der Build fortgesetzt werden muss, wenn ein Befehl im Schritt mit einem Exit-Wert ungleich Null nicht erfolgreich verläuft. Wenn kein Wert angegeben ist, lautet der Standardwert false, und der Schritt wird fortgesetzt. Zulässige Werte sind true und false. OCI empfiehlt, den Wert dieses Attributs auf true zu setzen.

Der unter steps definierte Attributwert failImmediatelyOnError hat Vorrang vor demselben Attributwert, der außerhalb von steps definiert wurde.

Sicherheitslückenaudit

Ein Sicherheitslückenaudit beschreibt die Sicherheitslücken der Anwendung und ihre Abhängigkeiten. Wenn Sie einen Build mit dem OCI DevOps-Service ausführen, können Sie einen Code-Scan für einen neuen Commit im Code-Repository starten. Der Sicherheitslückenaudit findet in der Phase "Verwalteter Build" statt.

In der Build-Spezifikationsdatei wird ein Sicherheitslückenauditschritt vom Typ VulnerabilityAudit hinzugefügt, den die DevOps-Build-Pipeline während der Build-Ausführung für den Code-Scan verwendet. Die Attribute dieses Schritts werden wie folgt aufgeführt:

Attributname Beschreibung Unterstützung parametrisierter Werte
name (Optional) Name des Schritts. Nicht zutreffend
vulnerabilityAuditName (Optional) Name der Sicherheitslückenauditressource. Ja
vulnerabilityAuditCompartmentId (Optional)

Standardwert: knowledgeBaseCompartmentId

OCID des Compartments, in dem die Auditressource erstellt werden muss. Ja
knowledgeBaseId (Obligatorisch) OCID des Platzhalters/Tags zum Verwalten der Details der Sicherheitslückenauditressource. Übergeordnete Ressource der Sicherheitslückenauditressource. Ja
configuration/buildType (Obligatorisch) Build-Tooltyp. Nicht zutreffend
configuration/pomFilePath (Obligatorisch) Speicherort der pom.xml-Datei. Ja
configuration/packagesToIgnore (Optional) Liste der Java-Packages, die bei der Berechnung des Scanergebnisses während des Sicherheitslückenaudits ignoriert werden sollen. Nicht zutreffend
configuration/maxPermissibleCvssV2Score (Optional)

Standardwert: 0.0

 Maximaler v2-CVSS-Score, der für das Sicherheitslückenaudit zulässig ist. Alle Elemente über dieser Konfiguration müssen den Build als Failed markieren. Nicht zutreffend
configuration/maxPermissibleCvssV3Score (Optional)

Standardwert: 0.0

 Maximaler v3-CVSS-Score, der für das Sicherheitslückenaudit zulässig ist. Alle Elemente über dieser Konfiguration müssen den Build als Failed markieren. Nicht zutreffend
freeFormTags (Optional) Akzeptiert Schlüssel/Wert-Paare. Nicht zutreffend

Vordefinierte Systemvariablen

DevOps stellt vordefinierte Systemvariablen mit Standardwerten bereit, die Sie wie Umgebungsvariablen in der Build-Spezifikation verwenden können.

Variable Beschreibung
OCI_STAGE_ID Die OCID der aktuellen Phase.
OCI_PIPELINE_ID Die OCID der aktuellen Build-Pipeline.
OCI_BUILD_RUN_ID Die OCID der aktuellen Build-Ausführung.
OCI_TRIGGER_COMMIT_HASH Commit-Hash des aktuellen Triggers.
OCI_TRIGGER_SOURCE_BRANCH_NAME Verzweigung, die den Build auslöst.
OCI_TRIGGER_SOURCE_URL Repository-URL, die den Build ausgelöst hat.
OCI_TRIGGER_EVENT_TYPE Trigger, der das Ereignis gestartet hat.
OCI_PRIMARY_SOURCE_DIR Standardarbeitsverzeichnis des Builds (Arbeitsverzeichnis der primären Quelle).
OCI_WORKSPACE_DIR Wert des Arbeitsverzeichnisses. Enthält /workspace als Standardwert.
${OCI_WORKSPACE_DIR}/<source-name> Verzeichnispfad der Build-Quelle.

source-name ist der Name der Build-Quelle, die vom Benutzer beim Erstellen der Build-Phase angegeben wird.
OCI_BUILD_STAGE_NAME Name der Build-Phase.
OCI_PRIMARY_SOURCE_NAME Name der primären Build-Quelle.
OCI_PRIMARY_SOURCE_COMMIT_HASH Der Commit-Hash der primären Build-Quelle, der in der aktuellen Build-Ausführung verwendet wird.
OCI_PRIMARY_SOURCE_URL URL der primären Build-Quelle.
OCI_PRIMARY_SOURCE_BRANCH_NAME Die Verzweigung der primären Build-Quelle, die in der aktuellen Build-Ausführung verwendet wird.

Beispiele für Build-Spezifikationen

Beispiel 1:

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

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

Beispiel 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

Beispiel3:

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
Hinweis

Um leistungsstarke Java-Anwendungen zu erstellen, können Sie Oracle GraalVM in der Build-Pipeline verwenden. Um Oracle GraalVM in der Build-Pipeline DevOps zu installieren und zu verwenden, müssen Sie die Build-Spezifikationsdatei aktualisieren. Weitere Informationen und Beispiele finden Sie unter Oracle GraalVM in DevOps-Build-Pipelines verwenden.