Использование секретов в GitHub Actions

Сведения о секретах

Секреты — это переменные, создаваемые в организации, репозитории или среде репозитория. Создаваемые секреты доступны для использования в рабочих процессах GitHub Actions. GitHub Actions может считывать секрет только при явном включении секрета в рабочий процесс.

В случае с секретами, хранящимися на уровне организации, можно использовать политики доступа для управления тем, какие репозитории могут использовать секреты организации. Секреты уровня организации позволяют совместно использовать секреты в нескольких репозиториях, что снижает потребность в создании повторяющихся секретов. При обновлении секрета организации в одном расположении это изменение вступает в силу во всех рабочих процессах репозитория, использующих этот секрет.

Для секретов, хранящихся на уровне среды, можно включить нужных проверяющих для управления доступом к секретам. Доступ к секретам среды предоставляется заданию только после создания утверждения требуемыми проверяющими.

Присвоение имен секретам

К именам секретов применяются следующие правила:

Например, секрет, созданный на уровне среды, должен иметь уникальное имя в этой среде, секрет, созданный на уровне репозитория, должен иметь уникальное имя в этом репозитории, а секрет, созданный на уровне организации, должен иметь уникальное имя на этом уровне.

Если секрет с одним и тем же именем существует на нескольких уровнях, приоритет имеет секрет самого низкого уровня. Например, если секрет уровня организации имеет то же имя, что и секрет уровня репозитория, то приоритет имеет секрет уровня репозитория. Аналогичным образом, если организация, репозиторий и среда содержат секрет с одним и тем же именем, приоритет имеет секрет на уровне среды.

Чтобы гарантировать, что GitHub изменит секрет в журналах, не используйте структурированные данные в качестве значений секретов. Например, не создавайте секреты, содержащие BLOB-объекты JSON или закодированные BLOB-объекты Git.

Доступ к секретам

Чтобы сделать секрет доступным для действия, необходимо задать секрет как входные данные или переменную среды в файле рабочего процесса. Просмотрите файл сведений о действии, чтобы узнать, каких входных данных и переменных среды ожидает действие. Дополнительные сведения см. в разделе Синтаксис рабочего процесса для GitHub Actions.

Вы можете использовать и считывать секреты в файле рабочего процесса, если у вас есть доступ к редактированию файла. Дополнительные сведения см. в разделе Разрешения на доступ в GitHub.

Секреты организации и репозитория считываются при выполнении рабочего процесса в очереди, а секреты среды считываются при запуске задания, ссылающегося на среду.

Вы также можете управлять секретами с помощью REST API. Дополнительные сведения см. в разделе Конечные точки REST API для секретов GitHub Actions.

Ограничение разрешений для учетных данных

При создании учетных данных рекомендуется предоставить минимальные разрешения. Например, вместо использования личных учетных данных используйте ключи развертывания или учетную запись службы. Попробуйте предоставить разрешения только для чтения, если это необходимо, и максимально ограничить доступ.

При создании personal access token (classic)выберите самые необходимые области. При создании fine-grained personal access tokenвыберите минимальные разрешения и необходимый доступ к репозиторию.

Вместо использования personal access tokenрекомендуется использовать GitHub App, которая использует точные разрешения и короткие маркеры, аналогичные fine-grained personal access token. В отличие от personal access token, GitHub App не привязан к пользователю, поэтому рабочий процесс будет продолжать работать, даже если пользователь, установивший приложение, покидает вашу организацию. Дополнительные сведения см. в разделе Выполнение запросов API с проверкой подлинности с помощью приложения GitHub в рабочем процессе GitHub Actions.

Создание секретов для репозитория

gh secret set SECRET_NAME

gh secret set SECRET_NAME < secret.txt

Создание секретов для среды

Чтобы создать секреты или переменные для среды в репозитории личная учетная запись, необходимо быть владельцем репозитория. Чтобы создать секреты или переменные для среды в репозитории организации, необходимо иметь admin доступ. Дополнительные сведения о средах см. в разделе "Управление средами для развертывания".

gh secret set --env ENV_NAME SECRET_NAME

gh secret list --env ENV_NAME

Создание секретов для организации

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

Проверка доступа к секретам на уровне организации

Вы можете проверить, какие политики доступа применяются к секрету в вашей организации.

1. На GitHubперейдите на главную страницу организации.

2. Под именем организации щелкните Settings. Если вкладка "Параметры" не отображается, выберите раскрывающееся меню и нажмите кнопку "Параметры".

   

3. Список секретов включает все настроенные разрешения и политики. Дополнительные сведения о настроенных разрешениях для каждого секрета нажмите кнопку "Обновить".

Использование секретов в рабочем процессе

Чтобы указать действие с секретом в качестве входных данных или переменной среды, можно использовать контекст secrets для доступа к секретам, созданным в репозитории. Дополнительные сведения см. в разделе [AUTOTITLE и Доступ к контекстной информации о запусках рабочих процессов](/actions/using-workflows/workflow-syntax-for-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 }}

На секреты нельзя напрямую ссылаться в условных выражениях if:. Вместо этого рекомендуется задать секреты в качестве переменных среды на уровне задания, а затем создать ссылки на переменные среды для условного выполнения шагов в задании. Дополнительные сведения см. в разделе Доступ к контекстной информации о запусках рабочих процессов иjobs.<job_id>.steps[*].if .

Если секрет не задан, возвращаемое значение выражения, которое ссылается на этот секрет (например, ${{ secrets.SuperSecret }} в примере) будет пустой строкой.

