Hinzufügen und Verwenden von Variablengruppen

  • Artikel

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2019

Variablengruppen speichern Werte und Geheimnisse, die Sie möglicherweise an eine YAML-Pipeline übergeben oder über mehrere Pipelines hinweg verfügbar machen sollten. Sie können Variablengruppen in mehreren Pipelines im selben Projekt gemeinsam verwenden.

Geheimnisvariablen in Variablengruppen sind geschützte Ressourcen. Sie können Kombinationen von Genehmigungen, Überprüfungen und Pipelineberechtigungen hinzufügen, um den Zugriff auf Geheimnisvariablen in einer Variablengruppe zu beschränken. Der Zugriff auf Nicht-Geheimnisvariablen ist nicht mittels Genehmigungen, Überprüfungen und Pipelineberechtigungen eingeschränkt.

Erstellen einer Variablengruppe

Sie können keine Variablengruppen in YAML erstellen, diese können jedoch wie unter Verwenden einer Variablengruppe beschrieben verwendet werden.

Verwenden einer Variablengruppe

Um eine Variable aus einer Variablengruppe zu verwenden, fügen Sie einen Verweis auf die Gruppe in Ihrer YAML-Datei hinzu:

variables:
- group: my-variable-group

Anschließend können Variablen aus der Variablengruppe in Ihrer YAML-Datei verwendet werden.

Wenn Sie sowohl Variablen als auch Variablengruppen verwenden, verwenden Sie die name/value-Syntax für die einzelnen nicht gruppierten Variablen:

variables:
- group: my-variable-group
- name: my-bare-variable
  value: 'value of my-bare-variable'

Verwenden Sie Makrosyntax oder einen Laufzeitausdruck, um auf eine Variablengruppe zu verweisen. Im folgenden Beispiel verfügt die Gruppe my-variable-group über eine Variable namens myhello.

variables:
- group: my-variable-group
- name: my-passed-variable
  value: $[variables.myhello] # uses runtime expression

steps:
- script: echo $(myhello) # uses macro syntax
- script: echo $(my-passed-variable)

Sie können auf mehrere Variablengruppen in derselben Pipeline verweisen. Wenn mehrere Variablengruppen dieselbe Variable enthalten, legt die zuletzt in Ihre YAML-Datei eingeschlossene Variablengruppe den Wert der Variable fest.

variables:
- group: my-first-variable-group
- group: my-second-variable-group

Sie können auch auf eine Variablengruppe in einer Vorlage verweisen. In der Vorlage variables.yml wird auf die Gruppe my-variable-group verwiesen. Die Variablengruppe enthält eine Variable mit dem Namen myhello.

# variables.yml
variables:
- group: my-variable-group

In dieser Pipeline ist die Variable $(myhello) aus der Variablengruppe my-variable-group enthalten und auf variables.yml wird verwiesen.

# azure-pipeline.yml
stages:
- stage: MyStage
  variables:
  - template: variables.yml
  jobs:
  - job: Test
    steps:
    - script: echo $(myhello)

Autorisieren einer Variablengruppe

Um mit einer Variablengruppe arbeiten zu können, müssen Sie die Gruppe autorisieren. Wenn Sie nur die Variablengruppe in YAML benennen, kann jeder, der Code an Ihr Repository pushen kann, den Inhalt der Geheimnisse in der Variablengruppe extrahieren. Sie können die Gruppe mit einer der folgenden Methoden autorisieren:

  • Wenn Sie eine Pipeline zur Verwendung der Variablengruppe autorisieren möchten, wechseln Sie zu Azure Pipelines. Dies bietet sich an, wenn Sie keine Geheimnisse in der Gruppe haben. Wählen SieBibliothek (Library)>Variablengruppen (Variable groups) und dann die betreffende Variablengruppe aus und aktivieren Sie die Einstellung Zugriff auf alle Pipelines zulassen (Allow access to all pipelines).

  • Um eine Variablengruppe für eine bestimmte Pipeline zu autorisieren, öffnen Sie die Pipeline, wählen Sie Bearbeiten (Edit) aus und stellen Sie dann einen Build manuell in die Warteschlange. Daraufhin werden ein Ressourcenautorisierungsfehler und die Aktion „Ressourcen autorisieren“ (Authorize resources) für den Fehler angezeigt. Wählen Sie diese Aktion aus, um die Pipeline explizit als autorisierten Benutzer der Variablengruppe hinzuzufügen.

