Перейти к содержанию

Релиз

Релизы создаются на основе опубликованного релиза на GitHub, тег которого представляет собой значение semver с префиксом v, например v1.2.7.

Единый рабочий процесс Release разрешает тег один раз, а затем передаёт производные теги version, version_tag и тег образа, безопасный для Docker, через упаковку npm, аргументы сборки Docker, метки образов, метаданные сервера, маркеры README и маркеры документации .

Все тестовые наборы приложения, покрытие, установка пакета и проверка подписей зависимостей выполняются до мержа и контролируются required-ci. Workflow Release собирает и публикует проверенную версию кода через package:pack и docs:build:site, проверяя метаданные выпуска и состав артефактов.

Настройки репозитория GitHub

Настройте эти параметры перед первым выпуском.

Область Необходимая настройка
Actions Включите GitHub Actions для репозитория.
Токен Actions Разрешите рабочим процессам запрашивать права, объявленные в каждом процессе.
Защита ветки Требуйте прохождения Actionlint, CI, CodeQL и Dependency Review перед слиянием в main.
Pages Установите Build and deployment -> Source в GitHub Actions.
Packages Разрешите GitHub Actions публиковать пакеты в GitHub Packages.
Окружения Создайте npm-production, docker-production, github-pages и mcp-registry-production.
Сканирование кода Включите сканирование кода для просмотра результатов CodeQL, Scorecard и Trivy в формате SARIF.

Добавьте необходимых рецензентов в npm-production, docker-production и mcp-registry-production, если для релизов требуется ручное утверждение после публикации релиза на GitHub. Среда github-pages используется встроенной задачей развертывания GitHub Pages.

Публикация в npm

Рабочий процесс выпуска npm осуществляет публикацию через npm Trusted Publishing с использованием GitHub Actions OIDC. Для публикации не используется NPM_TOKEN.

Настройте доверенного издателя на сайте npmjs.com, указав именно следующие значения:

Поле npm Trusted Publisher Значение
Провайдер GitHub Actions
Репозиторий swimmwatch/cloakbrowser-mcp
Имя файла рабочего процесса release.yml
Окружение npm-production
Разрешённое действие npm publish

Задание npm выполняется на раннерах, размещённых на GitHub, использует Node.js 24 и сохраняет id-token: write, чтобы npm мог обменять токен OIDC GitHub Actions на краткосрочные учетные данные для публикации. Для доверенной публикации npm требуется npm CLI >=11.5.1 и Node.js >=22.14.0.

Использование в издательском деле:

npm publish <tarball> --access public --tag <latest|next>

При публикации через Trusted Publishing npm автоматически генерирует информацию о происхождении пакетов для общедоступных пакетов из общедоступных репозиториев. Не следует добавлять в этот рабочий процесс долгосрочный токен публикации npm.

Версия пакета взята из тега релиза GitHub, предшествующего npm pack и npm publish, и задание завершается с ошибкой, если package.json не соответствует определённой версии выпуска.

Публикация в Docker

Образы Docker публикуются по адресу:

ghcr.io/swimmwatch/cloakbrowser-mcp
docker.io/swimmwatch/cloakbrowser-mcp

Задание docker использует репозиторий GITHUB_TOKEN с packages: write для GHCR. Для публикации на Docker Hub требуется DOCKERHUB_USERNAME и DOCKERHUB_TOKEN в секретах среды docker-production или репозитория.

Этот рабочий процесс обновляет обзор репозитория на Docker Hub после успешной загрузки образа. Docker Hub не загружает корневой репозиторий README.md автоматически для данного цикла выпуска GitHub Actions; обзор, специфичный для Docker Hub, содержится в docs/dockerhub-readme.md.

Перед слиянием release PR CI проверяет:

  • запускает проверки TypeScript, lint, форматирования, сборки, тестов и покрытия;
  • проверяет метаданные и содержимое npm-пакета;
  • собирает Docker-образы для linux/amd64 и linux/arm64;
  • запускает smoke-проверки Docker --help;
  • сравнивает образ linux/amd64 с upstream Playwright MCP с помощью скрипта проверки паритета моста;
  • сканирует Docker-образы с помощью Trivy на наличие уязвимостей ОС и библиотек высокого и критического уровня.

Во время публикации релиза Docker workflow:

  • применяет версию релиза;
  • устанавливает доступные обновления безопасности Debian поверх зафиксированного базового образа Playwright MCP во время сборки Docker;
  • удаляет неиспользуемые глобальные данные npm из образа среды выполнения;
  • публикует мультиплатформенный образ;
  • обновляет обзор Docker Hub после успешной отправки образа.

