Encrypted secrets

Informationen zu verschlüsselten Geheimnissen

Secrets are encrypted environment variables that you create in an organization or repository. The secrets that you create are available to use in GitHub Actions workflows. GitHub uses a libsodium sealed box to help ensure that secrets are encrypted before they reach GitHub and remain encrypted until you use them in a workflow.

Für Geheimnisse, die auf Organisationsebene gespeichert sind, kannst Du Zugriffsrichtlinien festlegen, um zu kontrollieren, welche Repositorys die Organisations-Geheimnisse verwenden können. Geheimnisse auf Organisationsebene ermöglichen es Dir, Geheimnisse zwischen mehreren Repositories zu teilen, was die Notwendigkeit zur Erstellung von doppelten Geheimnissen verringert. Die Aktualisierung eines Organisationsgeheimnisses an nur einem Ort stellt außerdem sicher, dass die Änderung in allen Workflows aller Repositorys wirksam wird, die dieses Geheimnis verwenden.

Benennen Ihrer Geheimnisse

Die folgenden Regeln gelten für geheime Namen:

• Geheime Namen dürfen nur alphanumerische Zeichen ([a-z], [A-Z], [0-9]) oder Unterstriche (_) enthalten. Leerzeichen sind nicht zulässig.

• Geheime Namen dürfen nicht mit dem GITHUB_ -Präfix beginnen.

• Geheime Namen dürfen nicht mit einer Zahl beginnen.

• Secret names are not case-sensitive.

• Geheime Namen müssen auf der Ebene eindeutig sein, auf der sie erstellt werden.

  For example, a secret created at the repository level must have a unique name in that repository, and a secret created at the organization level must have a unique name at that level.

  If a secret with the same name exists at multiple levels, the secret at the lower level takes precedence. For example, if an organization-level secret has the same name as a repository-level secret, then the repository-level secret takes precedence.

To help ensure that GitHub redacts your secret in logs, avoid using structured data as the values of secrets. Vermeide beispielsweise Geheimnisse zu erstellen, die JSON oder codierte Git-Blobs enthalten.

Zugriff auf Ihre Geheimnisse

Um ein Geheimnis für eine Aktion verfügbar zu machen, legen Sie das Geheimnis als Eingabe oder Umgebungsvariable in der Workflow-Datei fest. In der README-Datei der Aktion erfahren Sie, welche Eingaben und Umgebungsvariablen die Aktion erwartet. Weitere Informationen finden Sie unter „Workflow-Syntax für GitHub Actions“.

Du kannst verschlüsselte Geheimnisse in einer Workflow-Datei verwenden und lesen, wenn Du auf die Datei Bearbeitungs-Zugriff hast. Weitere Informationen findest Du unter „Zugriffsberechtigungen auf GitHub“.

Sie können Geheimnisse auch mit der REST-API verwalten. For more information, see "Secrets."

Einschränken von Anmeldeinformationsberechtigungen

Beim Generieren von Anmeldeinformationen wird empfohlen, möglichst geringe Berechtigungen zu erteilen. Anstatt z.B. persönliche Anmeldeinformationen zu verwenden, solltest Du Bereitstellen von Schlüsseln oder einen „Service-Account“ (Dienstkonto) benuzen. Ziehe in Erwägung, Nur-Lese-Berechtigungen zu gewähren, wenn dies ausreicht, und schränke den Zugriff so weit wie möglich ein. Wähle beim Generieren eines persönlichen Zugriffstokens („personal access token“, PAT) die geringsmöglichen Anwendungsbereiche („scopes“) aus.

Erstellen verschlüsselter Geheimnisse für ein Repository

Um Geheimnisse für ein Benutzerkonto-Repository zu erstellen, musst Du der Repository-Inhaber sein. Um Geheimnisse für ein Organisations-Repository zu erstellen, musst Du admin-Zugriff haben.

gh secret set secret-name

gh secret set secret-name < secret.txt

Erstellen verschlüsselter Geheimnisse für eine Organisation

Beim Erstellen eines geheimen Schlüssels in einer Organisation können Sie eine Richtlinie verwenden, um einzuschränken, welche Repositorys auf diesen geheimen Schlüssel zugreifen können. Sie können z. B. Zugriff auf alle Repositorys gewähren oder den Zugriff auf nur private Repositorys oder eine angegebene Liste von Repositorys beschränken.

Um Geheimnisse auf Organisationsebene zu erstellen, musst Du admin-Zugriff haben.

gh auth login --scopes "admin:org"

gh secret set --org organization-name secret-name

gh secret set --org organization-name secret-name --visibility all

gh secret set --org organization-name secret-name --repos repo-name-1,repo-name-2"

gh secret list --org organization-name

Überprüfen des Zugriffs auf Geheimnisse auf Organisationsebene

Sie können überprüfen, welche Zugriffsrichtlinien auf einen geheimen Schlüssel in Ihrer Organisation angewendet werden.

1. Navigiere auf GitHub Enterprise Server zur Hauptseite der Organisation.
2. Klicken Sie unter dem Namen Ihrer Organisation auf Settings.
3. Klicken Sie auf der linken Seitenleiste auf Secrets (Geheimnisse).
4. Die Liste der Geheimnisse enthält alle konfigurierten Berechtigungen und Richtlinien. Ein Beispiel:
5. Weitere Informationen zu den konfigurierten Berechtigungen für jeden geheimen Schlüssel finden Sie unter Aktualisieren.

