Verwenden von Geheimnissen in GitHub-Aktionen

Erstellen von Geheimnissen für ein Repository

Um Geheimnisse oder Variablen auf GitHub für ein Organisations-Repository zu erstellen, benötigen Sie write Zugriff. Für ein persönliches Konto-Repository müssen Sie Repository-Kollaborator sein.

gh secret set SECRET_NAME

gh secret set SECRET_NAME < secret.txt

Erstellen von Geheimnissen für eine Umgebung

Um Geheimnisse oder Variablen für eine Umgebung in einem Repository eines persönlichen Kontos zu erstellen, müssen Sie Besitzer des Repositorys sein. Für das Erstellen von Geheimnissen oder Variablen für eine Umgebung in einem Organisationsrepository benötigen Sie admin-Zugriff. Weitere Informationen zu Umgebungen findest du unter Verwalten von Umgebungen für die Bereitstellung.

gh secret set --env ENV_NAME SECRET_NAME

gh secret list --env ENV_NAME

Erstellen von Geheimnissen für eine Organisation

Beim Erstellen eines Geheimnisses oder einer Variable in einer Organisation kannst du mit einer Richtlinie den Zugriff jeweils nach Repository einschränken. Du kannst beispielsweise allen Repositorys Zugriff gewähren oder nur private Repositorys oder eine angegebene Liste von Repositorys zulassen.

Organisationsbesitzerinnen und Benutzerinnen mit den Berechtigungen „Organisationsaktionenvariablen verwalten“ oder „Organisationsaktioneneheimnisse verwalten“ können Geheimnisse oder Variablen auf Organisationsebene erstellen.

Weitere Informationen findest du unter Berechtigungen von benutzerdefinierten Organisationsrollen.

gh auth login --scopes "admin:org"

gh secret set --org ORG_NAME SECRET_NAME

gh secret set --org ORG_NAME SECRET_NAME --visibility all

gh secret set --org ORG_NAME SECRET_NAME --repos REPO-NAME-1, REPO-NAME-2

gh secret list --org ORG_NAME

Überprüfen des Zugriffs auf Organisationsgeheimnisse

Du kannst überprüfen, welche Zugriffsrichtlinien auf ein Geheimnis in deiner Organisation angewendet werden.

1. Navigieren Sie auf GitHub zur Hauptseite der Organisation.

2. Klicke unter dem Organisationsnamen auf Settings. Wenn die Registerkarte „Einstellungen“ nicht angezeigt wird, wähle im Dropdownmenü die Option Einstellungen aus.

   

3. Wähle im Abschnitt „Security“ der Randleiste Secrets and variables, und klicke anschließend auf Actions.

4. Die Liste der Geheimnisse enthält alle konfigurierten Berechtigungen und Richtlinien. Klicke auf Aktualisieren, um weitere Details zu den konfigurierten Berechtigungen des jeweiligen Geheimnisses anzuzeigen.

Verwenden von Geheimnissen in einem Workflow

Wenn du für eine Aktion ein Geheimnis als Eingabe- oder Umgebungsvariable bereitstellen möchtest, kannst du mithilfe des secrets-Kontexts auf Geheimnisse zugreifen, die du in deinem Repository erstellt hast. Weitere Informationen findest du unter Kontextreferenz und Workflowsyntax für GitHub Actions.

steps:
  - name: Hello world action
    with: # Set the secret as an input
      super_secret: ${{ secrets.SuperSecret }}
    env: # Or as an environment variable
      super_secret: ${{ secrets.SuperSecret }}

In if:-Bedingungen kann nicht direkt auf Geheimnisse verwiesen werden. Erwäge stattdessen, Geheimnisse als Umgebungsvariablen auf Auftragsebene festzulegen, und verweise dann auf die Umgebungsvariablen, um Schritte im Auftrag bedingt auszuführen. Weitere Informationen findest du unter Kontextreferenz und jobs.<job_id>.steps[*].if.

Wenn kein geheimer Schlüssel festgelegt wurde, ist der Rückgabewert eines Ausdrucks, der auf den geheimen Schlüssel verweist (z ${{ secrets.SuperSecret }} . B. im Beispiel), eine leere Zeichenfolge.

Wann immer dies möglich ist, vermeide die Übergabe von Geheimnissen zwischen Prozessen von der Befehlszeile aus. Befehlszeilenprozesse sind möglicherweise für andere Benutzer*innen sichtbar (mit dem Befehl ps) oder können durch Sicherheitsüberwachungsereignisse erfasst werden. Verwende zum Schutz von Geheimnissen Umgebungsvariablen, STDIN oder andere Methoden, die vom Zielprozess unterstützt werden.

Wenn du Geheimnisse innerhalb einer Kommandozeile übergeben musst, umschließe sie im Rahmen der gültigen Quotierungsregeln. Geheimnisse enthalten oft Sonderzeichen, die in deiner Shell unbeabsichtigte Wirkungen entfalten können. Um diese Sonderzeichen zu vermeiden, verwende deine Umgebungsvariablen mit Anführungszeichen. Beispiel:

Beispiel mit Bash

steps:
  - shell: bash
    env:
      SUPER_SECRET: ${{ secrets.SuperSecret }}
    run: |
      example-command "$SUPER_SECRET"

Beispiel mit PowerShell

steps:
  - shell: pwsh
    env:
      SUPER_SECRET: ${{ secrets.SuperSecret }}
    run: |
      example-command "$env:SUPER_SECRET"

Beispiel mit Cmd.exe

