Использование пользовательских изображений

Пользовательские образы

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

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

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

Предпосылки

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

•         **Политика**: пользовательские образы должны быть включены для вашей организации или предприятия. Владельцы предприятия могут управлять доступом к пользовательским образам и настраивать политики хранения в параметрах политики действий. Дополнительные сведения см. в разделе [AUTOTITLE](/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise#custom-images).
  

• Разрешения: чтобы создавать пользовательские образы и управлять ими, вы должны быть владельцем организации или предприятия, или иметь роль, или CI/CD Admin иметь роль со следующими детализированными разрешениями.

  • Просмотр пользовательских образов размещенного в организации средства выполнения тестов
  • Управление пользовательскими образами размещенного в организации средства выполнения тестов
  • Управление группами runner и runner организации

  Дополнительные сведения см. в разделе Разрешения на кастомные организационные роли.

Настройка средства запуска генерации изображений

Чтобы создать пользовательский образ, необходимо сначала настроить средство запуска создания образов. При создании средства выполнения тестов платформа, выбранная для средства выполнения, должна совпадать с платформой образа, который требуется создать. Платформой раннера может быть Linux x64, Linux ARM64 или Windows x64.

1. Создайте рекомендует еженедельно настраивать генерацию изображений как запланированный рабочий процесс. Такой подход гарантирует, что зависимости остаются up-to-date и содержат последние обновления безопасности. Дополнительные сведения см. в разделе События, инициирующие рабочие процессы.

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

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

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

Строковый синтаксис

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

jobs: 
  build:
    runs-on: my-image-generation-runner
    snapshot: my-custom-image
    steps:
      # Add any steps to download and setup any dependencies here

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

Вы можете использовать синтаксис сопоставления с snapshot для определения как одного, image-name так и необязательного version. Когда вы указываете основную версию, дополнительная версия автоматически увеличивается, если эта основная версия уже существует. Версии патчей не поддерживаются.

jobs: 
  build:
    runs-on: my-image-generation-runner
    snapshot: 
        image-name: my-custom-image
        version: 2.*
    steps:
      # Add any steps to download and setup any dependencies here

Управление версиями

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

Поведение по умолчанию

Если изображение с указанным именем не существует в вашей организации или предприятии, GitHub создает его с начальным номером версии 1.0.0. Если изображение с таким же именем уже существует, GitHub создает новую версию, увеличивая младший номер версии (например, 1.1.0, 1.2.0 и т. д.).

Если вы не укажете версию в файле YAML, при создании изображений будет использоваться это поведение по умолчанию.

Указание версии в рабочем процессе

Если вы включаете версию в сопоставление YAML, GitHub сначала проверяет основной номер версии.

• Если указанная основная версия уже существует, то в новом образе используется следующая дополнительная версия (например, 1.0 становится 1.1).
• Если мажорная версия не существует, GitHub создает новую мажорную версию (например, 2.0).

Версии патчей не поддерживаются.

Последний тег

Самый последний запуск рабочего процесса для изображения всегда помечается как последний. Если вы указываете более старую основную версию в YAML (например, version: 1.*, если существует версия 2.0), GitHub генерирует новую дополнительную версию под старой основной версией и помечает ее как новую.

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

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

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

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

   

3. На левой боковой панели нажмите Действия, затем нажмите Пользовательские изображения.

4. На странице "Пользовательские изображения" вы можете просмотреть все пользовательские образы, созданные в вашей организации или предприятии.

5. Чтобы просмотреть сведения о конкретном изображении, нажмите на его название.

Установка пользовательских образов

Как только ваш пользовательский образ будет готов, вы можете установить его на новый Более крупное средство выполнения, размещенное в GitHub.

1. Следуйте инструкциям по созданию крупное средство выполнения:

   • Сведения об организациях см. в разделе Добавление более крупного средства выполнения тестов в организацию.
   • Сведения о предприятиях см. в разделе Добавление более крупного средства выполнения тестов в предприятие.

2. При настройке бегуна: * Платформа: выберите ту же платформу, которую вы использовали для создания образа (Linux x64, Linux ARM64 или Windows x64). * Изображение: выберите вкладку «Пользовательский », затем выберите свое пользовательское изображение из списка.

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

   •      **Версия образа**: выберите **Последняя** , чтобы автоматически использовать самую последнюю версию, или выберите конкретный номер версии, чтобы закрепить средство выполнения этой версии.
     

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

   •      **Размер**: выберите размер бегуна с объемом памяти, равным или превышающим размер вашего изображения. Например, если образ был создан на 8-ядерном средстве выполнения, выберите 8-ядерный или более крупный для запуска этого образа.
     

   •      **Группа средств выполнения**: назначьте средство выполнения тестов группе средств выполнения, которая является общей для репозиториев, которым необходимо использовать этот образ.
     

3. В задании рабочего процесса GitHub Actions установите runs-on ключ к имени средства выполнения.

   jobs: 
     build:
       runs-on: my-custom-runner
       steps:
       # Add any steps for your workflow here
   

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

Лучшие практики безопасности для пользовательских изображений

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

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

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

•         **Применяйте наименьшие привилегии к репозиториям.** Избегайте предоставления общеорганизационного `write` доступа для репозиториев, имеющих доступ к раннерам генерации изображений. Поскольку изображения можно генерировать из любой ветки, любой, обладающий доступом к записи, мог создать ветку с произвольным кодом и запустить генерацию изображений.