Выпуск¶
Выпускі ініцыююцца апублікаваным на GitHub рэлізам, тэгам якога з'яўляецца значэнне semver з прэфіксам v, напрыклад v1.2.7.
Адзіны Release працоўны працэс развязвае тэг адзін раз, а затым перадае вытворны version, version_tag, і тэгі вобраза, бяспечныя для Docker, праз npm-пакаванне, аргументы Docker build, тэгі вобраза, метаданыя сервера, маркіроўкі 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 Trusted Publishing патрабуе npm CLI >=11.5.1 і Node.js >=22.14.0.
Выкарыстанне ў выданні:
Пры публікацыі праз Trusted Publishing npm аўтаматычна стварае паходжанне пакета для публічных пакетаў з публічных рэпазіторыяў. Не дадавайце доўгатэрміновы токен публікацыі npm назад у гэты працоўны працэс.
Версія пакета прымяняецца з тэгі выпуску GitHub перад npm pack і npm publish, і задача правальваецца, калі package.json не супадае з вызначанай версіяй рэлізу.
Публікацыя ў Docker¶
Добра, што вы ўсё разумееце.
Задача docker выкарыстоўвае рэпазіторый GITHUB_TOKEN з packages: write для GHCR. Для публікацыі ў Docker Hub патрабуюцца DOCKERHUB_USERNAME і DOCKERHUB_TOKEN у docker-production асяроддзі або сакрэтах рэпазіторыя.
Працоўны працэс абнаўляе агляд рэпазіторыя Docker Hub пасля паспяховага загрузкі (push) вобраза. Docker Hub не атрымлівае каранёвы README.md аўтаматычна для гэтага працоўнага працэсу выпуску GitHub Actions; Агляд, спецыфічны для Docker Hub, падтрымліваецца ў docs/dockerhub-readme.md.
Перад зліццём release PR CI правярае:
- запускае праверкі TypeScript, lint, format, build, test і coverage;
- правярае метаданыя і змесціва npm-пакета;
- збірае Docker-вобразы для
linux/amd64іlinux/arm64; - запускае smoke-праверкі Docker
--help; - параўноўвае вобраз
linux/amd64з upstream Playwright MCP з дапамогай скрыпта праверкі парытэту моста; - скануе Docker-вобразы з дапамогай Trivy на наяўнасць сур'ёзных і крытычных уразлівасцей АС/бібліятэк.
Падчас публікацыі рэлізу Docker workflow:
- прымяняе версію рэлізу;
- падчас зборкі Docker прымяняе даступныя бяспекавыя абнаўленні Debian на базе замацаванага базавага вобраза Playwright MCP;
- выдаляе невыкарыстаны глабальны npm-пайлоуд з runtime-вобраза;
- публікуе шматплатформавы вобраз;
- абнаўляе агляд Docker Hub пасля паспяховага push вобраза.
Зборка Docker атрымлівае RELEASE_VERSION, RELEASE_VERSION_TAG, і VCS_REF аргументы зборкі. Рабочы працэс таксама вызначае хэш базавага вобраза MCP ад upstream Playwright і перадае яго як 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 у афіцыйны рэестр па адрасе:
Публікацыя на сервер выкарыстоўвае лакальны MCP Registry Publish кампазітны GitHub Action, афіцыйны mcp-publisher CLI і GitHub Actions OIDC. Не адкрывайце pull-запыт на modelcontextprotocol/registry для пералічэння гэтага сервера; той рэпазіторый адкрыта патрабуе ад аўтараў пакетаў публікаваць з дапамогай mcp-publisher.
Працоўны працэс не патрабуе Glama, выстаўлення рахункаў, GitHub PAT, 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 пачынаецца з той жа падзеі выпуску ў GitHub, што і 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
Рэестр https://github.com/mcp GitHub — гэта асобная ўпарадкаваная прастора для пошуку. Публікацыя ў афіцыйным рэестры MCP з'яўляецца абавязковай, але гэта не гарантуе неадкладнай бачнасці на старонцы /mcp GitHub. Разглядайце npm run registry:check як інструмент праверкі рэлізу для афіцыйнага рэестра, npm, GHCR, Docker Hub і як сродак для максімальна магчымай праверкі бачнасці на GitHub MCP. Выкарыстоўвайце npm run registry:check:strict толькі пасля таго, як бачнасць у GitHub MCP павінна стаць абавязковым крокам.
Кантрольны спіс для каталога Глама¶
Ацэнка каталога Glama асобная ад рэлізаў на GitHub і афіцыйнага публікавання ў рэестры MCP. Рэпазіторый уключае 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; - націсніце «Разгортванне» (Deploy) і пачакайце, пакуль тэст зборкі пройдзе паспяхова;
- стварыць і выпусціць рэліз 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.
Публікацыя дакументацыі таксама запускае SEO-валідатар пасля зборкі MkDocs. Факультатыўныя токены праверкі вэб-майстроў выкарыстоўваюць афіцыйныя бясплатныя інструменты для вэб-майстроў і могуць быць прадастаўлены ў выглядзе зменных рэпазіторыя або сакрэтаў:
GOOGLE_SITE_VERIFICATIONBING_SITE_VERIFICATIONYANDEX_SITE_VERIFICATIONBAIDU_SITE_VERIFICATIONNAVER_SITE_VERIFICATION
Апцыянальныя апавяшчэнні IndexNow патрабуюць сакрэт рэпазіторыя з назвай INDEXNOW_KEY. Калі ён усталяваны, рабочы працэс публікуе неабходны ключавы файл і падае згенераваныя URL-адрасы sitemap пасля разгортвання GitHub Pages.
Не дадавайце платныя паслугі індэксацыі, рэкламныя прадукты або статыстыку трэціх бакоў у працэс выпуску дакументацыі без асобнага выразнага рашэння.
Узрэзавы маніторынг¶
Пакет працоўных працэсаў моніторынгу верхняга стрыму запускаецца штодня, а таксама можа быць запушчаны ўручную з дапамогай GitHub Actions. Ён правярае абодва дыстрыбутыўныя каналы Playwright MCP з верхняга стрыму:
- npm-пакет:
@playwright/mcp; - Docker-абраз:
mcr.microsoft.com/playwright/mcp.
Калі выяўляецца больш новая версія ў вышэйстаячым рэпазіторыі, працоўны працэс стварае іссу на GitHub, прызначаны для swimmwatch. Іссу ўключае бягучую і апошнюю версіі npm/Docker версіі, кароткі агляд release-notes ад microsoft/playwright-mcp і спасылкі на поўны changelog зыходнай распрацоўкі, npm-пакет і Docker-тэгы.
Правядзіце тую ж праверку лакальна з дапамогай:
Тэгі рэлізу¶
| Тып выпуску | Налада 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. - Пазначце рэліз як prerelease пры публікацыі версіі
nextnpm. - Пераканайцеся, што npm Trusted Publisher наладжаны для
release.ymlіnpm-production. - Пацвердзіце
npm-production,docker-production,github-pages, іmcp-registry-productionасяроддзі існуюць. - Пераканайцеся, што сканаванне кода GitHub уключана, калі неабходная бачнасць загрузкі SARIF.
- Пераканайцеся, што бачнасць пакета GHCR з'яўляецца публічнай пасля першай публікацыі Docker.
- Пераканайцеся, што сервер Glama быў сінхранізаваны, пратэставаны праз адміністрацыйную старонку Dockerfile і выпушчаны з той жа стабільнай версіяй.
SUPPORT.md наўмысна адкладаецца, пакуль праект не атрымае стабільную палітыку падтрымкі па-за межамі GitHub-іссій і паведамленняў аб бяспецы.