Зашифрованные секреты

Сведения о зашифрованных секретах

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

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

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

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

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

• Имена могут содержать только буквенно-цифровые символы ([a-z], [A-Z], [0-9]) или символы подчеркивания (_). Пробелы недопустимы.

• Имена не должны начинаться GITHUB_ с префикса.

• Имена не должны начинаться с числа.

• В именах не учитывается регистр символов.

• Имена должны быть уникальными на уровне, на который они создаются.

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

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

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

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

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

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

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

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

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

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

При создании personal access token выберите наименьшее необходимое количество областей.

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

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

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

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

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

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

Чтобы создать секреты на уровне организации, у вас должен быть admin доступ.

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 Enterprise Server перейдите на главную страницу организации. 1. Под названием организации щелкните Параметры. Если вкладка "Параметры" не отображается, выберите раскрывающееся меню и щелкните Параметры.

   1. В разделе "Безопасность" боковой панели выберите Секреты, , а затем щелкните Действия.

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

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

Чтобы указать действие с секретом в качестве входных данных или переменной среды, можно использовать контекст secrets для доступа к секретам, созданным в репозитории. Дополнительные сведения см. в разделах Контексты и Синтаксис рабочего процесса для 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.

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

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

5. Создайте скрипт оболочки в репозитории для расшифровки файла секрета. В этом примере секрет называется decrypt_secret.sh.

   #!/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@v3
         - 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-объектов в виде секретов. Затем можно создать ссылку на секрет в рабочем процессе и декодировать его для использования в средстве выполнения тестов. Ограничения размера см. в разделе Зашифрованные секреты.

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

   $ base64 -i cert.der -o 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@v3
         - 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