Hinweis

Wenn Sie einer Pipeline eine Variablengruppe hinzufügen und in Ihrem Build keinen Ressourcenautorisierungsfehler erhalten, wenn Sie einen Fehler erwartet haben, deaktivieren Sie die Einstellung Zugriff auf alle Pipelines zulassen (Allow access to all pipelines).

Sie können auf die Variablenwerte in einer verknüpften Variablengruppe auf die gleiche Weise zugreifen wie bei Variablen, die in der Pipeline selbst definiert werden. Wenn Sie beispielsweise auf den Wert einer Variable namens customer in einer Variablengruppe zugreifen möchten, die mit der Pipeline verknüpft ist, verwenden Sie $(customer) in einem Aufgabenparameter oder einem Skript. Sie können jedoch nicht direkt in Skripts auf Geheimnisvariablen (verschlüsselte Variablen und Schlüsseltresorvariablen) zugreifen. Stattdessen müssen sie als Argumente an eine Aufgabe übergeben werden. Weitere Informationen finden Sie unter Geheimnisse

Änderungen, die Sie an einer Variablengruppe vornehmen, sind automatisch für alle Definitionen oder Phasen verfügbar, mit denen die Variablengruppe verknüpft wird.

Auflisten von Variablengruppen

Verwenden Sie die CLI, um die Variablengruppen für Pipelineausführungen mit dem Befehl az pipelines variable-group list aufzulisten. Wenn Sie nicht mit der Azure DevOps-Erweiterung für die CLI vertraut sind, finden Sie weitere Informationen unter Erste Schritte mit Azure DevOps CLI.

az pipelines variable-group list [--action {manage, none, use}]
                                 [--continuation-token]
                                 [--group-name]
                                 [--org]
                                 [--project]
                                 [--query-order {Asc, Desc}]
                                 [--top]

Optionale Parameter

  • action: Gibt die Aktion an, die für die Variablengruppen ausgeführt werden kann. Akzeptierte Werte sind manage, none und use.
  • continuation-token: Listet die Variablengruppen auf, nachdem ein Fortsetzungstoken bereitgestellt wurde.
  • group-name: Name der Variablengruppe. Es werden Wildcards akzeptiert, z. B. new-var*.
  • org: Azure DevOps-Organisations-URL. Konfigurieren der Standardorganisation mithilfe von az devops configure -d organization=ORG_URL. Erforderlich, wenn nicht als Standard konfiguriert oder mithilfe von git config übernommen. Beispiel: --org https://dev.azure.com/MyOrganizationName/.
  • project: Name oder ID des Projekts. Konfigurieren des Standardprojekts mithilfe von az devops configure -d project=NAME_OR_ID. Erforderlich, wenn nicht als Standard konfiguriert oder mithilfe von git config übernommen.
  • query-order: Listet die Ergebnisse entweder in aufsteigender oder absteigender Reihenfolge (standard) auf. Akzeptierte Werte sind Asc und Desc.
  • top: Anzahl der aufzulistenden Variablengruppen.

Beispiel

Der folgende Befehl listet die obersten drei Variablengruppen in aufsteigender Reihenfolge auf und gibt die Ergebnisse im Tabellenformat zurück.

az pipelines variable-group list --top 3 --query-order Asc --output table

ID    Name               Type    Number of Variables
----  -----------------  ------  ---------------------
1     myvariables        Vsts    2
2     newvariables       Vsts    4
3     new-app-variables  Vsts    3