Verschlüsselte Geheimnisse in einem Workflow verwenden

Um eine Aktion mit einem Geheimnis als Eingabe- oder Umgebungsvariable zu versehen, kannst Du den secrets Kontext verwenden, um auf Geheimnisse zuzugreifen, die Du in Deinem Repository erstellt hast. For more information, see "Contexts" and "Workflow syntax for GitHub Actions."

steps:
  - name: Hello world action
    with: # Das Geheimnis als Eingabe setzen
      super_secret: ${{ secrets.SuperSecret }}
    env: # Oder als Umgebunsvariable ("environment variable")
      super_secret: ${{ secrets.SuperSecret }}

Wann immer dies möglich ist, vermeide die Übergabe von Geheimnissen zwischen Prozessen von der Befehlszeile aus. Befehlszeilen-Prozesse können für andere Benutzer (mithilfe des Befehls ps) sichtbar sein oder von „security audit events“ (Ereignissen zur Sicherheits-Überprüfung) erfasst werden. Um den Schutz von Geheimnissen zu unterstützen, solltest Du die Verwendung von Umgebungsvariablen, STDIN oder andere vom Zielprozess unterstützte Mechanismen in Betracht ziehen.

Wenn Sie Geheimnisse innerhalb einer Kommandozeile übergeben müssen, 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. Ein 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%"

Einschränkungen für Geheimnisse

You can store up to 1,000 organization secrets and 100 repository secrets.

A workflow created in a repository can access the following number of secrets:

• All 100 repository secrets.
• If the repository is assigned access to more than 100 organization secrets, the workflow can only use the first 100 organization secrets (sorted alphabetically by secret name).

Geheimnisse sind auf 64 KB beschränkt. Um Geheimnisse zu verwenden, die größer als 64 KB sind, können Sie verschlüsselte Geheimnisse in Ihrem Repository speichern und die Passphrase zur Entschlüsselung als Geheimnis auf GitHub speichern. Sie können beispielsweise gpg verwenden, um Ihre Anmeldeinformationen lokal zu verschlüsseln, bevor Sie die Datei in Ihrem Repository auf GitHub einchecken. Weitere Informationen finden Sie auf der „gpg-Manpage“.

1. Führe den folgenden Befehl von Deinem Terminal aus, um die Datei my_secret.json mit gpg und dem Verschlüsselungs-Algorithmus AES256 zu verschlüsseln.

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

2. Du wirst aufgefordert, eine Passphrase einzugeben. Merken Sie sich die Passphrase, denn Sie müssen ein neues Geheimnis auf GitHub mit der Passphrase als Wert erstellen.

3. Erstellen Sie einen neuen Geheimschlüssel, der die Passphrase enthält. Erstelle beispielsweise ein neues Geheimnis mit dem Namen LARGE_SECRET_PASSPHRASE und setze den Wert des Geheimnisses auf die Passphrase, die Du im obigen Schritt ausgewählt hast.

4. Kopiere Deine verschlüsselte Datei in Dein Repository und committe sie. In diesem Beispiel ist die verschlüsselte Datei my_secret.json.gpg.

5. Erstellen Sie ein Shell-Skript, um das Passwort zu entschlüsseln. Speichern Sie diese Datei als decrypt_secret.sh.

   Die Datei
   mkdir $HOME/secrets
   --batch entschlüsseln, um den interaktiven Befehl
   zu verhindern - --ja, um "Ja" für Fragen
   gpg --quiet --batch --yes --decrypt --passphrase="$LARGE_SECRET_PASSPHRASE"
   --output $HOME/secrets/my_secret.json my_secret.json.gp

6. Stellen Sie sicher, dass Ihr Shell-Skript ausführbar ist, bevor Sie es in Ihrem Repository einchecken.

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

7. Verwenden Sie in Ihrem Workflow einen step, um das Shell-Skript aufzurufen und das Geheimnis zu entschlüsseln. Um in der Umgebung, in der Dein Workflow läuft, eine Kopie Deines Projektarchivs zu haben, musst Du die Aktion actions/checkout verwenden. Referenzieren Sie Ihr Shell-Skript mit dem Befehl run relativ zum Root Ihres Repositorys.

   name: Workflows with large secrets
   
   on: push
   
   jobs:
     my-job:
       name: My Job
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v2
         - name: Decrypt large secret
           run: ./.github/scripts/decrypt_secret.sh
           env:
             LARGE_SECRET_PASSPHRASE: ${{ secrets.LARGE_SECRET_PASSPHRASE }}
         # Dieser Befehl ist nur ein Beispiel, um zu zeigen, dass Dein Geheimnis ausgegeben wird
         # Stelle sicher, dass Du alle Druckanweisungen Deiner Geheimnisse entfernst. Github
         # verbirgt keine Geheimnisse, die diese Umgehung verwenden.
         - name: Test printing your secret (Remove this step in production)
           run: cat $HOME/secrets/my_secret.json