CI/CD-Referenz: Jenkins

Auf dieser Seite erhalten Sie eine vollständige deklarative Jenkinsfile , die die CLI installiert, sich mit einer externen Anwendung authentifiziert, eine UiPath-Lösung verpackt und veröffentlicht, sie im Orchestrator bereitstellt und eine Test Manager-Suite ausführt. Platzieren Sie ihn im Stammverzeichnis Ihres Repositorys, erstellen Sie einen übereinstimmenden Jenkins-Anmeldeinformationseintrag und die Pipeline wird ausgeführt.

Für die zugrundeliegenden Prinzipien – Authentifizierung, Zwischenspeicherung, Vorinstallation des Tools, Versionsheft – siehe Anleitung: Bereitstellen von CI im Orchestrator. Diese Seite konzentriert sich auf die Jenkins-Syntax, einschließlich der Bits (withCredentials, stash / unstash, Agent-Auswahl), die Jenkins-spezifisch sind.

Voraussetzungen

Vor dem Kopieren der Jenkins-Datei:

1. Erstellen Sie eine externe Anwendung in UiPath mit den OR.* Scopes, die Ihre Pipeline benötigt. Siehe Authentifizierung – Flow 2.
2. Speichern Sie die Geheimnisse in Jenkins-Anmeldeinformationen:
   • Verwalten von Jenkins → Anmeldeinformationen → System → Globale Anmeldeinformationen (uneingeschränkt).
   • Fügen Sie zwei Geheimnis-Texteinträge mit den IDs UIPATH_CLIENT_ID und UIPATH_CLIENT_SECRET hinzu.
   • Fügen Sie einen Nur-Text- oder Geheimen Texteintrag mit ID UIPATH_TENANT (dem Mandantennamen; nicht streng geheim, aber die Anmeldeinformationen sind der portabelste Ort) hinzu.
3. Anforderungen an Agents. Die Pipeline geht von einem Agent mit der Bezeichnung linux mit Node.js 18+ und npm auf dem PATH aus. Sehen Sie sich unten die alternativen Agent-Optionen an, wenn Sie unter Windows oder in einem Container arbeiten.
4. Stellen Sie ein Test Manager-Projekt und einen Testsatz bereit, wenn Sie die Testphase durchführen möchten. Fügen Sie TEST_SET_KEY und PROJECT_KEY als zusätzliche Anmeldeinformationen (oder als Pipelineparameter) hinzu.

Jenkins-Datei

