Skip to main content

Автоматическая проверка подлинности токенов

GitHub предоставляет маркер, который можно использовать для проверки подлинности от имени GitHub Actions.

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

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

При включении GitHub Actions GitHub устанавливает GitHub App в репозитории. Секрет GITHUB_TOKEN — это маркер доступа установки GitHub App. Маркер доступа установки можно использовать для проверки подлинности от имени установленного в репозитории GitHub App. Разрешения маркера ограничены репозиторием, содержащим рабочий процесс. Дополнительные сведения см. в разделе «Разрешения дляGITHUB_TOKEN».

Перед началом выполнения каждого задания GitHub получает маркер доступа установки для задания. Срок действия GITHUB_TOKEN истекает при завершении задания или в течение не более 24 часов.

Маркер также доступен в контексте github.token. Дополнительные сведения см. в разделе Доступ к контекстной информации о запусках рабочих процессов.

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

GITHUB_TOKEN можно использовать со стандартным синтаксисом для ссылки на секреты: ${{ secrets.GITHUB_TOKEN }}. К примерам использования GITHUB_TOKEN относятся передача маркера в качестве входных данных для действия или его использование для выполнения прошедшего проверку подлинности GitHub запроса API.

Важно! Действие может получить доступ к GITHUB_TOKEN через контекст github.token, даже если рабочий процесс явно не передает GITHUB_TOKEN действию. Из соображений безопасности рекомендуется всегда предоставлять действиям минимальный необходимый доступ путем ограничения разрешений, предоставленных GITHUB_TOKEN. Дополнительные сведения см. в разделе «Разрешения дляGITHUB_TOKEN».

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

Фиксации, отправленные рабочим процессом GitHub Actions с использованием GITHUB_TOKEN сборки GitHub Pages.

Пример 1. Передача GITHUB_TOKEN в качестве входных данных

В этом примере рабочий процесс использует интерфейс командной строки GitHub, для которого требуется GITHUB_TOKEN значение входного GH_TOKEN параметра:

YAML
name: Open new issue
on: workflow_dispatch

jobs:
  open-issue:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
    steps:
      - run: |
          gh issue --repo ${{ github.repository }} \
            create --title "Issue title" --body "Issue body"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Пример 2. Вызов REST API

GITHUB_TOKEN можно использовать для выполнения вызовов API, прошедших проверку подлинности. В этом примере рабочего процесса создается проблема с помощью REST API GitHub:

name: Create issue on commit

on: [ push ]

jobs:
  create_issue:
    runs-on: ubuntu-latest
    permissions:
      issues: write
    steps:
      - name: Create issue using REST API
        run: |
          curl --request POST \
          --url https://api.github.com/repos/${{ github.repository }}/issues \
          --header 'authorization: Bearer ${{ secrets.GITHUB_TOKEN }}' \
          --header 'content-type: application/json' \
          --data '{
            "title": "Automated issue for commit: ${{ github.sha }}",
            "body": "This issue was automatically created by the GitHub Action workflow **${{ github.workflow }}**. \n\n The commit hash was: _${{ github.sha }}_."
            }' \
          --fail

Разрешения для GITHUB_TOKEN

Сведения о конечных точках API GitHub Apps могут получить доступ с каждым разрешением, см. в разделе "Разрешения, необходимые для приложений GitHub".

