Создание действия JavaScript

Введение

В этом руководстве вы узнаете об основных компонентах, необходимых для создания и использования упакованного действия JavaScript. Чтобы сосредоточиться в этом руководстве на компонентах, необходимых для упаковки действия, функциональные возможности кода действия будут минимальны. Действие записывает сообщение "Hello World" в журналах или "Hello [имя приветствуемого]" при указании пользовательского имени.

Для ускорения разработки в этом руководстве применяется модуль Node.js из набора средств GitHub Actions. Дополнительные сведения см. в репозитории actions/toolkit.

Завершив этот проект, вы узнаете, как создать собственное действие JavaScript и протестировать его в рабочем процессе.

Чтобы обеспечить совместимость действий JavaScript со всеми средствами выполнения, размещенными в GitHub (Ubuntu, Windows и macOS), упакованный код JavaScript должен быть чистым JavaScript без зависимостей от других двоичных файлов. Действия JavaScript запускаются непосредственно в средстве выполнения и используют двоичные файлы, которые уже существуют в образе средства выполнения тестов.

Предварительные требования

Перед началом работы необходимо скачать Node.js и создать общедоступный репозиторий GitHub.

1. Скачайте и установите Node.js 16.x, в том числе npm.

   https://nodejs.org/en/download/

2. Создайте новую общедоступный репозиторий в экземпляр GitHub Enterprise Server и назовите ее hello-world-javascript-action. Дополнительные сведения см. в разделе Создание репозитория.

3. Клонируйте репозиторий на ваш компьютер. Дополнительные сведения см. в разделе Клонирование репозитория.

4. В окне терминала измените каталоги на новый репозиторий.

   Shell

   cd hello-world-javascript-action

5. В окне терминала инициализируйте каталог с помощью npm, чтобы создать файл package.json.

   Shell

   npm init -y

Создание файла метаданных действия

Создайте в каталоге hello-world-javascript-action файл с именем action.yml, содержащий приведенный ниже код. Дополнительные сведения см. в разделе Синтаксис метаданных для GitHub Actions.

name: 'Hello World'
description: 'Greet someone and record the time'
inputs:
  who-to-greet:  # id of input
    description: 'Who to greet'
    required: true
    default: 'World'
outputs:
  time: # id of output
    description: 'The time we greeted you'
runs:
  using: 'node16'
  main: 'index.js'

В этом файле определяются входной атрибут who-to-greet и выходной атрибут time. В нем также указывается способ запуска этого действия JavaScript средством выполнения.

Добавление пакетов из набора средств actions

Набор средств actions — это коллекция пакетов Node.js, которые позволяют быстро и согласованно создавать действия JavaScript.

Пакет @actions/core из набора средств предоставляет интерфейс для команд рабочего процесса, входных и выходных переменных, состояний выхода и сообщений отладки.

Набор средств также предлагает пакет @actions/github, который возвращает прошедший проверку подлинности клиент REST Octokit и доступ к контекстам GitHub Actions.

Набор средств не ограничивается пакетами core и github. Дополнительные сведения см. в репозитории actions/toolkit.

В окне терминала установите пакеты core и github из набора средств actions.

npm install @actions/core
npm install @actions/github

Теперь должен отображаться каталог node_modules с только что установленными модулями и файлом package-lock.json, в котором содержатся зависимости установленных модулей и версия каждого установленного модуля.

Написание кода действия

Это действие использует набор средств для получения входной переменной who-to-greet, требуемой в файле метаданных действия, и записывает строку "Hello [имя приветствуемого]" в отладочном сообщении журнала. Затем скрипт получает текущее время и присваивает его выходной переменной, которую смогут использовать действия, выполняемые позже в рамках задания.

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

Добавьте файл с именем index.js, содержащий приведенный ниже код.

const core = require('@actions/core');
const github = require('@actions/github');

try {
  // `who-to-greet` input defined in action metadata file
  const nameToGreet = core.getInput('who-to-greet');
  console.log(`Hello ${nameToGreet}!`);
  const time = (new Date()).toTimeString();
  core.setOutput("time", time);
  // Get the JSON webhook payload for the event that triggered the workflow
  const payload = JSON.stringify(github.context.payload, undefined, 2)
  console.log(`The event payload: ${payload}`);
} catch (error) {
  core.setFailed(error.message);
}

Если в приведенном выше примере index.js возникает ошибка, core.setFailed(error.message); использует пакет @actions/core из набора средств actions для регистрации сообщения и задания кода выхода "сбой". Дополнительные сведения см. в разделе Настройка кодов выхода для действий.

Создание файла README

Чтобы сообщить людям, как применить свое действие, можно создать файл README. Файл README является наиболее полезным, если вы планируете поделиться своим действием публично, но также является отличным способом напомнить вам или вашей команде, как использовать действие.

