Публикация пакетов Node.js

Введение

В этом руководстве показано, как создать рабочий процесс, публикующий пакеты Node.js в GitHub Packages и реестры npm после прохождения тестов непрерывной интеграции (CI).

Необходимые компоненты

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

Дополнительные сведения о создании рабочего процесса CI для проекта Node.js см. в разделе Создание и тестирование для Node.js.

Также могут быть полезны базовые знания в следующих областях:

•         [AUTOTITLE](/packages/working-with-a-github-packages-registry/working-with-the-npm-registry)
  

•         [AUTOTITLE](/actions/learn-github-actions/variables)
  

•         [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions)
  

•         [AUTOTITLE](/actions/security-guides/automatic-token-authentication)
  

Сведения о конфигурации пакета

          `name` Поля `version` в `package.json` файле создают уникальный идентификатор, который реестры используют для связывания пакета с реестром. Вы можете добавить сводку для страницы описания пакетов, включив `description` поле в `package.json` файл. Дополнительные сведения см. в разделе ["Создание файла](https://docs.npmjs.com/creating-a-package-json-file) package.json" и ["Создание модулей](https://docs.npmjs.com/creating-node-js-modules) Node.js" в документации npm.

Если локальный .npmrc``registry файл существует и имеет указанное значение, команда использует реестр, npm publish настроенный в .npmrc файле. Действие можно использовать setup-node для создания локального .npmrc файла в средстве выполнения, который настраивает реестр и область по умолчанию. Действие setup-node также принимает в качестве входных данных маркер проверки подлинности, используемый для доступа к частным реестрам или публикации пакетов узлов. Дополнительные сведения см. в разделе setup-node.

Указать версию Node.js, установленную в средстве выполнения тестов, можно с помощью действия setup-node.

Если вы добавите шаги в рабочий процесс для настройки publishConfig полей в package.json файле, вам не нужно указывать URL-адрес реестра с помощью setup-node действия, но вы будете ограничены публикацией пакета в одном реестре. Дополнительные сведения см . в статье publishConfig в документации по npm.

Публикация пакетов в реестре npm

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

Для выполнения аутентифицированных операций с реестром npm в рабочем процессе необходимо сохранить маркер проверки подлинности npm в виде секрета. Например, создайте секрет репозитория NPM_TOKEN. Дополнительные сведения см. в разделе Использование секретов в GitHub Actions.

По умолчанию npm использует name поле package.json файла для определения имени опубликованного пакета. При публикации в глобальном пространстве имен необходимо включить только имя пакета. Например, пакет с именем my-package вы бы опубликовали в https://www.npmjs.com/package/my-package.

Если вы публикуете пакет, содержащий префикс области, добавьте область в имя package.json файла. Например, если префикс области npm имеет значение "octocat", а имя пакета — hello-world, name в файле package.json должно быть @octocat/hello-worldуказано значение . Если пакет npm использует префикс области и пакет является общедоступным, необходимо использовать параметр npm publish --access public. Это параметр, который npm требует, чтобы запретить кому-либо непреднамеренно опубликовать частный пакет.

Если вы хотите опубликовать пакет с прованом, добавьте --provenance флаг с помощью npm publish команды. Это позволяет публично и проверяемо определить, где и как был создан пакет, что повышает безопасность цепочки поставок для людей, которые потребляют ваш пакет. Дополнительные сведения см. в разделе "Создание инструкций прованса" в документации npm.

В этом примере секрет NPM_TOKEN сохраняется в переменной среды NODE_AUTH_TOKEN. setup-node Когда действие создает .npmrc файл, он ссылается на маркер из переменной NODE_AUTH_TOKEN среды.

name: Publish Package to npmjs
on:
  release:
    types: [published]
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v5
      # Setup .npmrc file to publish to npm
      - uses: actions/setup-node@v4
        with:
          node-version: '20.x'
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm publish --provenance --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

name: Publish Package to npmjs
on:
  release:
    types: [published]
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v5
      # Setup .npmrc file to publish to npm
      - uses: actions/setup-node@v4
        with:
          node-version: '20.x'
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm publish --provenance --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

В приведенном выше setup-node примере действие создает .npmrc файл в средстве выполнения со следующим содержимым:

//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}
registry=https://registry.npmjs.org/
always-auth=true

Обратите внимание, что для правильной настройки учетных данных необходимо задать для registry-url значение https://registry.npmjs.org/ в setup-node.

Публикация пакетов в GitHub Packages

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

Настройка целевого репозитория

Связывать пакет с GitHub Packages с помощью ключа repository не обязательно. Если вы решили не указать repository ключ в package.json файле, то ваш пакет не будет связан с репозиторием при публикации, но вы можете подключить пакет к репозиторию позже.

Если в файле указан ключ, репозиторий repository в package.json этом разделе используется в качестве целевого реестра npm для GitHub Packages. Например, публикация приведенных ниже package.json результатов в пакете с именем my-package , опубликованном в octocat/my-other-repo репозитории GitHub.

{
  "name": "@octocat/my-package",
  "repository": {
    "type": "git",
    "url": "https://github.com/octocat/my-other-repo.git"
  },
}

Проверка подлинности в целевом репозитории

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

Если вы хотите опубликовать пакет в другом репозитории, необходимо использовать personal access token (classic) с разрешением на запись в пакеты в целевом репозитории. Дополнительные сведения см. в разделе [AUTOTITLE и Управление личными маркерами доступа](/actions/security-guides/using-secrets-in-github-actions).

Пример рабочего процесса

В этом примере секрет GITHUB_TOKEN сохраняется в переменной среды NODE_AUTH_TOKEN. setup-node Когда действие создает .npmrc файл, он ссылается на маркер из переменной NODE_AUTH_TOKEN среды.

name: Publish package to GitHub Packages
on:
  release:
    types: [published]
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v5
      # Setup .npmrc file to publish to GitHub Packages
      - uses: actions/setup-node@v4
        with:
          node-version: '20.x'
          registry-url: 'https://npm.pkg.github.com'
          # Defaults to the user or organization that owns the workflow file
          scope: '@octocat'
      - run: npm ci
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

name: Publish package to GitHub Packages
on:
  release:
    types: [published]
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v5
      # Setup .npmrc file to publish to GitHub Packages
      - uses: actions/setup-node@v4
        with:
          node-version: '20.x'
          registry-url: 'https://npm.pkg.github.com'
          # Defaults to the user or organization that owns the workflow file
          scope: '@octocat'
      - run: npm ci
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Действие setup-node создает .npmrc файл в средстве выполнения. При использовании входных scope данных для setup-node действия .npmrc файл включает префикс области. По умолчанию setup-node действие задает область в .npmrc файле учетной записи, содержащей этот файл рабочего процесса.

//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
@octocat:registry=https://npm.pkg.github.com
always-auth=true

Публикация пакетов с помощью Yarn

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

name: Publish Package to npmjs
on:
  release:
    types: [published]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      # Setup .npmrc file to publish to npm
      - uses: actions/setup-node@v4
        with:
          node-version: '20.x'
          registry-url: 'https://registry.npmjs.org'
          # Defaults to the user or organization that owns the workflow file
          scope: '@octocat'
      - run: yarn
      - run: yarn npm publish // for Yarn version 1, use `yarn publish` instead
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

name: Publish Package to npmjs
on:
  release:
    types: [published]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      # Setup .npmrc file to publish to npm
      - uses: actions/setup-node@v4
        with:
          node-version: '20.x'
          registry-url: 'https://registry.npmjs.org'
          # Defaults to the user or organization that owns the workflow file
          scope: '@octocat'
      - run: yarn
      - run: yarn npm publish // for Yarn version 1, use `yarn publish` instead
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Чтобы пройти проверку подлинности в реестре во время публикации, убедитесь, что маркер проверки подлинности также определен в yarnrc.yml файле. Дополнительные сведения см . в статье "Параметры " в документации Yarn.