steps:
  - shell: cmd
    env:
      SUPER_SECRET: ${{ secrets.SuperSecret }}
    run: |
      example-command "%SUPER_SECRET%"

Speichern großer Geheimnisse

Um geheime Schlüssel zu verwenden, die größer als 48 KB sind, können Sie eine Problemumgehung verwenden, um geheime Schlüssel in Ihrem Repository zu speichern und die Entschlüsselungspassphrase als geheimer Schlüssel GitHubzu speichern. Zum Beispiel können Sie gpg verwenden, um eine Datei, die Ihr Geheimnis enthält, lokal zu verschlüsseln, bevor Sie die verschlüsselte Datei in Ihr Repository auf GitHub einchecken. Weitere Informationen findest du unter gpg manpage.

1. Führe in deinem Terminal den folgenden Befehl aus, um die Datei mit deinem Geheimnis mithilfe von gpg und dem AES256-Verschlüsselungsalgorithmus zu verschlüsseln. In diesem Beispiel ist my_secret.json die Datei, die das Geheimnis enthält.

   gpg --symmetric --cipher-algo AES256 my_secret.json
   

2. Du wirst aufgefordert, eine Passphrase einzugeben. Denken Sie an die Passphrase, da Sie einen neuen geheimen Schlüssel GitHub erstellen müssen, der die Passphrase als Wert verwendet.

3. Erstelle ein neues Geheimnis, das die Passphrase enthält. Erstelle z. B. ein neues Geheimnis mit dem Namen LARGE_SECRET_PASSPHRASE, und lege den Wert des Geheimnisses auf die Passphrase fest, die du im vorherigen Schritt verwendet hast.

4. Kopiere deine verschlüsselte Datei in einen Pfad in deinem Repository, und committe sie. In diesem Beispiel lautet die verschlüsselte Datei my_secret.json.gpg.

   Warnung

   Kopiere die verschlüsselte my_secret.json.gpg-Datei, die mit der Dateierweiterung .gpg endet, und nicht die unverschlüsselte my_secret.json-Datei.

   git add my_secret.json.gpg
   git commit -m "Add new secret JSON file"
   

5. Erstelle ein Shellskript in deinem Repository, um die Geheimnisdatei zu entschlüsseln. In diesem Beispiel heißt das Skript decrypt_secret.sh.

   Shell

   #!/bin/sh
   
   # Decrypt the file
   mkdir $HOME/secrets
   # --batch to prevent interactive command
   # --yes to assume "yes" for questions
   gpg --quiet --batch --yes --decrypt --passphrase="$LARGE_SECRET_PASSPHRASE" \
   --output $HOME/secrets/my_secret.json my_secret.json.gpg
   

6. Stelle sicher, dass dein Shell-Skript ausführbar ist, bevor du es in deinem Repository eincheckst.

   chmod +x decrypt_secret.sh
   git add decrypt_secret.sh
   git commit -m "Add new decryption script"
   git push
   

7. Verwenden Sie in Ihrem GitHub Actions Workflow ein step-Shellskript, um das Skript auszuführen und das Geheimnis zu entschlüsseln. Verwende für eine Kopie deines Repositorys in der Umgebung, in der dein Workflow ausgeführt wird, die Aktion actions/checkout. Verweise relativ zum Stamm des Repositorys mithilfe des Befehls run auf dein Shellskript.

   name: Workflows with large secrets
   
   on: push
   
   jobs:
     my-job:
       name: My Job
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v5
         - name: Decrypt large secret
           run: ./decrypt_secret.sh
           env:
             LARGE_SECRET_PASSPHRASE: ${{ secrets.LARGE_SECRET_PASSPHRASE }}
         # This command is just an example to show your secret being printed
         # Ensure you remove any print statements of your secrets. GitHub does
         # not hide secrets that use this workaround.
         - name: Test printing your secret (Remove this step in production)
           run: cat $HOME/secrets/my_secret.json
   

Speichern binärer Base64-Blobs als Geheimnisse

Mithilfe der Base64-Codierung kannst du kleine binäre Blobs als Geheimnisse speichern. Anschließend kannst du in deinem Workflow auf das Geheimnis verweisen und es zur Verwendung im Runner decodieren. Die Größenbeschränkungen findest du unter Verwenden von Geheimnissen in GitHub-Aktionen.

1. Verwende base64, um die Datei in eine Base64-Zeichenfolge zu codieren. Beispiel:

   Unter macOS können Sie Folgendes ausführen:

   base64 -i cert.der -o cert.base64
   

   Unter Linux können Sie Folgendes ausführen:

   base64 -w 0 cert.der > cert.base64
   

2. Erstelle ein Geheimnis, das die Base64-Zeichenfolge enthält. Beispiel:

   $ gh secret set CERTIFICATE_BASE64 < cert.base64
   ✓ Set secret CERTIFICATE_BASE64 for octocat/octorepo
   

3. Geben Sie das Geheimnis in base64 --decode weiter, um über den Runner auf die Base64-Zeichenfolge zuzugreifen. Beispiel:

   name: Retrieve Base64 secret
   on:
     push:
       branches: [ octo-branch ]
   jobs:
     decode-secret:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v5
         - name: Retrieve the secret and decode it to a file
           env:
             CERTIFICATE_BASE64: ${{ secrets.CERTIFICATE_BASE64 }}
           run: |
             echo $CERTIFICATE_BASE64 | base64 --decode > cert.der
         - name: Show certificate information
           run: |
             openssl x509 -in cert.der -inform DER -text -noout
   

Nächste Schritte

Referenzinformationen findest du unter Referenzen zu Geheimnissen.