Anzeigen von Details für eine Variablengruppe

Sie können die Details einer Variablengruppe in Ihrem Projekt mit dem Befehl az pipelines variable-group show anzeigen. Wenn Sie nicht mit der Azure DevOps-Erweiterung für die CLI vertraut sind, finden Sie weitere Informationen unter Erste Schritte mit Azure DevOps CLI.

az pipelines variable-group show --group-id
                                 [--org]
                                 [--project]

Parameter

  • group-id: Erforderlich. ID der Variablengruppe. Informationen zum Ermitteln der Variablengruppen-ID finden Sie unter Auflisten von Variablengruppen.
  • org: Azure DevOps-Organisations-URL. Konfigurieren der Standardorganisation mithilfe von az devops configure -d organization=ORG_URL. Erforderlich, wenn nicht als Standard konfiguriert oder mithilfe von git config übernommen. Beispiel: --org https://dev.azure.com/MyOrganizationName/.
  • project: Name oder ID des Projekts. Konfigurieren des Standardprojekts mithilfe von az devops configure -d project=NAME_OR_ID. Erforderlich, wenn nicht als Standard konfiguriert oder mithilfe von git config übernommen.

Beispiel

Der folgende Befehl zeigt Details für die Variablengruppe mit der ID 4 an und gibt die Ergebnisse im YAML-Format zurück.

az pipelines variable-group show --group-id 4 --output yaml

authorized: false
description: Variables for my new app
id: 4
name: MyNewAppVariables
providerData: null
type: Vsts
variables:
  app-location:
    isSecret: null
    value: Head_Office
  app-name:
    isSecret: null
    value: Fabrikam

Löschen einer Variablengruppe

Sie können eine Variablengruppe in Ihrem Projekt mit dem Befehl az pipelines variable-group delete löschen. Wenn Sie nicht mit der Azure DevOps-Erweiterung für die CLI vertraut sind, finden Sie weitere Informationen unter Erste Schritte mit Azure DevOps CLI.

az pipelines variable-group delete --group-id
                                   [--org]
                                   [--project]
                                   [--yes]

Parameter

  • group-id: Erforderlich. ID der Variablengruppe. Informationen zum Ermitteln der Variablengruppen-ID finden Sie unter Auflisten von Variablengruppen.
  • org: Azure DevOps-Organisations-URL. Konfigurieren der Standardorganisation mithilfe von az devops configure -d organization=ORG_URL. Erforderlich, wenn nicht als Standard konfiguriert oder mithilfe von git config übernommen. Beispiel: --org https://dev.azure.com/MyOrganizationName/.
  • project: Name oder ID des Projekts. Konfigurieren des Standardprojekts mithilfe von az devops configure -d project=NAME_OR_ID. Erforderlich, wenn nicht als Standard konfiguriert oder mithilfe von git config übernommen.
  • yes: Optional. Fordert nicht zur Bestätigung auf.

Beispiel

Der folgende Befehl löscht die Variablengruppe mit der ID 1 und fordert keine Bestätigung.

az pipelines variable-group delete --group-id 1 --yes

Deleted variable group successfully.

Hinzufügen von Variablen zu einer Variablengruppe

Mithilfe der Azure DevOps-CLI können Sie einer Variablengruppe in einer Pipeline mit dem Befehl az pipelines variable-group variable create eine Variable hinzufügen. Wenn Sie nicht mit der Azure DevOps-Erweiterung für die CLI vertraut sind, finden Sie weitere Informationen unter Erste Schritte mit Azure DevOps CLI.

az pipelines variable-group variable create --group-id
                                            --name
                                            [--org]
                                            [--project]
                                            [--secret {false, true}]
                                            [--value]

