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 des primären Build-Quellverzeichnisses gespeichert und bei der Ausführung einer Build-Pipeline verwendet. Der Name der Datei lautet "build_spec.yml" oder "build_spec.yaml". Wenn die Build-Spezifikation nicht im Root-Verzeichnis vorhanden ist, müssen Sie beim Hinzufügen der Phase "Verwalteten Build" einen relativen Pfad der 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 Sicherheitsrisikoaudit beschreibt die Schwachstellen der Anwendung und ihre Abhängigkeiten. Wenn Sie einen Build mit dem OCI DevOps-Service ausführen, können Sie einen Codescan 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