Skip to content
Home » ##vso task.setvariable: Der umfassende Leitfaden zur Steuerung von Variablen in Azure Pipelines

##vso task.setvariable: Der umfassende Leitfaden zur Steuerung von Variablen in Azure Pipelines

In modernen Continuous-Integration- und Continuous-Delivery-Umgebungen spielen Variablen eine zentrale Rolle. Sie ermöglichen es, Werte zu speichern, weiterzugeben und den Build- bzw. Release-Prozess flexibel zu gestalten. Der Befehl ##vso task.setvariable ist ein mächtiges Logging-Command in Azure DevOps Pipelines, das es Aufgaben (Tasks) erlaubt, Variablen zu setzen, die anschließend von nachfolgenden Tasks genutzt werden können. In diesem Leitfaden erfahren Sie, wie Sie ##vso task.setvariable sicher und effektiv einsetzen – von der Grundsyntax über fortgeschrittene Varianten bis hin zu Best Practices und Troubleshooting.

Was ist ##vso task.setvariable?

Der Ausdruck ##vso task.setvariable gehört zu den sogenannten Logging Commands in Azure Pipelines. Mit ihm schreibt eine Aufgabe eine Variable direkt in den Pipelines-Log, sodass der nachfolgende Task diese Variable auslesen oder weiterverarbeiten kann. Zweck ist es, dynamische Werte zu erzeugen, die erst im Verlauf des Builds oder Deployments bekannt werden – zum Beispiel das Ergebnis einer Berechnung, eine Build-Nummer, der Pfad zu einem Artefakt oder der aktuelle Timestamp.

Der generische Aufbau lautet typischerweise so:

##vso[task.setvariable variable=NAME;]WERT

Dabei steht NAME für den Namen der Variable und WERT für deren Inhalt. Die Semikolons trennen optionale Parameter voneinander. Das einfache Setzen einer Variablen kann bereits in vielen Fällen den Build erheblich vereinfachen, indem Sie fortlaufende Tasks voneinander abhängig machen, ohne harte Kopplungen einzugehen.

Syntax und Parameter von ##vso task.setvariable

In der Praxis finden Sie verschiedene Optionen, die das Verhalten von ##vso task.setvariable beeinflussen. Die wichtigsten Parameter sind:

  • variable: Der Name der zu gesetzenden Variable.
  • isSecret / issecret (true|false): Wenn gesetzt, wird der Wert in Logs maskiert. Nützlich bei sensiblen Werten wie Tokens oder Passwörtern.
  • isOutput (true|false): Markiert eine Variable als Output-Variable, damit sie von nachfolgenden Tasks in parallelen oder abhängigen Abläufen referenziert werden kann.
  • dependsOn oder weitere Kontexte (je nach Task-Engine): Spezifiziert ggf. Abhängigkeiten im Kontext von Multi-Stage-Pipelines.

Eine erweiterte, häufig verwendete Form ist:

##vso[task.setvariable variable=BUILD_NUMBER;issecret=false;]20240219.1

Hier wird BUILD_NUMBER auf den Wert 20240219.1 gesetzt, sichtbar in Logs, sofern isSecret nicht aktiviert ist. Um sensible Informationen zu schützen, verwenden Sie stattdessen issecret=true:

##vso[task.setvariable variable=AUTH_TOKEN;issecret=true;]s3cr3t_t0k3n

Unterschiede zwischen YAML- und klassischen Pipelines

In YAML-Pipelines erfolgt der Aufruf typischerweise direkt in der Skriptsprache der jeweiligen Aufgabe, z. B. Bash, PowerShell oder Node.js. Der Logging-Command wird dort wie im folgenden Beispiel genutzt:

steps:
- script: |
    echo "Setting a variable from a script"
    echo "##vso[task.setvariable variable=BuildBranch;]$(Build.SourceBranch)"
  displayName: "Setze Build-Branch-Variable"