В следующей таблице показаны разрешения, предоставленные для GITHUB_TOKEN по умолчанию. Пользователи с разрешениями администратора для корпорации, организации или репозитория могут задавать разрешения по умолчанию в качестве разрешительных или ограничительных. Сведения о настройке разрешений по умолчанию для GITHUB_TOKEN предприятия, организации или репозитория см. в разделе "[AUTOTITLE", "[AUTOTITLE" илиОтключение или ограничение GitHub Actions для вашей организации](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise#enforcing-a-policy-for-workflow-permissions-in-your-enterprise)](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#setting-the-permissions-of-the-github_token-for-your-repository)".

ОбластьДоступ по умолчанию
(разрешительное)
Доступ по умолчанию
(ограничительное)
Максимальный доступ для
Запросы на вытягивание из
общедоступные вилки репозиториев
actionsчтение/записьничегочтение
attestationsчтение/записьничегочтение
checksчтение/записьничегочтение
содержаниечтение/записьчтениечтение
службчтение/записьничегочтение
Обсуждениячтение/записьничегочтение
id-tokenничегоничегоничего
службчтение/записьничегочтение
metadataчтениечтениечтение
службчтение/записьreadчтение
pagesчтение/записьничегочтение
pull-requestsчтение/записьничегочтение
repository-projectsчтение/записьничегочтение
security-eventsчтение/записьничегочтение
Статусычтение/записьничегочтение

Примечания:

  • При активации pull_request_target рабочего процесса событием GITHUB_TOKEN предоставляется разрешение на чтение и запись репозитория, даже если он активируется из общедоступной вилки. Дополнительные сведения см. в разделе События, инициирующие рабочие процессы.
  • Частные репозитории могут контролировать, могут ли запросы на вытягивание из вилок запускать рабочие процессы и настраивать разрешения, назначенные GITHUB_TOKEN. Дополнительные сведения см. в разделе Управление параметрами GitHub Actions для репозитория.
  • Рабочий процесс запускается с помощью запросов на вытягивание Dependabot, как если бы они выполнялись из вилированного репозитория и поэтому используют только GITHUB_TOKENдля чтения. Этот рабочий процесс не может получить доступ к секретам. Сведения о стратегиях защиты этих рабочих процессов см. в разделе "Защита системы безопасности для GitHub Actions".

Изменение разрешений для GITHUB_TOKEN

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

Посмотреть разрешения, выданные GITHUB_TOKEN для выполнения определенного задания, можно в разделе «Настройка задания» журнала выполнения рабочего процесса. Дополнительные сведения см. в разделе Использование журналов выполнения рабочих процессов.

Ключ permissions в файле рабочего процесса можно использовать для изменения разрешений GITHUB_TOKEN для всего рабочего процесса или отдельных заданий. Это позволяет настроить минимально необходимые разрешения для рабочего процесса или задания. При использовании ключа permissions для всех неуказанных разрешений доступ запрещен. Исключение составляет область metadata, которая всегда получает доступ на чтение.

С помощью ключа permissions можно добавлять и удалять разрешения на чтение для разветвленных репозиториев, но обычно предоставить доступ на запись нельзя. Исключением из этого поведения является то, что пользователь администратора выбрал Отправлять маркеры записи в рабочие процессы из запросов на вытягивание в параметрах GitHub Actions. Дополнительные сведения см. в разделе Управление параметрами GitHub Actions для репозитория.

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

Полные сведения о permissions ключе см. в разделе "Синтаксис рабочего процесса для GitHub Actions".

Примечание. Владельцы организации могут запретить предоставлять доступ на GITHUB_TOKEN запись на уровне репозитория. Дополнительные сведения см. в разделе "Отключение или ограничение GitHub Actions для вашей организации".

Расчет разрешений для задания рабочего процесса

Изначально в качестве разрешений для GITHUB_TOKEN задаются параметры по умолчанию для предприятия, организации или репозитория. Если на любом из этих уровней по умолчанию заданы ограниченные разрешения, они будут применяться к соответствующим репозиториям. Например, если выбрать в качестве значения по умолчанию на уровне организации ограниченные разрешения, все репозитории в этой организации будут использовать в качестве значения по умолчанию ограниченные разрешения. Затем разрешения корректируются на основе любой конфигурации в файле рабочего процесса: сначала на уровне рабочего процесса, а затем на уровне задания. Наконец, если рабочий процесс был активирован запросом на вытягивание из разветвленного репозитория, а параметр Отправлять маркеры записи отправлять в рабочие процессы из запросов на вытягивание не выбран, разрешения корректируются, чтобы изменить любые разрешения на запись на разрешения только на чтение.

Предоставление дополнительных разрешений

Если вам нужен маркер, требующий разрешений, недоступных в GITHUB_TOKENприложении, можно создать GitHub App и создать маркер доступа к установке в рабочем процессе. Дополнительные сведения см. в разделе Выполнение запросов API с проверкой подлинности с помощью приложения GitHub в рабочем процессе GitHub Actions. Кроме того, можно создать personal access token, сохранить его в качестве секрета в репозитории и использовать маркер в рабочем процессе с синтаксисом ${{ secrets.SECRET_NAME }} . Дополнительные сведения см. в разделе "[AUTOTITLE" и "Управление личными маркерами доступа](/actions/security-guides/using-secrets-in-github-actions)".

Дополнительные материалы