В процессе сборки Docker получает аргументы сборки RELEASE_VERSION, RELEASE_VERSION_TAG и VCS_REF. Рабочий процесс также вычисляет дайджест базового образа Playwright MCP из исходного репозитория и передаёт его как PLAYWRIGHT_MCP_IMAGE_DIGEST.

В окончательном образе хранятся те же значения, что и в метках OCI и метаданных среды выполнения (переменных среды). Опубликованные образы содержат метки для названия, описания, источника, документации, версии, ревизии, лицензии, авторов, поставщика, названия базового образа, хеша базового образа и имени сервера MCP.

Trivy — это бесплатное программное обеспечение с открытым исходным кодом, которое не требует внешнего токена для публичного сканирования образов. Результаты SARIF загружаются в систему сканирования кода GitHub, если сканирование кода включено.

После первой публикации убедитесь, что пакет GHCR является общедоступным и связан с этим репозиторием, а также убедитесь, что репозиторий на Docker Hub является общедоступным.

Docker публикует кроссплатформенный манифест для linux/amd64 и linux/arm64. PR CI выполняет smoke-проверки обеих платформ перед слиянием и сохраняет сравнение паритета браузерных инструментов для linux/amd64.

Публикация реестра MCP

Задание mcp-registry публикует server.json в официальный реестр по адресу:

https://registry.modelcontextprotocol.io

При публикации с сервера используется локальный составной GitHub Action MCP Registry Publish, официальный mcp-publisher CLI и OIDC GitHub Actions. Не создавайте пул- запрос к modelcontextprotocol/registry для добавления этого сервера в список; этот репозиторий явно требует, чтобы авторы пакетов публиковали их с использованием mcp-publisher.

Для работы этого рабочего процесса не требуются Glama, система биллинга, PAT-ключ GitHub, учетные данные DNS или долгосрочные секретные ключи реестра. В нём используются:

  • id-token: write для аутентификации по стандарту OIDC на GitHub;
  • mcp-publisher login github-oidc;
  • существующее пространство имён GitHub io.github.swimmwatch/cloakbrowser-mcp;
  • значение пакета npm mcpName для подтверждения права собственности на пакет npm;
  • метка образа Docker io.modelcontextprotocol.server.name для подтверждения права собственности на образ OCI .

Задание MCP Registry запускается в момент того же события GitHub Release, что и npm, Docker, а также публикация документации. Оно объявляет needs: [npm, docker], поэтому публикация в npm и Docker завершается до начала публикации в реестре. Развертывание документации объявляет needs: [docs-build, npm, docker, mcp-registry], поэтому GitHub Pages обновляется только после успешной публикации npm, Docker и официального MCP Registry. Это составное действие намеренно ориентировано на реестр: оно проверяет server.json локально, проверяет его с помощью mcp-publisher, проверяет, видна ли уже точно такая же версия в реестре, проводит аутентификацию с помощью mcp-publisher login github-oidc, публикует метаданные сервера и проверяет окончательную запись в реестре.

В случае временного сбоя реестра запустите заново задание mcp-registry, вызвавшее сбой, в первоначальном цикле выпуска после того, как задания npm и Docker будут отмечены зеленым цветом. Ручной триггер workflow_dispatch на Release предназначен для полных запусков конвейера релиза с явно указанным тегом.

Проверьте опубликованную запись реестра с помощью:

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.swimmwatch/cloakbrowser-mcp"
npm run registry:check

Реестр GitHub https://github.com/mcp представляет собой отдельную, тщательно отборную платформу для поиска проектов. Публикация в официальном реестре MCP является обязательной, но не гарантирует немедленной видимости на странице GitHub /mcp. Рассматривайте команду npm run registry:check как инструмент проверки выпуска для официального реестра, npm, GHCR, Docker Hub, а также как средство проверки видимости в GitHub MCP с максимальной эффективностью. Используйте npm run registry:check:strict только после того, как видимость в GitHub MCP станет обязательным условием.

Контрольный список каталога Glama

Оценка в каталоге Glama не связана с релизами на GitHub и официальной публикацией в MCP Registry. Репозиторий содержит glama.json, поэтому учетная запись администратора swimmwatch может заявить о своих правах или подтвердить владение в Glama.

Перед выпуском стабильной версии заполните бесплатный чек-лист Glama:

  • синхронизировать сервер через интерфейс администрирования сервера Glama MCP после того, как glama.json будет объединен с main;
  • открыть https://glama.ai/mcp/servers/swimmwatch/cloakbrowser-mcp/admin/dockerfile;
  • настроить Glama для сборки Dockerfile этого репозитория и запуска существующей точки входа stdio без дополнительных секретов;
  • сохранить совместимость среды выполнения с настройками по умолчанию CloakBrowser: cloak браузерный , режим без интерфейса, вывод в stdout и хранилище артефактов /data;
  • нажмите «Развернуть» и дождитесь успешного завершения теста сборки;
  • создайте и опубликуйте релиз Glama с той же версией, что и релиз на GitHub, например, 1.2.7;
  • после выпуска один раз воспользуйтесь функцией Glama «Попробовать в браузере», чтобы стимулировать начальное использование;
  • вручную добавьте соответствующие серверы, как минимум официальный сервер Playwright MCP, а также, по желанию, близкие альтернативы для автоматизации браузеров.