Im klassischen UI-Workflow, bei dem Tasks in einer Sequenz aufgerufen werden, funktioniert der Logging-Command identisch – nur der Kontext unterscheidet sich geringfügig. Wichtig ist, dass der Befehl konsistent ausgeführt wird, damit nachfolgende Tasks die gesetzte Variable lesen können.

Praxisbeispiele: Typische Anwendungsfälle

Build-Nummer fortlaufend erhöhen

In vielen Projekten gibt es eine automatische Build-Nummer, die bei jedem Durchlauf inkrementiert wird. Mit ##vso task.setvariable lässt sich diese Nummer einfach an den nächsten Tasks weitergeben und dort zum Benennen von Artefakten oder Docker-Images verwenden.

BUILD_NUMBER=$(date +%Y%m%d.%H%M%S)
echo "##vso[task.setvariable variable=BUILD_NUMBER;]$BUILD_NUMBER"

Umgebungsabhängige Konfigurationen

Manchmal müssen Werte wie API-URLs oder Feature-Flags je nach Umgebung unterschiedlich gesetzt werden. Durch das Setzen über ##vso task.setvariable können spätere Schritte dieselben Variablennamen verwenden, unabhängig davon, welche Umgebung aktiviert ist.

if [ "$ENV" = "prod" ]; then
  echo "##vso[task.setvariable variable=API_BASE_URL;]https://api.prod.example.com"
else
  echo "##vso[task.setvariable variable=API_BASE_URL;]https://api.staging.example.com"
fi

Ausgabevariablen (Output-Variablen)

Für komplexe Pipelines ist es oft sinnvoll, Werte von einem Task an andere Tasks zu übergeben. Mit isOutput markieren Sie Variablen als Output-Variablen, die dann in abhängigen Jobs oder Stages genutzt werden können. Die Referenzierung erfolgt dann über die spezifische Struktur der Pipeline-Konfiguration.

##vso[task.setvariable variable=MyOutputVar;isOutput=true]SomeValue

Fehlerbehebung: Warum eine Variable nicht verfügbar ist

Oft treten Probleme auf, wenn Variablen nicht wie erwartet in nachfolgenden Tasks erscheinen. Hier einige häufige Ursachen und Lösungswege:

  • Variablen-Scope: Variablen sind standardmäßig innerhalb des Tasks oder der Stage sichtbar. Um sie über mehrere Tasks hinweg nutzbar zu machen, setzen Sie isOutput oder verwenden Sie eine zentrale Struktur zur Weitergabe.
  • Reihenfolge der Tasks: Stellen Sie sicher, dass der Task, der die Variable setzt, tatsächlich vor dem Task liegt, der sie liest.
  • Schreibfehler oder falsche Namen: Der Variablenname muss exakt übereinstimmen, inklusive Groß-/Kleinschreibung, sofern von der Plattform so vorgesehen.
  • Secrets: Wenn Sie isSecret aktivieren, prüfen Sie, ob der lesende Task überhaupt ein Zugriffrecht auf das Geheimnis hat. Geheimnisse erscheinen sonst nicht im Klartext und können zu Verwirrung führen.
  • Logging-Blockierung: In manchen Umgebungen werden Logs aus Sicherheitsgründen eingeschränkt. Prüfen Sie, ob der Aufruf wirklich im Log erscheint und ob er von einer Gatekeeping-Policy blockiert wird.

Ein häufiges Muster ist, eine Variable sofort nach dem Setzen zu testen, z. B. durch Echo-Ausgaben oder durch direkte Nutzung in einem Skript, um sicherzustellen, dass der Wert korrekt gesetzt wird.

Sicherheit und Best Practices