pipeline {
  agent none

  options {
    timestamps()
    buildDiscarder(logRotator(numToKeepStr: '30'))
    disableConcurrentBuilds()
  }

  environment {
    CLI_VERSION      = '1.0.0'
    SOLUTION_NAME    = 'my-solution'
    SOLUTION_DIR     = 'my-solution'
    OUTPUT_DIR       = 'dist'
    SOLUTION_VERSION = "1.2.0-ci.${env.BUILD_NUMBER}"

    // npm global prefix for a user-local, no-sudo install
    NPM_PREFIX       = "${env.WORKSPACE}/.npm-global"
  }

  stages {

    stage('Build') {
      agent { label 'linux' }
      steps {
        checkout scm
        sh '''#!/usr/bin/env bash
          set -euo pipefail

          mkdir -p "$NPM_PREFIX"
          npm config set prefix "$NPM_PREFIX"
          export PATH="$NPM_PREFIX/bin:$PATH"

          if ! command -v uip >/dev/null; then
            npm install -g "@uipath/cli@${CLI_VERSION}"
          fi

          uip --version

          mkdir -p "$OUTPUT_DIR"
          uip solution pack "$SOLUTION_DIR" "$OUTPUT_DIR" \
            --name "$SOLUTION_NAME" \
            --version "$SOLUTION_VERSION"
        '''

        // Carry the .zip to the Deploy stage, which runs on a fresh agent.
        stash name: 'solution-zip', includes: "${OUTPUT_DIR}/*.zip"

        archiveArtifacts artifacts: "${OUTPUT_DIR}/*.zip", fingerprint: true
      }
    }

    stage('Deploy') {
      agent { label 'linux' }
      steps {
        unstash 'solution-zip'

        withCredentials([
          string(credentialsId: 'UIPATH_CLIENT_ID',     variable: 'UIPATH_CLIENT_ID'),
          string(credentialsId: 'UIPATH_CLIENT_SECRET', variable: 'UIPATH_CLIENT_SECRET'),
          string(credentialsId: 'UIPATH_TENANT',        variable: 'UIPATH_TENANT')
        ]) {
          sh '''#!/usr/bin/env bash
            set -euo pipefail

            mkdir -p "$NPM_PREFIX"
            npm config set prefix "$NPM_PREFIX"
            export PATH="$NPM_PREFIX/bin:$PATH"

            if ! command -v uip >/dev/null; then
              npm install -g "@uipath/cli@${CLI_VERSION}"
            fi

            uip login \
              --client-id env.UIPATH_CLIENT_ID \
              --client-secret env.UIPATH_CLIENT_SECRET \
              --tenant "$UIPATH_TENANT"

            ARTIFACT=$(find "$OUTPUT_DIR" -maxdepth 1 -name "*.zip" | head -1)
            uip solution publish "$ARTIFACT"

            uip solution deploy run \
              --name "${SOLUTION_NAME}-${BUILD_NUMBER}" \
              --package-name "$SOLUTION_NAME" \
              --package-version "$SOLUTION_VERSION" \
              --folder-name MySolution \
              --folder-path Shared
          '''
        }
      }
    }

    stage('Test') {
      when {
        expression { return env.TEST_SET_KEY?.trim() }
      }
      agent { label 'linux' }
      steps {
        withCredentials([
          string(credentialsId: 'UIPATH_CLIENT_ID',     variable: 'UIPATH_CLIENT_ID'),
          string(credentialsId: 'UIPATH_CLIENT_SECRET', variable: 'UIPATH_CLIENT_SECRET'),
          string(credentialsId: 'UIPATH_TENANT',        variable: 'UIPATH_TENANT'),
          string(credentialsId: 'TEST_SET_KEY',         variable: 'TEST_SET_KEY'),
          string(credentialsId: 'PROJECT_KEY',          variable: 'PROJECT_KEY')
        ]) {
          sh '''#!/usr/bin/env bash
            set -euo pipefail

            mkdir -p "$NPM_PREFIX"
            npm config set prefix "$NPM_PREFIX"
            export PATH="$NPM_PREFIX/bin:$PATH"

            if ! command -v uip >/dev/null; then
              npm install -g "@uipath/cli@${CLI_VERSION}"
            fi

            uip login \
              --client-id env.UIPATH_CLIENT_ID \
              --client-secret env.UIPATH_CLIENT_SECRET \
              --tenant "$UIPATH_TENANT"

            EXECUTION_ID=$(uip tm testsets run \
              --test-set-key "$TEST_SET_KEY" \
              --output-filter "Data.ExecutionId" \
              --output plain)

            echo "started execution $EXECUTION_ID"

            if ! uip tm wait \
              --execution-id "$EXECUTION_ID" \
              --project-key "$PROJECT_KEY" \
              --timeout 1800; then
              code=$?
              case "$code" in
                2) echo "test run did not finish within 30 minutes" >&2; exit 2 ;;
                *) echo "wait failed (exit $code)" >&2; exit "$code" ;;
              esac
            fi

            uip tm report get \
              --execution-id "$EXECUTION_ID" \
              --project-key "$PROJECT_KEY"

            FAILED=$(uip tm report get \
              --execution-id "$EXECUTION_ID" \
              --project-key "$PROJECT_KEY" \
              --output-filter "Data.Failed" \
              --output plain)

            if [ "$FAILED" -gt 0 ]; then
              echo "$FAILED test case(s) failed" >&2
              exit 1
            fi
          '''
        }
      }
    }
  }

  post {
    always {
      // Best-effort cleanup; uip logout only matters on a persistent agent.
      node('linux') {
        sh '''
          if command -v uip >/dev/null; then
            uip logout || true
          fi
        '''
      }
    }
  }
}

