Создание пользовательского действия GitHub

  • 8 мин

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

Типы действий GitHub

Схема, отображающая три типа GitHub Actions; Действия Docker, JavaScript и составных шагов выполнения.

Действия — это отдельные задачи, которые можно использовать для настройки рабочих процессов разработки. Вы можете создать собственные действия, написав пользовательский код, взаимодействующий с репозиторием для выполнения пользовательских задач, или с помощью действий, общих папок сообщества GitHub. Навигация по различным действиям вы заметите, что существует три различных типа действий: действия контейнера Docker, действия JavaScript и составные действия выполнения. Рассмотрим каждый из типов действий подробнее.

Действия контейнера Docker

Контейнеры Docker упаковывают среду с кодом GitHub Actions. Это означает, что действие выполняется в согласованной и надежной среде, так как все его зависимости находятся в этом контейнере. Если действие должно выполняться в определенной конфигурации среды, контейнеры Docker являются хорошим способом, так как вы можете настроить операционную систему и средства. Недостаток состоит в том, что, поскольку задание должно создавать и извлекать контейнер, действия контейнера Docker часто выполняются медленнее, чем действия JavaScript.

Перед созданием действия контейнера Docker необходимо иметь некоторое общее представление об использовании переменных среды и файловой системы контейнера Docker. Действия, которые необходимо выполнить для создания действия контейнера Docker, минимальны и просты:

  1. Создайте Dockerfile, чтобы определить команды для сборки образа Docker.
  2. Создайте файл метаданных action.yml для определения входных и выходных данных действия. Установите значение runs: using: на docker и значение runs: image: на Dockerfile в файле.
  3. Создайте файл entrypoint.sh для описания образа Docker.
  4. Зафиксируйте и отправьте свое действие в GitHub со следующими файлами: action.yml, entrypoint.sh, Dockerfile и README.md.

Действия JavaScript

Действия JavaScript могут выполняться непосредственно на компьютере runner и отделять код действия от среды, которая используется для выполнения действия. Благодаря этому код действия упрощен и может выполняться быстрее, чем действия в контейнере Docker.

В качестве необходимого компонента для создания и использования упакованных действий JavaScript необходимо скачать Node.js, включающий NPM. Как необязательный шаг (но рекомендуемый) — использовать набор средств GitHub Actions Node.js, который представляет собой коллекцию пакетов Node.js, что позволяет быстро создавать действия JavaScript с большей согласованности.

Шаги по созданию действия JavaScript являются минимальными и простыми:

  1. action.yml Создайте файл метаданных, чтобы определить входные и выходные данные действия, а также сообщить средству выполнения действия, как начать выполнение этого действия JavaScript.
  2. Создайте файл index.js со сведениями о контексте пакетов набора средств, маршрутизации и других функций действия.
  3. Зафиксируйте и отправьте свое действие в GitHub со следующими файлами: action.yml, index.js, node_modules, package.json, package-lock.json и README.md.

Действия составных шагов выполнения

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

Метаданные и синтаксис, необходимые для создания действия

При создании или проверке действия GitHub рекомендуется просмотреть action.yml файл, чтобы оценить входные данные, выходные данные, описание, запуски и другие сведения о конфигурации, необходимые действия. Некоторые из этих параметров являются обязательными, а другие — необязательными. В файле action.yml определены следующие сведения о действии:

Параметр Описание: Обязательное поле
Имя. Имя действия. Помогает визуально определить действие в задании. yes
Описание: Сводка того, что делает действие. yes
Входные данные Входные параметры позволяют указать данные, которые действие предполагает использовать во время выполнения. Эти параметры становятся переменными среды в средстве выполнения. no
Выходные данные Выходные параметры позволяют указать данные, которые последующие действия могут использовать позже в рабочем процессе после выполнения действия, определяющего эти выходные данные. no
Запуски Команда, запускаемая при выполнении действия. yes
Фирменная символика Значок "Цвет и растушевка", используемый для создания эмблемы, которая позволяет персонализировать и различать действия в GitHub Marketplace. no

Входные данные