Parameter

  • group-id: Erforderlich. ID der Variablengruppe. Informationen zum Ermitteln der Variablengruppen-ID finden Sie unter Auflisten von Variablengruppen.
  • name: Erforderlich. Name der hinzugefügten Variable.
  • org: Azure DevOps-Organisations-URL. Konfigurieren der Standardorganisation mithilfe von az devops configure -d organization=ORG_URL. Erforderlich, wenn nicht als Standard konfiguriert oder mithilfe von git config übernommen. Beispiel: --org https://dev.azure.com/MyOrganizationName/.
  • project: Name oder ID des Projekts. Konfigurieren des Standardprojekts mithilfe von az devops configure -d project=NAME_OR_ID. Erforderlich, wenn nicht als Standard konfiguriert oder mithilfe von git config übernommen.
  • secret: Optional. Gibt an, ob der Wert der Variablen ein Geheimnis ist. Zulässige Werte sind false und true.
  • value: Bei nicht geheimen Variablen erforderlich. Der Wert der Variablen. Wenn der Parameter value bei geheimen Variablen nicht angegeben wird, wird er aus der Umgebungsvariablen mit dem Präfix AZURE_DEVOPS_EXT_PIPELINE_VAR_ übernommen, oder Benutzer*innen werden dazu aufgefordert, ihn über die Standardeingabe einzugeben. Beispielsweise kann eine Variable mit dem Namen MySecret mithilfe der Umgebungsvariablen AZURE_DEVOPS_EXT_PIPELINE_VAR_MySecret eingegeben werden.

Beispiel

Mit dem folgenden Befehl wird eine Variable in der Variablengruppe mit der ID 4 erstellt. Die neue Variable heißt requires-login mit dem Wert True und das Ergebnis wird im Tabellenformat angezeigt.

az pipelines variable-group variable create --group-id 4 --name requires-login --value True --output table

Name            Is Secret    Value
--------------  -----------  -------
requires-login  False        True

Auflisten von Variablen in einer Variablengruppe

Sie können die Variablen in einer Variablengruppe mit dem Befehl az pipelines variable-group variable list auflisten. Wenn Sie nicht mit der Azure DevOps-Erweiterung für die CLI vertraut sind, finden Sie weitere Informationen unter Erste Schritte mit Azure DevOps CLI.

az pipelines variable-group variable list --group-id
                                          [--org]
                                          [--project]

Parameter

  • group-id: Erforderlich. ID der Variablengruppe. Informationen zum Ermitteln der Variablengruppen-ID finden Sie unter Auflisten von Variablengruppen.
  • org: Azure DevOps-Organisations-URL. Konfigurieren der Standardorganisation mithilfe von az devops configure -d organization=ORG_URL. Erforderlich, wenn nicht als Standard konfiguriert oder mithilfe von git config übernommen. Beispiel: --org https://dev.azure.com/MyOrganizationName/.
  • project: Name oder ID des Projekts. Konfigurieren des Standardprojekts mithilfe von az devops configure -d project=NAME_OR_ID. Erforderlich, wenn nicht als Standard konfiguriert oder mithilfe von git config übernommen.

Beispiel

Der folgende Befehl listet alle Variablen in der Variablengruppe mit der ID 4 auf und zeigt das Ergebnis im Tabellenformat an.

az pipelines variable-group variable list --group-id 4 --output table

Name            Is Secret    Value
--------------  -----------  -----------
app-location    False        Head_Office
app-name        False        Fabrikam
requires-login  False        True

Aktualisieren von Variablen in einer Variablengruppe

Sie können eine Variablengruppe mit dem Befehl az pipelines variable-group variable update aktualisieren. Wenn Sie nicht mit der Azure DevOps-Erweiterung für die CLI vertraut sind, finden Sie weitere Informationen unter Erste Schritte mit Azure DevOps CLI.

az pipelines variable-group variable update --group-id
                                            --name
                                            [--new-name]
                                            [--org]
                                            [--project]
                                            [--prompt-value {false, true}]
                                            [--secret {false, true}]
                                            [--value]