Exemplarische Vorgehensweise

Einrichtung auf höchster Ebene

• agent none gibt oben an, dass die Pipeline keinen Standard-Agent hat; Jede Phase wählt sich selbst mit agent { label 'linux' } aus. Auf diese Weise können Sie den Build auf einen Agent mit hoher Kapazität und die Bereitstellung auf einen gesperrten Agent stellen, wenn Ihre Infrastruktur sie auf diese Weise trennt.
• options – timestamps() fügt jeder Konsolenzeile [2026-04-24T10:30:12] Präfixe hinzu, was das Debuggen langer Ausführungen erheblich erleichtert. disableConcurrentBuilds() verhindert, dass zwei Bereitstellungen in denselben Orchestrator-Ordner laufen.
• environment -Block – das gleiche Muster wie die anderen Schemas: CLI_VERSION anheften, SOLUTION_VERSION aus BUILD_NUMBER berechnen und das globale Präfix von npm in den Arbeitsbereich weiterleiten, sodass Installationen per Build erfolgen und kein sudo benötigt wird.

Phase erstellen

• checkout scm – Jenkins benötigt dies explizit in einer deklarativen Pipeline.
• Installationsschritt – der gleiche if ! command -v uip Schutz wie bei anderen Plattformen. Das Workspace-Local-NPM-Präfix ($NPM_PREFIX) bedeutet, dass jeder Build neu beginnt; keine Zwischenspeicherung zwischen Ausführungen. Wenn Ihre Jenkins-Agents persistent sind und Sie die CLI zwischenspeichern möchten, verwenden Sie entweder das Job Cacher-Plugin oder legen Sie NPM_PREFIX auf einen Pfad auf dem Agent anstelle von ${env.WORKSPACE} fest.
• Packschritt – direkt uip solution pack mit einer expliziten Version.
• stash name: 'solution-zip' – Das ist das Jenkins-spezifische Teil. Im Gegensatz zu GitHub Actions-Artefakten oder Azure Pipelines publish ist ein stash auf die Pipelineausführung beschränkt und überläuft alle Phasen hinweg, ohne dass der Arbeitsbereich zum Fortsetzen erforderlich ist. Der Stash verwendet ein Glob (${OUTPUT_DIR}/*.zip), sodass er den Dateinamen aufnimmt, uip solution pack erzeugt. Jede Phase, die die .zip -Aufrufe unstash 'solution-zip' benötigt, ruft zu Beginn auf. Siehe die Jenkins-Dokumentation zu stash / unstash.
• archiveArtifacts – Eine Kopie von .zip wird auch auf der Buildseite zum Herunterladen durch Menschen angezeigt. fingerprint: true kann Jenkins sie auftragsübergreifend nachverfolgen.

Bereitstellungsphase

• unstash 'solution-zip' stellt .zip im Arbeitsbereich wieder her. In Kombination mit einem neuen Agenten trennt dies „Build-Kontext“ sauber vom „Bereitstellungskontext“.
• withCredentials bindet drei Anmeldeinformationseinträge an Umgebungsvariablen, die für den Block sh sichtbar sind. Der Abschluss ist die anmeldeinformationssichere Grenze – Werte werden im Konsolenprotokoll maskiert und nicht an einen Schritt außerhalb dieses Blocks weitergegeben. Verwenden Sie dies für jeden uip -Aufruf, der mit dem Orchestrator kommuniziert.
• uip login verwendet env.UIPATH_CLIENT_ID / env.UIPATH_CLIENT_SECRET – das Präfix env.VAR_NAME liest die von withCredentials festgelegte Variable. Siehe Authentifizierung – das Präfix env.VAR_NAME. Interpolieren Sie das Geheimnis niemals direkt in die Befehlszeile (--client-secret "$UIPATH_CLIENT_SECRET") – wodurch es in den gerenderten Shell-Befehl und, unter einigen Protokollierungskonfigurationen, in die Konsolenausgabe eingebettet wird.
• Veröffentlichen und Bereitstellen – uip solution publish und dann uip solution deploy run. --name "${SOLUTION_NAME}-${BUILD_NUMBER}" macht jede Bereitstellung bis zu ihrem Jenkins-Build nachverfolgbar.

Testphase

Gruppiert durch when { expression { return env.TEST_SET_KEY?.trim() } } – Wenn Sie die TEST_SET_KEY -Anmeldeinformationen nicht festlegen (oder leer lassen), wird die Phase übersprungen. Der Shell-Block ist das kanonische Muster für den Start → warten → überprüfen von So: Ausführen von Tests über die CLI:

1. uip tm testsets run startet und gibt ein ExecutionId zurück.
2. uip tm wait wird blockiert, bis die Ausführung einen Endzustand erreicht. Bei wait bedeutet der Exitcode 2 eine Zeitüberschreitung (kein Authentifizierungsfehler – es handelt sich um eine domänenspezifische Wiederverwendung des Codes).
3. uip tm report get liest Data.Failed und die Shell beendet 1 wenn ein Test fehlgeschlagen ist.

poste { immer }

Nach bestem Wissen und Gewissen uip logout. Bei flüchtigen Agents ist dies nicht notwendig; Auf einem persistenten Agent wird der „workspace-local“-Ordner .uipath/ gelöscht, sodass ein späterer Auftrag im selben Arbeitsbereich eine veraltete Sitzung nicht wiederverwendet. || true übernimmt den Fehler, wenn uip nie installiert wurde (der Build ist vor der Installation fehlgeschlagen).

Häufige Varianten

Agent-Variablen

• Windows-Agent – ersetzen Sie sh durch bat und übersetzen Sie die Bash-Skripte in cmd.exe oder PowerShell. Das Präfix env. und jeder uip -Befehl sind identisch; Nur die umgebende Shell ändert sich. Siehe Installieren der UiPath CLI – Windows.
• Docker-Agent – agent { docker { image 'node:20' } } bietet Ihnen eine neue Knoten-Runtime pro Build mit einer Agent-Konfiguration von Null. Fügen Sie args '-u root' hinzu, wenn Sie sudo-freie globale npm-Installationen in einem Stamm-Image benötigen; Konfigurieren Sie andernfalls das NPM-Präfix für $WORKSPACE/.npm-global wie oben und überspringen Sie den Berechtigungslauf.
• Kubernetes-Plugin – Verwenden Sie eine Pod-Vorlage mit einem node:20 -Container und stellen Sie /root/.npm-global als PVC bereit, um die CLI zwischen Builds zwischenzuspeichern.

Umgebungenübergreifend heraufstufen

Verwandeln Sie jede Umgebung in eine eigene Phase und verwenden Sie dieselbe stash wieder:

stage('Deploy stage') {
  agent { label 'linux' }
  steps {
    unstash 'solution-zip'
    withCredentials([string(credentialsId: 'UIPATH_STAGE_CLIENT_ID', variable: 'UIPATH_CLIENT_ID'), ...]) {
      sh '...deploy to stage tenant...'
    }
  }
}

stage('Approval') {
  steps {
    input message: 'Deploy to production?', ok: 'Deploy'
  }
}

stage('Deploy prod') {
  agent { label 'linux' }
  steps {
    unstash 'solution-zip'
    withCredentials([string(credentialsId: 'UIPATH_PROD_CLIENT_ID', variable: 'UIPATH_CLIENT_ID'), ...]) {
      sh '...deploy to prod tenant...'
    }
  }
}

Der Schritt input hält die Pipeline an, bis ein Mensch auf „Bereitstellen“ klickt. Verwenden Sie die Matrix-Autorisierungsstrategie von Jenkins, um einzuschränken, wer genehmigen kann. Tiefere Abdeckung bei der Anleitung: Packen und Veröffentlichen einer Lösung – Bewerben eines Pakets für mehrere Mandanten.

Rollback

Fügen Sie einen parametrisierten Auftrag hinzu – Jenkins → Neues Element → Pipeline → Dieses Projekt ist parametrisiert → Parameter (String) → „ROLLback_VERSION“ – und fügen Sie eine beaufsichtigte Phase hinzu:

stage('Rollback') {
  when { expression { return params.ROLLBACK_VERSION?.trim() } }
  agent { label 'linux' }
  steps {
    withCredentials([/* UIPATH_* credentials */]) {
      sh '''#!/usr/bin/env bash
        set -euo pipefail
        # …install + login…

        uip solution deploy run \
          --name "${SOLUTION_NAME}-rollback" \
          --package-name "$SOLUTION_NAME" \
          --package-version "$ROLLBACK_VERSION" \
          --folder-name MySolution \
          --folder-path Shared
      '''
    }
  }
  environment {
    ROLLBACK_VERSION = "${params.ROLLBACK_VERSION}"
  }
}