Sicherheit spielt bei Variablen eine wichtige Rolle, insbesondere wenn es um Tokens, Passwörter oder Zugangsschlüssel geht. Hier einige klare Empfehlungen:

  • Verwenden Sie always-Secret-Variablen, wenn sensible Informationen gesetzt werden müssen. issecret sorgt dafür, dass der Wert nicht in Logs erscheint.
  • Geben Sie Variablennamen eindeutig und sinnvoll, damit die Pipelines auch in der Zukunft wartbar bleiben. Eine konsistente Benennung erleichtert die Nachverfolgung.
  • Begrenzen Sie die Verfügbarkeit von Variablen auf das notwendige Scope. Vermeiden Sie, dass sensible Werte in zu vielen Tasks gelesen werden können.
  • Dokumentieren Sie Ihre Variablenverwendung, damit neue Teammitglieder verstehen, wo Werte herkommen und wie sie genutzt werden.

Fortgeschrittene Konzepte: Output-Variablen und Abhängigkeiten

Wenn Sie komplexe Pipelines mit mehreren Stages oder Jobs betreiben, sind Output-Variablen unverzichtbar. Die korrekte Verwendung von ##vso task.setvariable mit isOutput ermöglicht es, Werte explizit an nachfolgende Schritte zu übergeben. Die Referenzierung der Output-Variablen hängt vom Schema der Pipeline ab, oft sieht sie so aus:

${{ dependencies.<JobName>.Steps.<StepName>.outputs['MyOutputVar'] }}

Dieses Muster erlaubt es, dynamische Werte an die nächste Stufe zu leiten, ohne harte Kopplungen einzubauen. In einer österreichischen DevOps-Umgebung bedeutet dies oft, Building- und Deployment-Schritte flexibel zu orchestrieren, unabhängig von der genauen Build-Konfiguration.

Vergleich mit anderen Mechanismen zur Variablenverwaltung

Neben dem Logging-Command gibt es weitere Ansätze zur Variablenverwaltung in Pipelines. Hier ein kurzer Vergleich:

  • Umgebungsvariablen: Direkter Zugriff über die Shell; gut für einfache Werte, aber weniger geeignet, wenn der Wert sicherheitsrelevant oder nur für späteren Tasks bestimmt ist.
  • Pipeline-Variablen: Persistente Variablen, die in der Pipeline-Definition vorgeschlagen werden können. Sie eignen sich gut für Konfigurationen, die über den gesamten Build hinweg gelten.
  • Secret-Variablen: Sehr sicher, aber Einschränkungen beim Lesen in Logs. Ideal für Tokens und Passwörter.

Der Schlüssel ist, das richtige Instrument zum richtigen Zeitpunkt zu wählen. ##vso task.setvariable bietet eine feine Steuerung der Ablauflogik, insbesondere wenn Werte erst zur Build-Zeit verfügbar sind.

Häufige Anwendungsfälle in österreichischen DevOps-Teams

In vielen Unternehmen mit regionalen Teams in Österreich gibt es spezifische Anforderungen an Pipelines, die sich durch den Einsatz von ##vso task.setvariable elegant lösen lassen:

  • Lokale Build-Nummern mit regionalen Timestamp-Formaten (Jahr-MM-Tag, Uhrzeit im 24-Stunden-Format).
  • Umgebungsbasierte API-Endpunkte, die je nach Staging-, Produktiv- oder Testumgebung wechseln.
  • Feature-Flag-Status, der nach einem Schritt in den Rest der Pipeline hineinreichbar gemacht wird.
  • Artefakt-Namen inkl. Build-Nummer, Produktversion oder Commit-SHA, um Nachvollziehbarkeit und Auditierbarkeit sicherzustellen.

