JavaScript-экшены: рантайм node20, toolkit и бандл ncc

Рантайм node20 и toolkit

Если ты когда-нибудь писал воркфлоу GitHub Actions и замечал, что одни экшены читают структурированные inputs, маскируют секреты и делают API-вызовы, а другие похожи на просто скрипты в CI — разница в toolkit. Вот контракт между твоим кодом и раннером.

JavaScript-экшен объявляет runs.using: "node20" и main:, указывающий на входной файл. В момент вызова GitHub Actions спавнит процесс Node.js 20 (поддерживаемый LTS-рантайм; старые node16/node12 устарели) и выполняет этот файл на раннере — без контейнера, так что он работает на Linux, macOS и Windows одинаково и стартует менее чем за секунду против pull образа Docker-экшена. Контракт между вашим кодом и раннером — это @actions/toolkit — набор npm-пакетов, которые вы вызываете вместо ковыряния в магических переменных окружения:

import * as core from "@actions/core";
import * as github from "@actions/github";

async function run() {
  const token = core.getInput("github-token", { required: true });
  core.setSecret(token);                 // mask it in logs
  const label = core.getInput("label");

  const octokit = github.getOctokit(token);
  const { owner, repo } = github.context.repo;
  const pr = github.context.payload.pull_request;

  await octokit.rest.issues.addLabels({
    owner, repo, issue_number: pr.number, labels: [label],
  });

  core.setOutput("labeled", "true");     // available to later steps
}

run().catch((err) => core.setFailed(err.message));

core.getInput читает inputs из action.yml (они приходят как env-переменные INPUT_*, но напрямую их никогда не читайте); core.setOutput и core.setFailed — верный способ отдать outputs и упасть — setFailed ставит код выхода, так что шаг краснеет. github.context отдаёт распарсенный payload события, а github.getOctokit — заранее аутентифицированный клиент API. Дотягиваться мимо toolkit к парсингу process.env.GITHUB_EVENT_PATH вручную — классический джуниорский запах.

Почему собирают: проблема ncc

Раннер не делает npm install для экшена — он выполняет ваш файл main: как есть. Так что дерево зависимостей должно присутствовать в репозитории. Закоммитить сырой node_modules работает, но уродливо: сотни папок, тысячи файлов, шумный diff на каждом бампе зависимости и реальная supply-chain-поверхность для ревью. Стандартный ответ — @vercel/ncc: он компилирует ваш входной файл и всё его node_modules в единый dist/index.js, попутно tree-shaking неиспользуемый код. Вы указываете main: в action.yml на dist/index.js, коммитите этот один файл и кладёте node_modules в .gitignore. Экшен на toolkit, тянущий @actions/core плюс @actions/github (несущий Octokit), собирается в несколько сотен килобайт до единиц мегабайт — один файл, детерминированный, ревьюимый как diff.

Когда ты отгружаешь изменение логики экшена, задай себе вопрос: пересобран ли dist/? Этот вопрос должен стать рефлексом — вот почему его пропуск молча отгружает старый код каждому потребителю.

Дисциплина, которую это навязывает, реальна и частый источник багов: закоммиченный бандл может разойтись с исходником. Если вы правите index.js, гоняете тесты и забываете ncc build, CI продолжает гонять старый dist/index.js, и ваше изменение молча ничего не делает. Команды стерегут это CI-проверкой, что запускает ncc build и падает, если git diff --exit-code dist/ грязный — доказывая, что закоммиченный бандл совпадает с исходником. Ещё две старшие заметки: пиньте рантайм на node20 (не оставляйте устаревшую версию, которую GitHub отключит), и для supply-chain-безопасности потребители должны пинить ваш экшен по полному commit SHA, а не тегу — uses: org/labeler@<40-символьный-sha> — ведь тег вроде @v1 изменяем, и скомпрометированный релиз мог бы отгрузить зловредный код внутри этого собранного dist/index.js всем, кто отслеживает тег.