Автоматизация установки приложений в организациях предприятия

Введение

Чтобы автоматизировать процесс безопасно, можно создать GitHub App учетную запись предприятия, а затем установить приложение в организации или организации, где будет проходить автоматизация.

GitHub Apps предоставьте маркеры, которые можно использовать для проверки подлинности вызовов GitHub API в сценариях и рабочих процессах. Эти токены подходят для предприятий с особыми требованиями к безопасности и аудиту, потому что они:

• Временный
• Ограничен определенными учетными записями и разрешениями
• Связано с удостоверением приложения, а не с учетной записью пользователя

Общей потребностью крупных предприятий является обеспечение согласованности и up-toавтоматизации во многих организациях. Это можно сделать, установив приложение программным способом. Например, если необходимо настроить все организации с определенными политиками и параметрами, можно установить GitHub App эту задачу в каждой организации.

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

Обзор процесса

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

Вот что нужно сделать:

1. Создайте два приложения, которые принадлежат вашей корпоративной учетной записи.
   • У вас будет разрешение на установку приложений в организациях.
   • Другой будет иметь разрешение на автоматизацию процесса в организации (в данном случае на создание репозитория).
2. Проверьте подлинность первого приложения, чтобы получить маркер доступа на уровне предприятия .
3. Используйте маркер уровня предприятия для вызова API, который устанавливает приложение автоматизации в организации.
4. Пройдите проверку подлинности приложения, установленного в организации, чтобы получить маркер доступа на уровне организации .
5. Используйте маркер на уровне организации для вызова API, который создает репозиторий в организации.

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

Предпосылки

Чтобы следовать этому руководству на своем устройстве, необходимо:

• Станьте владельцем предприятия.
• Будьте владельцем корпоративной организации, в которой вы будете выполнять автоматизацию.
• GitHub CLI Установите для выполнения вызовов API. См. раздел "Установка " в репозитории GitHub CLI .
• Установлены openssl для того, чтобы сгенерировать веб-токен JSON (JWT). На многих устройствах по умолчанию установлен OpenSSL. Вы можете проверить это, выполнив команду openssl -v, которая возвращает номер версии, если она установлена.
• Используйте оболочку Unix, такую как Bash, ZSH или Git Bash.

1. Подготовка к генерации JWT

Чтобы запросить маркер доступа от приложения, вам потребуется веб-маркер JSON (JWT), созданный на основе идентификатора клиента и закрытого ключа приложения. Многие языки программирования имеют встроенные методы для генерации JWT. В этом руководстве вы будете использовать сценарий Bash для создания JWT из командной строки с помощью openssl.

1. Скопируйте содержимое скрипта Bash для генерации JWT из AUTOTITLE.

2. Сохраните содержимое в новом файле в вашем домашнем каталоге с именем gen-jwt.sh.

3. Сделайте скрипт исполняемым.

   Shell

   chmod +x ~/gen-jwt.sh
   

2. Создайте два корпоративных приложения

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

a. Создание приложения установщика

«Приложение-установщик» будет установлено в корпоративной учетной записи и будет иметь разрешение на установку другого приложения в организации.

1. Создайте новое приложение в корпоративной учетной записи.

   1. Перейдите в настройки корпоративной учетной записи.
   2. В левой боковой панели щелкните GitHub Apps.
   3. Нажмите «Новое GitHub App».

2. Вы можете оставить большинство значений по умолчанию, за исключением:

   • Вызовите приложение YOUR-HANDLE-installer-app, заменив YOUR-HANDLE имя GitHub пользователя.
   • Установите для параметра "URL домашней страницы" значение https://github.com.
   • Снимите флажок Expire user authorization tokens и в разделе "Webhook" снимите флажок Active.
   • В разделе "Корпоративные разрешения" предоставьте приложению разрешения на чтение и запись для установок корпоративной организации.

3. После создания приложения скопируйте идентификатор клиента и сохраните его как переменную с именем INSTALLER_APP_CLIENT_ID. Например, в командной строке:

   Shell

   export INSTALLER_APP_CLIENT_ID='abcde12345'
   

4. На странице приложения прокрутите вниз и нажмите «Сгенерировать закрытый ключ». Файл с закрытым ключом будет загружен.

5. Обратите внимание на путь к файлу, который будет выглядеть примерно так.~/YOUR-HANDLE-installer-app.DOWNLOAD-DATE.private-key.pem

6. На левой боковой панели страницы приложения нажмите «Установить приложение», затем установите новое приложение в корпоративной учетной записи. Установка приложения дает приложению разрешение на выполнение действий в учетной записи.

7. Просмотрите URL-адрес в браузере, чтобы найти идентификатор установки приложения. Это строка цифр в конце URL-адреса /enterprises/ENTERPRISE/settings/installations/ID . Сохраните это как INSTALLER_APP_INSTALL_ID переменную.

   Shell

   export INSTALLER_APP_INSTALL_ID='12345678'
   

8. Сохраните название предприятия, на котором установлено приложение, в качестве переменной.

   Shell

   export ENTERPRISE='octo-enterprise'
   

б. Создание приложения автоматизации

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

1. Создайте новое приложение в корпоративной учетной записи.

   • Вызовите приложение YOUR-HANDLE-automation-app, заменив YOUR-HANDLE имя GitHub пользователя.
   • Установите для параметра "URL домашней страницы" значение https://github.com.
   • Снимите флажок Expire user authorization tokens и в разделе "Webhook" снимите флажок Active.
   • В разделе "Разрешения репозитория" предоставьте приложению разрешения на чтение и запись для администрирования.