Best Practices: Wie man mit ##vso task.setvariable sauber arbeitet

  • Nutzen Sie klare, beschreibende Variablennamen. Verhindern Sie Mehrdeutigkeiten durch Namenskonventionen wie PREFIX_SUFFIX oder ähnliche Muster.
  • Setzen Sie Variablen sobald wie möglich im Ablauf, wenn spätere Tasks darauf angewiesen sind. Die rechtzeitige Verfügbarkeit erleichtert Debugging und Wartung.
  • Verwenden Sie isSecret, wenn der Wert sensibel ist. Verstecken Sie diese Werte zuverlässig in Logs.
  • Testen Sie Pipelines in einer sicheren Umgebung, bevor Sie neue Variablenstrukturen in die Production-Pipeline übernehmen.
  • Dokumentieren Sie jede Variable, ihren Zweck, den Scope und die Abhängigkeiten zu anderen Tasks.

Praktische Tipps zur Fehlervermeidung

Um typische Stolpersteine zu vermeiden, beachten Sie diese Hinweise:

  • Stellen Sie sicher, dass der Befehl exakt so formatiert ist, wie Azure DevOps ihn erwartet: ##vso[task.setvariable variable=NAME;]WERT.
  • Beobachten Sie die Pipeline-Logs aufmerksam. Oft offenbart der Log-Eintrag, ob der Wert erfolgreich gesetzt wurde oder ob es einen Fehler gab.
  • Wenn Sie eine Variable als Output deklarieren, prüfen Sie, ob die Referenzierung der Variable in der nachfolgenden Stage wirklich korrekt umgesetzt ist.
  • Beachten Sie Unterschiede zwischen Bash-, PowerShell- oder Shell-Skripten, insbesondere wie Variablen in den jeweiligen Umgebungen zurückgegeben werden.

Fallstricke vermeiden: Typen, Werte und Konvertierung

Obwohl ##vso task.setvariable sehr flexibel ist, sollten Sie sich über Typ- und Formatierungseinschränkungen im Klaren sein. Ein Wert ist standardmäßig eine Zeichenkette. Falls Sie numerische oder boolesche Werte benötigen, sollten Sie sie in der Ziel-Task entsprechend konvertieren oder die Variable in der richtigen Form setzen.

Zusammenfassung: Warum ##vso task.setvariable so wertvoll ist

Der Befehl ##vso task.setvariable bietet eine einfache, aber leistungsstarke Schnittstelle, um Werte zwischen Tasks in Azure Pipelines zu übertragen. Sichtbarkeit, Sicherheit (mit isSecret), sowie die Möglichkeit, Output-Variablen zu nutzen, machen ihn zu einem unverzichtbaren Bestandteil jeder gut strukturierten Pipeline. Durch saubere Namensgebung, klare Dokumentation und bewussten Einsatz von Scope und Secrets lässt sich die Pipeline-Wartbarkeit erheblich erhöhen.

Weiterführende Überlegungen: Integration mit anderen Tools

In vielen modernen DevOps-Setups arbeiten Teams nicht nur mit Azure Pipelines. Häufig besteht eine Notwendigkeit, Variablen auch an andere Tools weiterzugeben, z. B. in Container-Orchestrierungssysteme, Deployments auf künftige Cluster oder in Monitoring-Systeme. In solchen Fällen dient ##vso task.setvariable als integrativer Brücke zwischen Build-Phasen und Deploy-Phasen, indem es konsistente Werte beibehält, die dann in den nächsten Schritten interpretiert werden können.

Fazit

Der Logging-Command ##vso task.setvariable ist mehr als nur eine einfache Methode zum Speichern von Werten in einer Pipeline. Er bietet Flexibilität, Sicherheit und klare Struktur, um Build- und Release-Prozesse robuster und nachvollziehbarer zu gestalten. Egal, ob Sie eine kleine, lokale CI/CD-Pipeline oder eine komplexe Multi-Stage-Architektur betreiben – mit diesem Befehl setzen Sie Variablen dort, wo sie benötigt werden, zuverlässig und verständlich. Nutzen Sie ihn bewusst, pflegen Sie eine konsistente Namensgebung und dokumentieren Sie Ihre Variablen sorgfältig, dann profitieren Sie von stabileren Abläufen, besseren Audits und einer schnelleren Fehlerdiagnose.