Входные данные — это параметры, позволяющие указать данные, которые действие ожидает использовать во время выполнения. GitHub хранит эти входные параметры как переменные среды.

Ниже приведен пример списка входных данных для действия. Входные firstNameStudent данные являются необязательными, а studentGrade входные данные являются обязательными.

inputs:
  firstNameStudent:
    description: 'First name of student'
    required: false
    default: '1'
  studentGrade:
    description: 'Grade of the student'
    required: true

Выходные данные

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

Следующий пример — это простой результат для объявления среднего класса учащихся:

outputs:
  average:
    description: 'The average grade of the students'

Запуски

Как вы узнали ранее, в действии необходимо иметь инструкцию runs, которая определяет команду, необходимую для выполнения действия. В зависимости от того, как вы создаете действие , независимо от того, используете ли вы контейнер Docker, JavaScript или составные шаги выполнения, runs синтаксис определяется по-разному.

runs для действий Docker

Действия контейнера Docker требуют инструкции runs для настройки образа, который использует действие Docker со следующими аргументами:

  • using: необходимо задать для docker запуска действия контейнера Docker
  • image: образ Docker, используемый в качестве контейнера для запуска действия
runs:
  using: 'docker'
  image: 'Dockerfile'

runs для действий JavaScript

Действия JavaScript предполагают, что инструкция runs принимает следующие два аргумента:

  • using: приложение, используемое для выполнения кода, как определено в main
  • main: файл, содержащий код действия; приложение, определенное в using выполнении этого файла

Например, вот runs инструкция для действия JavaScript с помощью Node.js:

runs:
  using: 'node12'
  main: 'main.js'

runs для действий составных шагов выполнения

Действия составных шагов выполнения предполагают, что инструкция runs принимает следующие три аргумента:

  • using: необходимо задать для "composite" запуска составного шага выполнения.
  • steps: выполните шаги для выполнения действия.
  • steps[*].run: команда, которую вы хотите выполнить (может быть встроенным или скриптом в репозитории действий)

Например, вот runs инструкция для действия составных шагов выполнения, которые будут запускать скрипт в filepath /test/script/sh:

runs:
  using: "composite"
  steps:
    - run: ${{ github.action_path }}/test/script.sh
      shell: bash

Фирменная символика

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

branding:
  icon: 'shield'  
  color: 'blue'

Ниже приведен пример индикатора действия выхода на сайте GitHub Marketplace:

Снимок экрана, показывающий символику действия в GitHub Marketplace.

Команды рабочего процесса

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

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

Большинство команд рабочего процесса используют echo команду в следующем формате, а другие могут вызываться путем записи в файл:

echo "::workflow-command parameter1={data},parameter2={data}::{command value}"

Ниже приведены некоторые основные примеры ведения журнала сообщений для печати сообщения отладки, сообщения об ошибке или предупреждения в консоли:

- name: workflow commands logging messages
  run: |
    echo "::debug::This is a debug message"
    echo "This is an info message"
    echo "::error::This is an error message"
    echo "::warning::This is a warning message"

Кроме того, можно создать сообщение для ввода в журнал с именем файла (file), номером строки (line) и столбцом (col), в котором произошла ошибка. Предупреждающие сообщения отображаются в желтом выделении с текстом "предупреждение", а сообщения об ошибках отображаются в красном выделении с текстом "error".

echo "::error file=app.js,line=10,col=15::Something went wrong"

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

Например, следующий текст представляет собой многострочный текст:

This text spans
across multiple lines

Это сообщение должно быть закодировано, как показано здесь:

This text spans%0Aacross multiple lines

В дополнение к командам рабочего процесса можно задать коды выхода, чтобы задать состояние действия. Это важно, поскольку при работе с заданиями в рабочем процессе код выхода с ошибками остановит все параллельные действия и отменит все будущие действия. Если вы создаете действие JavaScript, вы можете использовать пакет средств @actions/core действий для регистрации сообщения и задания кода выхода из сбоя. Если вы создаете действие контейнера Docker, можно задать код выхода из сбоя в скрипте entrypoint.sh .