2. После создания приложения скопируйте идентификатор клиента и сохраните его в качестве AUTOMATION_APP_CLIENT_ID переменной.

   Shell

   export AUTOMATION_APP_CLIENT_ID='abcde12345'
   

3. Прокрутите вниз и нажмите Сгенерировать закрытый ключ. Файл с закрытым ключом будет загружен.

4. Обратите внимание на путь к файлу, который будет выглядеть примерно так.~/YOUR-HANDLE-automation-app.DOWNLOAD-DATE.private-key.pem

5. Сохраните название организации, в которой будет установлено приложение, в качестве переменной.

   Shell

   export ORG='octo-org'
   

3. Аутентифицируйте приложение-установщик

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

1. Сгенерируйте JWT с помощью сохраненного скрипта Bash. Рассмотрим пример.

   Shell

   ~/gen-jwt.sh $INSTALLER_APP_CLIENT_ID ~/YOUR-HANDLE-installer-app.DOWNLOAD-DATE.private-key.pem
   

2. Скопируйте JWT (длинную строку после JWT= ) и сохраните его как переменную.

   Shell

   export INSTALL_JWT='abcde12345'
   

3. Используйте JWT для проверки подлинности запроса на маркер доступа к установке. На этом шаге используется параметр Создание маркера доступа установки для конечной точки API приложения и требуется идентификатор установки приложения.

   Shell

   gh api --method POST "/app/installations/$INSTALLER_APP_INSTALL_ID/access_tokens" --header "Authorization: Bearer $INSTALL_JWT"
   

4. Вы должны увидеть объект JSON, содержащий свойство token . Скопируйте токен доступа (значение token свойства, без кавычек) и сохраните его как INSTALLER_APP_INSTALL_TOKEN переменную.

   Shell

   export INSTALLER_APP_INSTALL_TOKEN='abcde12345'
   

4. Установите приложение для автоматизации

Только что полученный маркер доступа к установке дает разрешение на вызов API для установки приложений в организации. Здесь мы будем использовать токен для установки приложения автоматизации (второго созданного вами приложения) в конкретной организации. На самом деле вы можете вызывать этот API несколько раз, чтобы установить приложение в нескольких организациях.

1. Выполните следующую команду. Мы используем конечную точку API для установки приложения GitHub в конечной точке API, принадлежащей корпоративной организации , проходим проверку подлинности с помощью только что запрошенного маркера установки и передаем идентификатор клиента приложения автоматизации, которое мы хотим установить.

   Shell

   gh api --method POST \
     "/enterprises/$ENTERPRISE/apps/organizations/$ORG/installations" \
     --header "Authorization: Bearer $INSTALLER_APP_INSTALL_TOKEN" \
     --header "Accept: application/vnd.github+json" \
     --header "X-GitHub-Api-Version: 2022-11-28" \
     --field "client_id=$AUTOMATION_APP_CLIENT_ID" \
     --field "repository_selection=all"
   

2. В случае успеха вы должны увидеть большое количество возвращенных свойств, начиная с идентификатора установки приложения.

   Чтобы проверить, что приложение было успешно установлено, перейдите в раздел https://github.com/organizations/ORG/settings/installations, заменив ORG на название организации. Вы должны увидеть только что установленное приложение на странице.

3. Найдите идентификатор установки новой установки и сохраните его как AUTOMATION_APP_INSTALL_ID. Чтобы найти идентификатор, вы можете либо скопировать первое свойство идентификатора, возвращенное API, либо нажать кнопку Настроить рядом с установкой приложения в пользовательском интерфейсе и скопировать идентификатор из URL-адреса.

   Shell

   export AUTOMATION_APP_INSTALL_ID='12345678'
   

5. Аутентификация приложения автоматизации

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

1. Создайте JWT с идентификатором клиента и закрытым ключом приложения автоматизации. Рассмотрим пример.

   Shell

   ~/gen-jwt.sh $AUTOMATION_APP_CLIENT_ID ~/octocat-automation-app.2025-10-08.private-key.pem
   

2. Скопируйте JWT (длинную строку после JWT= ) и сохраните его как переменную.

   Shell

   export AUTO_JWT='abcde12345'
   

3. Используйте JWT для проверки подлинности запроса на маркер доступа к установке, на этот раз передав идентификатор установки и JWT для только что установленного приложения автоматизации.

   Shell

   gh api --method POST "/app/installations/$AUTOMATION_APP_INSTALL_ID/access_tokens" --header "Authorization: Bearer $AUTO_JWT"
   

4. Скопируйте новый маркер доступа к установке и сохраните его в качестве AUTOMATION_APP_INSTALL_TOKEN переменной.

   Shell

   export AUTOMATION_APP_INSTALL_TOKEN='abcde12345'
   

6. Автоматизируйте процесс

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

1. Выполните следующую команду. Обратите внимание, что мы аутентифицируемся с помощью только что полученного маркера установки.

   Shell

   gh api --method POST \
     "/orgs/$ORG/repos" \
     --header "Authorization: Bearer $AUTOMATION_APP_INSTALL_TOKEN" \
     --header "Accept: application/vnd.github+json" \
     --header "X-GitHub-Api-Version: 2022-11-28" \
     --field "name=automatic-repo" \
     --field "description=Repository created automatically using GitHub App automation" \
     --field "private=false" \
     --field "auto_init=true"
   

2. Чтобы проверить, что репозиторий был успешно создан, перейдите в раздел https://github.com/orgs/ORG/repositories, заменив ORG на название вашей организации.

7. Удалите приложения

В целях безопасности удалите приложения из предприятия и организации. Это приведет к отзыву всех токенов, связанных с приложениями. Инструкции см. в разделе Обзор и изменение установленных приложений GitHub.

Дальнейшие шаги

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