Введение
В этом руководстве показано, как получить рабочий процесс непрерывной интеграции (CI), который создает и тестирует код Node.js. Если тесты CI проходят правильно, может потребоваться развернуть код или опубликовать пакет.
Предварительные требования
Рекомендуется иметь базовое представление о Node.js, YAML, параметрах конфигурации рабочих процессов, а также о том, как создавать файл рабочего процесса. Дополнительные сведения можно найти в разделе
Использование начального рабочего процесса Node.js
GitHub предоставляет начальный рабочий процесс Node.js, который будет работать для большинства проектов Node.js. В этом руководстве приведены примеры npm и Yarn, которые можно использовать для настройки начального рабочего процесса. Дополнительные сведения см. в разделе Начальный рабочий процесс Node.js.
Чтобы быстро приступить к работе, добавьте начальный рабочий процесс в каталог .github/workflows
своего репозитория. В показанном ниже рабочем процессе предполагается, что ветвью по умолчанию для вашего репозитория является main
.
name: Node.js CI
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
node-version: [14.x, 16.x, 18.x, 20.x]
steps:
- uses: actions/checkout@v3
- name: Use Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v3
with:
node-version: ${{ matrix.node-version }}
- run: npm ci
- run: npm run build --if-present
- run: npm test
Выполнение заданий в другой операционной системе
Начальный рабочий процесс настраивает задания для запуска в Linux с помощью размещенных в GitHub средств выполнения ubuntu-latest
. Можно изменить ключ runs-on
для выполнения заданий в другой операционной системе. Например, можно использовать размещенные в GitHub средства выполнения Windows.
runs-on: windows-latest
Кроме этого, можно выполнять задания на размещенных в GitHub средствах выполнения macOS.
runs-on: macos-latest
Можно также выполнять задания в контейнерах Docker или предоставить локальное средство выполнения, которое выполняется в собственной инфраструктуре. Дополнительные сведения см. в разделе Синтаксис рабочего процесса для GitHub Actions.
Указание версии Node.js
Самый простой способ указать версию Node.js заключается в использовании действия setup-node
, предоставляемого GitHub. Дополнительные сведения см. описании setup-node
.
Действие setup-node
принимает версию Node.js в качестве входных данных и настраивает ее в средстве выполнения. Действие setup-node
находит определенную версию Node.js из кэша инструментов в каждом средстве запуска и добавляет необходимые двоичные файлы в переменную PATH
, которая сохраняется до конца задания. Применение действия setup-node
представляет собой рекомендуемый способ использования Node.js с GitHub Actions, так как он обеспечивает согласованное поведение в разных средствах выполнения и различных версиях Node.js. При использовании локального средства выполнения необходимо установить Node.js и добавить его в PATH
.
Начальный рабочий процесс включает матричную стратегию, которая создает и тестирует код с четырьмя версиями Node.js: 14.x, 16.x, 18.x и 20.x. Здесь "x" — это подстановочный знак, соответствующий последнему дополнительному выпуску и выпуску исправлений, доступному для версии. Каждая версия Node.js, указанная в массиве node-version
, создает задание, которое выполняет одни и те же действия.
Каждое задание может получить доступ к значению, определенному в массиве node-version
матрицы, с помощью контекста matrix
. Действие setup-node
использует контекст в качестве входных данных node-version
. Действие setup-node
настраивает каждое задание с использованием разных версий Node.js перед созданием и тестированием кода. Дополнительные сведения о матричных стратегиях и контекстах см. в разделах Синтаксис рабочего процесса для GitHub Actions и Контексты.
strategy:
matrix:
node-version: [14.x, 16.x, 18.x, 20.x]
steps:
- uses: actions/checkout@v3
- name: Use Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v3
with:
node-version: ${{ matrix.node-version }}
Кроме того, можно создавать и тестировать код с использованием конкретных версий Node.js.
strategy:
matrix:
node-version: [10.17.0, 17.9.0]
Либо можно создавать и тестировать код с помощью одной версии Node.js.
name: Node.js CI
on: [push]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Use Node.js
uses: actions/setup-node@v3
with:
node-version: '18.x'
- run: npm ci
- run: npm run build --if-present
- run: npm test
Если не указать версию Node.js, GitHub использует версию Node.js по умолчанию, заданную для среды. Дополнительные сведения см. в разделе О средствах выполнения, размещенных в GitHub.
Установка зависимостей
Для размещенных в GitHub средств выполнения установлены диспетчеры зависимостей npm и Yarn. Вы можете использовать npm и Yarn для установки зависимостей в рабочем процессе перед созданием и тестированием кода. В Windows и Linux для размещенных в GitHub средств выполнения также установлены Grunt, Gulp и Bower.
Можно также кэшировать зависимости, чтобы ускорить рабочий процесс. Дополнительные сведения см. в разделе Кэширование зависимостей для ускорения рабочих процессов.
Пример использования npm
В этом примере устанавливаются зависимости, определенные в файле package.json. Дополнительные сведения см. на веб-сайте npm install
.
steps:
- uses: actions/checkout@v3
- name: Use Node.js
uses: actions/setup-node@v3
with:
node-version: '18.x'
- name: Install dependencies
run: npm install
При использовании npm ci
версии устанавливаются в файл package-lock.json или npm-shrinkwrap.json, а также запрещается изменение файла блокировки. Выполнение npm ci
обычно осуществляется быстрее, чем npm install
. Дополнительные сведения см. в описании npm ci
и разделе Знакомство с npm ci
для получения более быстродействующих и надежных сборок.
steps:
- uses: actions/checkout@v3
- name: Use Node.js
uses: actions/setup-node@v3
with:
node-version: '18.x'
- name: Install dependencies
run: npm ci
Пример использования Yarn
В этом примере устанавливаются зависимости, определенные в файле package.json. Дополнительные сведения см. на веб-сайте yarn install
.
steps:
- uses: actions/checkout@v3
- name: Use Node.js
uses: actions/setup-node@v3
with:
node-version: '18.x'
- name: Install dependencies
run: yarn
Кроме того, можно передать --frozen-lockfile
, чтобы установить версии в файле yarn.lock
и запретить изменения файла yarn.lock
.
steps:
- uses: actions/checkout@v3
- name: Use Node.js
uses: actions/setup-node@v3
with:
node-version: '18.x'
- name: Install dependencies
run: yarn --frozen-lockfile
Пример использования частного реестра и создания NPMRC-файла
Действие setup-node
можно использовать для создания локального NPMRC-файла в средстве выполнения, который настраивает реестр и область по умолчанию. Действие setup-node
также принимает в качестве входных данных маркер проверки подлинности, используемый для доступа к частным реестрам или публикации пакетов узлов. Дополнительные сведения см. на веб-сайте setup-node
.
Чтобы пройти проверку подлинности в частном реестре, нужно сохранить маркер проверки подлинности npm в виде секрета. Например, создайте секрет репозитория NPM_TOKEN
. Дополнительные сведения см. в разделе Зашифрованные секреты.
В приведенном ниже примере в NPM_TOKEN
секрета хранится токен проверки подлинности npm. Действие setup-node
настраивает файл NPMRC для чтения маркера проверки подлинности npm из переменной среды NODE_AUTH_TOKEN
. При использовании действия setup-node
для создания файла NPMRC необходимо задать для переменной среды NODE_AUTH_TOKEN
секрет, содержащий маркер проверки подлинности npm.
Перед установкой зависимостей используйте действие setup-node
для создания файла NPMRC. Это действие имеет два входных параметра. Параметр node-version
задает версию Node.js, а параметр registry-url
задает реестр по умолчанию. Если в реестре пакетов используются области, необходимо использовать параметр scope
. Дополнительные сведения см. на веб-сайте npm-scope
.
steps:
- uses: actions/checkout@v3
- name: Use Node.js
uses: actions/setup-node@v3
with:
always-auth: true
node-version: '18.x'
registry-url: https://registry.npmjs.org
scope: '@octocat'
- name: Install dependencies
run: npm ci
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
В приведенном выше примере создается файл NPMRC со следующим содержимым:
//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}
@octocat:registry=https://registry.npmjs.org/
always-auth=true
Примеры кэширования зависимостей
Можно кэшировать и восстанавливать зависимости с помощью setup-node
действия.
В следующем примере кэшируются зависимости для npm.
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: '14'
cache: 'npm'
- run: npm install
- run: npm test
В следующем примере кэшируются зависимости для Yarn.
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: '14'
cache: 'yarn'
- run: yarn
- run: yarn test
В следующем примере кэшируются зависимости для pnpm (версия 6.10 или более поздняя).
# Этот рабочий процесс использует действия, которые не сертифицированы GitHub.
# Они предоставляются сторонним поставщиком, и на них распространяются
# отдельные условия обслуживания, политика конфиденциальности и поддержка
# документации.
# NOTE: pnpm caching support requires pnpm version >= 6.10.0
steps:
- uses: actions/checkout@v3
- uses: pnpm/action-setup@0609f0983b7a228f052f81ef4c3d6510cae254ad
with:
version: 6.10.0
- uses: actions/setup-node@v3
with:
node-version: '14'
cache: 'pnpm'
- run: pnpm install
- run: pnpm test
Если у вас есть особые требования или вам нужно управлять кэшированием более детально, можно использовать действие cache
. Дополнительные сведения см. в разделе Кэширование зависимостей для ускорения рабочих процессов.
Создание и тестирование кода
Вы можете использовать те же команды, которые используются для создания и тестирования кода в локальной среде. Например, при запуске npm run build
для выполнения шагов сборки, определенных в файле package.json, и npm test
для выполнения набора тестов, вам нужно добавить эти команды в свой файл рабочего процесса.
steps:
- uses: actions/checkout@v3
- name: Use Node.js
uses: actions/setup-node@v3
with:
node-version: '18.x'
- run: npm install
- run: npm run build --if-present
- run: npm test
Упаковка данных рабочего процесса в виде артефактов
Вы можете сохранить артефакты из шагов сборки и тестирования, чтобы просмотреть их после завершения задания. Например, может потребоваться сохранить файлы журналов, основные дампы, результаты теста или снимки экрана. Дополнительные сведения см. в разделе Хранение данных рабочего процесса в виде артефактов.
Публикация в реестрах пакетов
Вы можете настроить рабочий процесс для публикации пакета Node.js в реестре пакетов после прохождения тестов CI. Дополнительные сведения о публикации в npm и GitHub Packages см. в разделе Публикация пакетов Node.js.