Parameter

  • group-id: Erforderlich. ID der Variablengruppe. Informationen zum Ermitteln der Variablengruppen-ID finden Sie unter Auflisten von Variablengruppen.
  • name: Erforderlich. Name der hinzugefügten Variable.
  • new-name: Optional. Kann angegeben werden, um den Namen der Variablen zu ändern.
  • org: Azure DevOps-Organisations-URL. Konfigurieren der Standardorganisation mithilfe von az devops configure -d organization=ORG_URL. Erforderlich, wenn nicht als Standard konfiguriert oder mithilfe von git config übernommen. Beispiel: --org https://dev.azure.com/MyOrganizationName/.
  • project: Name oder ID des Projekts. Konfigurieren des Standardprojekts mithilfe von az devops configure -d project=NAME_OR_ID. Erforderlich, wenn nicht als Standard konfiguriert oder mithilfe von git config übernommen.
  • prompt-value: Legen Sie diesen Wert auf true fest, um den Wert einer geheimen Variablen mithilfe einer Umgebungsvariablen oder nach Aufforderung über die Standardeingabe zu aktualisieren. Zulässige Werte sind false und true.
  • secret: Optional. Gibt an, ob der Wert der Variable ein Geheimnis ist. Zulässige Werte sind false und true.
  • value: Aktualisiert den Wert der Variablen. Verwenden Sie bei geheimen Variablen den Parameter prompt-value, um zur Eingabe über die Standardeingabe aufgefordert zu werden. Bei nicht interaktiven Konsolen kann dies aus der Umgebungsvariablen mit dem Präfix AZURE_DEVOPS_EXT_PIPELINE_VAR_ übernommen werden. Beispielsweise kann eine Variable mit dem Namen MySecret mithilfe der Umgebungsvariablen AZURE_DEVOPS_EXT_PIPELINE_VAR_MySecret eingegeben werden.

Beispiel

Der folgende Befehl aktualisiert die Variable requires-login mit dem neuen Wert False in der Variablengruppe mit der ID 4. Dabei wird angegeben, dass die Variable ein Geheimnis ist, und das Ergebnis im YAML-Format anzeigt. Beachten Sie, dass die Ausgabe den Wert als NULL anstelle von False anzeigt, da es sich um einen ausgeblendeten Geheimniswert handelt.

az pipelines variable-group variable update --group-id 4 --name requires-login --value False --secret true --output yaml

requires-login:
  isSecret: true
  value: null

Löschen von Variablen aus einer Variablengruppe

Sie können mit dem Befehl az pipelines variable-group variable delete eine Variable aus einer Variablengruppe löschen. Wenn Sie nicht mit der Azure DevOps-Erweiterung für die CLI vertraut sind, finden Sie weitere Informationen unter Erste Schritte mit Azure DevOps CLI.

az pipelines variable-group variable delete --group-id
                                            --name
                                            [--org]
                                            [--project]
                                            [--yes]

Parameter

  • group-id: Erforderlich. ID der Variablengruppe. Informationen zum Ermitteln der Variablengruppen-ID finden Sie unter Auflisten von Variablengruppen.
  • name: Erforderlich. Name der zu löschenden Variable.
  • org: Azure DevOps-Organisations-URL. Konfigurieren der Standardorganisation mithilfe von az devops configure -d organization=ORG_URL. Erforderlich, wenn nicht als Standard konfiguriert oder mithilfe von git config übernommen. Beispiel: --org https://dev.azure.com/MyOrganizationName/.
  • project: Name oder ID des Projekts. Konfigurieren des Standardprojekts mithilfe von az devops configure -d project=NAME_OR_ID. Erforderlich, wenn nicht als Standard konfiguriert oder mithilfe von git config übernommen.
  • yes: Optional. Fordert nicht zur Bestätigung auf.

Beispiel

Der folgende Befehl löscht die Variable requires-login aus der Variablengruppe mit der ID 4 und fordert zur Bestätigung auf.

az pipelines variable-group variable delete --group-id 4 --name requires-login

Are you sure you want to delete this variable? (y/n): y
Deleted variable 'requires-login' successfully.