В каталоге hello-world-javascript-action создайте файл README.md, указывающий следующие сведения:

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

# Hello world javascript action

This action prints "Hello World" or "Hello" + the name of a person to greet to the log.

## Inputs

### `who-to-greet`

**Required** The name of the person to greet. Default `"World"`.

## Outputs

### `time`

The time we greeted you.

## Example usage

```yaml
uses: actions/hello-world-javascript-action@e76147da8e5c81eaf017dede5645551d4b94427b
with:
  who-to-greet: 'Mona the Octocat'
```

Фиксация, применение тега и отправка действия в GitHub

Во время выполнения GitHub Enterprise Server скачивает каждый запуск действия в рамках рабочего процесса и выполняет его как полный пакет кода, прежде чем можно будет использовать команды рабочего процесса, такие как run, для взаимодействия с компьютером средства выполнения. Это означает, что необходимо включить все зависимости пакетов, необходимые для выполнения кода JavaScript. Вам потребуется вернуть пакеты core и github из набора средств в репозиторий действия.

В окне терминала зафиксируйте файлы action.yml, index.js, node_modules, package.json, package-lock.json и README.md. Если вы добавили файл .gitignore со списком node_modules, потребуется удалить эту строку, чтобы зафиксировать каталог node_modules.

Рекомендуется также добавлять тег версии для выпусков действия. Дополнительные сведения о настройке версий действия см. в разделе Сведения о настраиваемых действиях.

git add action.yml index.js node_modules/* package.json package-lock.json README.md
git commit -m "My first action is ready"
git tag -a -m "My first action release" v1.1
git push --follow-tags

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

1. Установите vercel/ncc, выполнив в окне терминала следующую команду:

   npm i -g @vercel/ncc

2. Скомпилируйте файл index.js.

   ncc build index.js --license licenses.txt

   Появится новый файл dist/index.js с кодом и скомпилированными модулями. Кроме того, появится вспомогательный файл dist/licenses.txt со всеми лицензиями на используемые модули node_modules.

3. Измените ключевое слово main в файле action.yml так, чтобы использовался новый файл dist/index.js:

   main: 'dist/index.js'

4. Если вы уже вернули каталог node_modules, удалите его.

   rm -rf node_modules/*

5. В окне терминала зафиксируйте изменения в файлах action.yml, dist/index.js и node_modules.

   Shell

   git add action.yml dist/index.js node_modules/*
   git commit -m "Use vercel/ncc"
   git tag -a -m "My first action release" v1.1
   git push --follow-tags

Тестирование действия в рабочем процессе

Теперь вы готовы протестировать действие в рабочем процессе.

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

Пример. Использование общедоступного действия

В этом примере показано, как можно запустить новое общедоступное действие из внешнего репозитория.

Скопируйте приведенный ниже код YAML в новый файл по пути .github/workflows/main.yml и измените строку uses: octocat/hello-world-javascript-action@v1.1, указав свое имя пользователя и имя созданного ранее общедоступного репозитория. Вы также можете заменить входное поле who-to-greet на свое имя.

on: [push]

jobs:
  hello_world_job:
    runs-on: ubuntu-latest
    name: A job to say hello
    steps:
      - name: Hello world action step
        id: hello
        uses: octocat/hello-world-javascript-action@v1.1
        with:
          who-to-greet: 'Mona the Octocat'
      # Use the output from the `hello` step
      - name: Get the output time
        run: echo "The time was ${{ steps.hello.outputs.time }}"

При активации этого рабочего процесса средство выполнения скачивает действие hello-world-javascript-action из общедоступного репозитория, а затем запускает его.

Пример использования частного действия

Скопируйте код рабочего процесса в файл .github/workflows/main.yml в репозитории действия. Вы также можете заменить входное поле who-to-greet на свое имя.

.github/workflows/main.yml

on: [push]

jobs:
  hello_world_job:
    runs-on: ubuntu-latest
    name: A job to say hello
    steps:
      # To use this repository's private action,
      # you must check out the repository
      - name: Checkout
        uses: actions/checkout@v3
      - name: Hello world action step
        uses: ./ # Uses an action in the root directory
        id: hello
        with:
          who-to-greet: 'Mona the Octocat'
      # Use the output from the `hello` step
      - name: Get the output time
        run: echo "The time was ${{ steps.hello.outputs.time }}"

В репозитории перейдите на вкладку Действия и выберите последний запуск рабочего процесса. В разделе Задания или в графе визуализации щелкните Задание для отображения приветствия.

Щелкните Шаг действия Hello world, и вы увидите "Hello Mona the Octocat" или имя, которое вы использовали для who-to-greet входных данных, напечатанных в журнале. Чтобы просмотреть метку времени, щелкните Получить время вывода.

Репозитории шаблонов для создания действий JavaScript

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

• javascript-action репозиторий шаблонов
• typescript-action репозиторий шаблонов