По возможности избегайте передачи секретов между процессами из командной строки. Процессы командной строки могут быть видимы для других пользователей (с помощью команды ps) или сканируются событиями аудита безопасности. Чтобы обеспечить защиту секретов, рассмотрите возможность использования переменных среды, STDINили других механизмов, поддерживаемых целевым процессом.

Если необходимо передать секреты в командной строке, добавьте их в соответствующие правила . Секреты зачастую содержат специальные символы, которые могут непреднамеренно повлиять на оболочку. Чтобы экранировать эти специальные символы, заключайте переменные среды в кавычки. Например:

Пример с использованием Bash

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

Пример с использованием PowerShell

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

Пример с использованием Cmd.exe

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

Ограничения для секретов

Можно хранить до 1000 секретов организации, 100 секретов репозитория и 100 секретов среды.

Рабочий процесс, созданный в репозитории, может получить доступ к следующему количеству секретов:

• Все 100 секретов в репозитории
• Если репозиторию назначен доступ к более чем 100 секретам организации, рабочий процесс может использовать только первые 100 секретов организации (отсортированные по имени в алфавитном порядке).
• Все 100 секретов среды.

Секреты ограничены размером 48 КБ. Чтобы сохранить более крупные секреты, см . обходное решение по хранению больших секретов ниже.

Хранение больших секретов

Чтобы использовать секреты размером более 48 КБ, можно использовать обходное решение для хранения секретов в репозитории и сохранения парольной фразы расшифровки в виде секрета на GitHub. Например, можно использовать gpg для локального шифрования файла, содержащего секрет, прежде чем добавлять файл в репозиторий на GitHub. Дополнительные сведения см. в gpg manpage.

1. Выполните следующую команду на терминале, чтобы зашифровать файл, содержащий секрет, с помощью gpg и алгоритма шифра AES256. В этом примере секрет содержит файл my_secret.json.

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

2. Вам будет предложено ввести парольную фразу. Запомните парольную фразу, так как вам потребуется создать новый секрет в GitHub, который использует парольную фразу как значение.

3. Создайте новый секрет, который содержит парольную фразу. Например, создайте новый секрет с именем LARGE_SECRET_PASSPHRASE и задайте для секрета парольную фразу, использованную на предыдущем шаге.

4. Скопируйте зашифрованный файл в путь в репозитории и выполните его фиксацию. В этом примере зашифрованный файл имеет значение my_secret.json.gpg.

   Warning

   Обязательно скопируйте зашифрованный my_secret.json.gpg файл, .gpg заканчивающийся расширением файла, а не незашифрованный my_secret.json файл.

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

5. Создайте скрипт оболочки в репозитории для расшифровки файла секрета. В этом примере секрет называется 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. Перед возвратом в репозиторий убедитесь, что скрипт оболочки является исполняемым.

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

7. В рабочем процессе GitHub Actions используйте step для вызова скрипта оболочки и расшифровки секрета. Чтобы создать копию репозитория в среде, в которой выполняется рабочий процесс, необходимо использовать действие actions/checkout. Создайте ссылку на сценарий оболочки с помощью команды run относительно корня репозитория.

   name: Workflows with large secrets
   
   on: push
   
   jobs:
     my-job:
       name: My Job
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - 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
   

Хранение двоичных BLOB-объектов Base64 в виде секретов

Кодировку Base64 можно использовать для хранения небольших BLOB-объектов в виде секретов. Затем можно создать ссылку на секрет в рабочем процессе и декодировать его для использования в средстве выполнения тестов. Ограничения размера см. в разделе Использование секретов в GitHub Actions.

1. Используйте base64 для кодирования файла в строку Base64. Например:

   В macOS можно выполнить следующее:

   base64 -i cert.der -o cert.base64
   

   В Linux можно выполнить следующее:

   base64 -w 0 cert.der > cert.base64
   

2. Создайте секрет, который содержит строку Base64. Например:

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

3. Чтобы получить доступ к строке Base64 из средства выполнения тестов, передайте секрет в base64 --decode. Например:

   name: Retrieve Base64 secret
   on:
     push:
       branches: [ octo-branch ]
   jobs:
     decode-secret:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - 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
   

Изменение секретов из журналов выполнения рабочего процесса

GitHub Actions автоматически редактирует содержимое всех секретов GitHub , которые печатаются в журналах рабочих процессов.

GitHub Actions также редактирует информацию, которая распознается как конфиденциальная, но не хранится в виде секрета. В настоящее время GitHub поддерживает следующее:

• 32-байтовые и 64-байтовые ключи Azure
• Пароли клиентского приложения Azure AD
• Ключи кэша Azure
• ключи Реестр контейнеров Azure
• Ключи узла функции Azure
• Ключи поиска Azure
• Строки подключения к базам данных
• Заголовки маркера носителя HTTP
• JWTs
• Маркеры автора NPM
• Ключи API NuGet
• Токены установки GitHub версии 1
• Токены установки GitHub версии 2 (ghp, , ghu``gho, ghs``ghr)
• GitHub PATs версии 2

В качестве привычки рекомендуется маскировать все конфиденциальные сведения, которые не являются секретом GitHub с помощью ::add-mask::VALUE. Это приводит к тому, что значение будет рассматриваться как секрет и отредактировано из журналов. Дополнительные сведения о маскировки данных см. в разделе Команды рабочего процесса для GitHub Actions.

Редактирование секретов выполняется средствами выполнения рабочих процессов. Это означает, что секрет будет отредактирован только в том случае, если он использовался в задании и доступен средством выполнения. Если нередактируемый секрет отправляется в журнал выполнения рабочего процесса, следует удалить журнал и повернуть секрет. Сведения об удалении журналов см. в разделе Использование журналов выполнения рабочих процессов.