Hinweis

Key Vaults, die die rollenbasierte Zugriffssteuerung (Azure RBAC) verwenden, werden nicht unterstützt.

Verknüpfen Sie einen vorhandenen Azure-Schlüsseltresor mit einer Variablengruppe und ordnen Sie der Variablengruppe selektive Tresorgeheimnisse zu.

  1. Aktivieren Sie auf der Seite Variablengruppen (Variable groups) die Option Geheimnisse von einem Azure-Schlüsseltresor als Variablen verknüpfen (Link secrets from an Azure key vault as variables). Sie benötigen einen vorhandenen Schlüsseltresor, der Ihre Geheimnisse enthält. Erstellen eines Schlüsseltresors über das Azure-Portal.

    Screenshot der Variablengruppe mit Azure Key Vault-Integration.

  2. Geben Sie den Endpunkt Ihres Azure-Abonnements und den Namen des Tresors an, der Ihre Geheimnisse enthält.

    Stellen Sie sicher, dass die Azure-Dienstverbindung im Tresor für die Geheimnisse mindestens über die Verwaltungsberechtigungen zum Abrufen und Auflisten verfügt. Aktivieren Sie Azure Pipelines, um diese Berechtigungen festzulegen, indem Sie neben dem Tresornamen Autorisieren (Authorize) auswählen. Sie können die Berechtigungen auch manuell im Azure-Portal festlegen:

    1. Öffnen Sie die Einstellungen für den Tresor und wählen Sie dann Zugriffsrichtlinien (Access policies)>Neu hinzufügen (Add new) aus.
    2. Wählen Sie Prinzipal auswählen (Select principal) und dann den Dienstprinzipal für Ihr Clientkonto aus.
    3. Wählen Sie Geheimnisberechtigungen (Secret permissions) aus, und stellen Sie sicher, dass die Berechtigungen Abrufen und Auflisten über Häkchen verfügen.
    4. Klicken Sie zum Speichern der Änderungen auf OK.

  3. Wählen Sie auf der Seite Variablengruppen (Variable groups) die Option + Hinzufügen (+ Add) aus, um bestimmte Geheimnisse aus Ihrem Tresor für die Zuordnung zu dieser Variablengruppe auszuwählen.

Verwalten von Schlüsseltresorgeheimnissen

Weitere Informationen finden Sie in der folgenden Liste hilfreicher Tipps zum Verwalten von Geheimnissen.

  • Nur die Geheimnisnamen werden der Variablengruppe zugeordnet, nicht die Geheimniswerte. Es wird der neueste aus dem Tresor abgerufene Geheimniswert in der Pipelineausführung verwendet, die mit der Variablengruppe verknüpft ist.

  • Alle Änderungen, die an vorhandenen Geheimnissen im Schlüsseltresor vorgenommen werden, sind automatisch für alle Pipelines verfügbar, in der die Variablengruppe verwendet wird.

  • Wenn neue Geheimnisse zum Tresor hinzugefügt oder daraus gelöscht werden, werden die zugeordneten Variablengruppen nicht automatisch aktualisiert. Die in der Variablengruppe enthaltenen Geheimnisse müssen explizit aktualisiert werden, damit die Pipelines, die die Variablengruppe verwenden, ordnungsgemäß ausgeführt werden.

  • Azure Key Vault unterstützt das Speichern und Verwalten von kryptografischen Schlüsseln und Geheimnissen in Azure. Derzeit unterstützt die Integration von Azure Pipelines-Variablengruppen nur die Zuordnung von Geheimnissen aus dem Azure-Schlüsseltresor. Kryptografische Schlüssel und Zertifikate werden nicht unterstützt.

Erweitern von Variablen in einer Gruppe

Wenn Sie eine Variable in einer Gruppe festlegen und in einer YAML-Datei verwenden, entspricht sie anderen definierten Variablen in der YAML-Datei. Weitere Informationen zur Rangfolge von Variablen finden Sie unter Variablen.