Triggern Sie von der Buildseite mit Build with Parameters. Informationen zum destruktiven Rollback (Deinstallieren + Löschen des Artefakts) finden Sie unter Anleitung: Packen und Veröffentlichen einer Lösung – Rollback.

Häufige Fallstricke

• withCredentials -Scoping. Anmeldeinformationen sind nur innerhalb des Abschlusses verfügbar. Wenn Sie uip login innerhalb von withCredentials und uip solution publish außerhalb aufrufen, hat der zweite Befehl keine Sitzung. Behalten Sie den gesamten CLI-Block in einem withCredentials bei.
• stash bevor Sie Agents wechseln. Ein in einer Phase deklariertes stash ist in späteren Phasen nur verwendbar, wenn der Stash-Schritt vor dem Wechsel des Agents abgeschlossen wurde. Wenn der Shell-Block der Phase Build vor stash nicht aber Null verlässt, schlagen spätere Phasen bei unstash fehl. Wenn Sie stash außerhalb des sh -Blocks platzieren – wie in diesem Konzept – wird sichergestellt, dass er unabhängig vom Shell-Ergebnis auf einem sauberen Agent ausgeführt wird.
• || true zur falschen Zeit. Der uip logout || true in post ist sicher, da der einzige Fehlermodus „uip wurde nie installiert“ ist. Durch frühere Phasen || true nicht hinzufügen – es verbergen echte Fehler.
• sh strikten Modus. Starten Sie das Bash-Skript jedes sh -Blocks mit #!/usr/bin/env bash und set -euo pipefail. Die standardmäßige Jenkins-Shell ist /bin/sh und unterstützt pipefail nicht. Siehe Skriptmuster – Strikte Shell-Optionen.
• Mehrzeilige Zeichenfolgen in Verbindung. Verwenden Sie nach Möglichkeit dreifach angegebene Zeichenfolgen mit einfachen Anführungszeichen ('''...''') für Shell-Textkörper – sie interpolieren $VAR nicht, daher wird die Variable mit Bash und nicht mit Den extrahieren erweitert. Dadurch wird eine häufige Klasse von „Variablen ist leer“-Fehlern vermieden. Verwenden Sie für Werte, die Greifen zur Kompilierungszeit der Pipeline ausfüllen sollen, ${env.SOME_VAR} explizit.

Siehe auch

• Anleitung: Bereitstellen von CI – plattformagnostische Anleitung für Orchestrator .
• So: Packen und Veröffentlichen einer Lösung – Versionierung und Rollback.
• So: Ausführen von Tests über die CLI – das Muster Starten → Warten → Verifizieren.
• CI/CD-Rezept: Azure Pipelines, GitHub Actions, GitLab CI – die gleiche Pipeline in anderen Plattformen.