Не добавляйте способ оплаты или платный хостинг Glama только для того, чтобы повысить рейтинг каталога. Если Glama требует оплаты за какой-либо обязательный пункт чек-листа, рассматривайте это как препятствие для выпуска, требующее явного решения со стороны сопровождающего.

Рабочие процессы в сфере безопасности

В репозитории используются бесплатные инструменты безопасности:

Рабочий процесс Инструмент Условие запуска Настройка пользователем
CodeQL GitHub CodeQL push, pull request, еженедельно, вручную Включите сканирование кода для просмотра результатов SARIF.
Dependency Review GitHub Dependency Review pull request Внешняя учётная запись или токен не требуются.
OpenSSF Scorecard OpenSSF Scorecard push, еженедельно, вручную Включите сканирование кода для просмотра результатов SARIF.
Zizmor zizmor изменения рабочих процессов, вручную Внешняя учётная запись или токен не требуются.
CI Trivy Сборка Docker в PR Включите сканирование кода для просмотра результатов SARIF.
CI npm audit --omit=dev --audit-level=high PR CI Внешняя учётная запись или токен не требуются.

Внешние GitHub Actions закреплены полными SHA коммитов с читаемыми комментариями версий. Сохраняйте эти закрепления при обновлении рабочих процессов.

Публикация документации

docs-build и docs-deploy развертывают MkDocs с помощью встроенного потока развертывания GitHub Pages Actions. В настройках Pages репозитория в качестве источника необходимо указать GitHub Actions.

Рабочий процесс формирует документацию в строгом режиме, загружает сгенерированный каталог site/ в каталог actions/upload-pages-artifact, а также развертывает его с помощью actions/deploy-pages в среду github-pages только после успешной публикации npm, Docker и MCP Registry.

При публикации документации после сборки MkDocs также запускается валидатор SEO. Дополнительные токены для подтверждения веб-мастера используют официальные бесплатные инструменты для веб-мастеров и могут указываться в виде переменных репозитория или секретных данных:

  • GOOGLE_SITE_VERIFICATION
  • BING_SITE_VERIFICATION
  • YANDEX_SITE_VERIFICATION
  • BAIDU_SITE_VERIFICATION
  • NAVER_SITE_VERIFICATION

Для включения уведомлений IndexNow требуется секретный ключ репозитория с именем INDEXNOW_KEY. Если он задан, рабочий процесс публикует необходимый файл ключа и отправляет сгенерированные URL-адреса карты сайта после развертывания на GitHub Pages.

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

Мониторинг вверх по течению

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

  • пакет npm: @playwright/mcp;
  • образ Docker: mcr.microsoft.com/playwright/mcp.

При обнаружении более новой версии из исходного репозитория рабочий процесс создает задачу на GitHub, назначенную пользователю swimmwatch. Задача содержит текущие и последние версии npm/Docker версии, краткое резюме примечаний к выпуску из microsoft/playwright-mcp, а также ссылки на полный журнал изменений исходного проекта, пакет npm и теги Docker.

Выполните ту же проверку локально с помощью команды:

npm run upstream:check

Теги выпуска

Тип релиза Настройка GitHub Release Тег npm dist-tag Теги Docker
Стабильный Не предварительный релиз latest vX.Y.Z, X.Y.Z, X.Y, latest
Предварительный релиз Предварительный релиз next vX.Y.Z-prerelease, X.Y.Z-prerelease

Контрольный список

Перед публикацией пресс-релиза:

  • Выполнять слияние только после того, как Actionlint и CI станут зелёными.
  • Создайте релиз на GitHub на основе тега, например v1.2.7.
  • При публикации версии npm next пометьте релиз как предварительный.
  • Убедитесь, что доверенный издатель npm настроен для release.yml и npm-production.
  • Убедитесь, что npm-production, docker-production, github-pages и mcp-registry-production.
  • Убедитесь, что сканирование кода на GitHub включено, если требуется открытый доступ к загруженным файлам SARIF.
  • Убедитесь, что пакет GHCR доступен публично после первой публикации в Docker.
  • Убедитесь, что сервер Glama синхронизирован, протестирован через страницу администрирования Dockerfile и выпущен с той же стабильной версией.

SUPPORT.md намеренно отложено до тех пор, пока для проекта не будет разработана стабильная политика поддержки, выходящая за рамки задач на GitHub и рекомендаций по безопасности.