Pandore/homarr

Public Access

0 Fork 0

Files

T

ajnart 6740d78c01 docs: refresh v2 release readiness evidence

2026-09-06 12:31:37 +02:00

50 KiB

Raw Blame History

Homarr v2 GA release checklist

Last audited: 2026-09-06 12:30 CEST (Europe/Berlin)

This is the working go/no-go checklist for the full Homarr v2 release. Do not mark an item complete from an old preview, PR run, or verbal confirmation. Add the final SHA, run URL, screenshot, issue, or written risk acceptance next to every completed release gate.

Release path

release/v2
  -> reviewed integration branch based on current dev
  -> promotion PR into dev
  -> final candidate validation on dev
  -> weekly or manually-created dev -> main PR
  -> HUMAN merge for the v2 major release
  -> Semantic Release creates v2.0.0
  -> GitHub release + GHCR images + release archives
  -> docs, Workshop, Discord and support follow-through

The weekly workflow deliberately does not auto-merge major releases. The v2 dev -> main PR must be merged by a human after the final go/no-go approval.

How to use this checklist

[ ] means unverified or incomplete.
[x] in the audited snapshot means it was observed on the dated snapshot only. Repeat final-candidate gates after integrating into dev.
BLOCKER must be closed or have explicit written acceptance from the release owner before the production merge.
Put evidence directly below the item or link it from the sign-off record.
If the candidate SHA changes, invalidate build, migration, image, browser, security and deployment sign-offs.

Audited snapshot

These facts are time-sensitive and must be refreshed at the start of the release window.

origin/release/v2: 35155b18b97b6904f6b571c93de9102c3d79e4da
origin/dev: da32acb4f0ba9d8fa8e9667f56a54f85ca497865
origin/main: 331925c197ad9cbf0138dbbcee9d8952ef9298dc (v1.76.2)
release/v2 has 562 commits not in dev; dev has 54 commits not in release/v2.
The merge base is 2513e8454f240caa315b68dd6738b79838eeeecc from 2026-08-13.
The dev...release/v2 change spans 2,473 files, 243,111 insertions and 59,966 deletions.
A clean git merge-tree --write-tree origin/dev origin/release/v2 rehearsal reports 42 unique conflict paths.
The exact release/v2 SHA has successful Fast gate, Container and E2E, CodeQL, Workshop validation and amd64/arm64 preview publication checks.
The latest dev deployment workflow at da32acb4f0ba9d8fa8e9667f56a54f85ca497865 is successful. An earlier arm64 offline-install failure was superseded by this green run.
The Homarr preview manifest exists for amd64 and arm64: ghcr.io/homarr-labs/homarr-test:v2@sha256:9055880e1d04ee78f2ff171ad8ff5ccd0b225e67e0a7635f4158669c40a8d7a0.
The Workshop preview manifest exists for amd64 and arm64: ghcr.io/homarr-labs/workshop:v2@sha256:1578c7e68955395a533ea9a3afad1168331cb783bb98b0255c3ded5c0cd927f5.
PR #6760 merged the streamlined v2 documentation and passed its hosted checks.
GitHub currently reports zero open CodeQL alerts and zero open secret-scanning alerts.
All 65 open pull requests were inventoried: 36 target dev, 21 target release/v2, seven are internal stack layers and one targets main. Every one is classified below as review/merge, port, defer, superseded or cleanup.
Audit-created readiness PRs #6770 through #6788 are non-draft, have clean merge state and have no failing or pending hosted checks. None has a human approval yet, and this evidence must be repeated after each rebase/merge wave.
Repository Actions secret names include DISCORD_WEBHOOK and DISCORD_WEBHOOK_AUTOMATIC_RELEASE; values were not read. Their last name-level updates were 2024-02-03 and 2023-12-20, so delivery must still be tested.
The github-pages environment has a deployment branch policy. The existing prod environment has no protection rules or reviewers and is not referenced by the production release workflow.
The public v2 preview is reachable, redirects to the login page, accepts the advertised demo account and displays Version 2.0.0 on /manage/about.
A read-only Chromium smoke of the public preview loaded the populated dashboard without application console errors, completed an authenticated reload to network-idle in 3.2 seconds, opened the Date and time advanced view through its keyboard control, rendered three world clocks, and rendered populated Media Releases data. This does not replace final-candidate or real-provider testing.
GitHub Dependabot currently reports 168 open repository-wide alerts: 5 critical, 64 high, 82 medium and 17 low. These are based on the repository's default-branch dependency view and must be reconciled with the candidate-specific pnpm audit results.
No v2.0.0 tag or production GitHub release exists yet. The latest production release is v1.76.2.
The v2.0.0 milestone is still open but contains zero open issues and only one closed issue. It is not an adequate source of release truth.

Readiness fixes opened from this audit

These are fixes, not completed release gates. Merge them into release/v2, carry them through the reviewed release/v2 -> dev integration, and repeat the final-candidate checks before changing the related items to [x].

#6770 — restore weekly release no-op behavior and scheduled Discord notifications, repair GitHub App token inputs, extend the merge timeout, and remove the obsolete release dispatch to the archived documentation repository.
#6771 — make mock integrations opt-in and enforce the unsafe flag in server-side creation, onboarding and direct-page paths.
#6772 — generate valid integration documentation links and remove committed/generated null URLs.
#6773 — point contributor guidance at the monorepo docs and current v2 branch flow.
#6774 — add the canonical v1-to-v2 upgrade, migration, backup and rollback guide.
#6775 — patch the critical Auth.js fail-open and email normalization advisories; 131 focused auth/proxy tests and affected typechecks pass.
#6776 — patch the critical protobufjs path while staying on compatible 7.x; 24 Docker tests and affected typechecks pass.
#6777 — replace the SQLite database placeholder with a safe ignored local path, remove copy-pastable weak secrets and delete the obsolete source-install CRON_JOB_API_KEY instruction. It also makes SSO key/credential replacement explicit and removes obsolete BASE_URL / NEXTAUTH_URL entries. The production docs build and hosted Fast gate, amd64/arm64 preview builds, container/E2E tests and multi-platform preview publication all pass.
#6778 — port the focused database-restore re-login and error reporting fix from #6624 without unrelated branch drift.
#6779 — make MCP OAuth discovery, resource validation, authentication challenges and login redirects honor the public origin and supported MCP route aliases. Sixteen route tests, Next.js typecheck/build, docs build and production-server route smokes pass.
#6780 — enforce NO_EXTERNAL_CONNECTION before weather location search makes an outbound request and show the disabled state. Fifteen focused tests and affected typechecks pass.
#6781 — use Unraid's byte-based memory metrics and clamp inconsistent values instead of using layout metadata.
#6782 — report Docker container CPU as a 0–100 percent share of the whole machine while retaining one-shot/Podman fallback behavior. Twenty focused tests pass.
#6783 — sync the committed Helm page to live chart 8.28.2 / app v1.76.2. Regenerate it again from the v2 chart after that chart is published.
#6784 — give the Downloads name column a stable default width without changing user-resizable persisted state.
#6785 — support nested OIDC group/name claim paths while preserving v2's provider and verified-email linking safeguards. Twenty-three focused Auth tests pass.
#6786 — preserve reverse-proxy subpaths in Nextcloud CalDAV discovery. Five focused Nextcloud tests pass.
#6787 — use valid UniFi HTTPS default ports, preserve explicit ports and avoid hiding authentication failures. Six focused tests pass.
#6788 — patch every published, fixable high-severity production dependency path found by the audit with exact catalog versions and range-scoped overrides. All workspace typechecks, the production docs build and 18 focused backup/ZIP tests pass. Its hosted Fast gate, amd64/arm64 preview builds, container/E2E tests and multi-platform preview publication all pass.
A temporary combined audit of origin/release/v2 plus #6775, #6776 and #6788 reports 0 critical, 2 high, 20 moderate and 9 low production advisories. Both remaining high findings are Docusaurus build-time paths to image-size@2.0.2; the registry still reports 2.0.2 as latest while both advisories require >=2.0.3.
That exact temporary combined graph also passes all 38 Turbo typecheck tasks and the Docusaurus production build.
The five repository-wide critical Dependabot alerts were reconciled: three runtime Auth.js alerts are addressed by #6775, protobufjs is addressed by #6776, and the remaining handlebars alert is development-scoped and is not present in the candidate's production audit.

Recommended review and merge order

Merge #6769 early so the team works from this checklist; continue updating its evidence in the release tracking issue if the file itself is frozen.
Review the release-control and production-default fixes first: #6770, #6771, #6772, #6773, #6774 and #6777.
Merge the lockfile security chain in this order: #6775, rebase/re-audit #6776, then rebase/re-audit #6788. Do not resolve their shared lockfile conflicts by choosing one side wholesale.
Review the backup, public-origin, privacy, authentication and integration correctness fixes next: #6778, #6779, #6780, #6785, #6786 and #6787.
Review the isolated display/metric fixes next: #6781, #6782 and #6784.
Review #6783 against the chart actually available to GA users; regenerate it after the v2 chart is published.
Decide #6765 explicitly before freeze. It is not ready to merge on the current evidence.
After every merge wave, update the remaining PRs from the new release/v2 head and rerun affected checks. Their current green results are based on the same pre-integration release SHA and are not final-candidate evidence.

Current merge conflicts

.agents/skills/codebase-context/SKILL.md
.agents/skills/datatable-migration/SKILL.md
.agents/skills/documentation-sync/SKILL.md
.agents/skills/mcp-integration/SKILL.md
.mcp.json
AGENTS.md
apps/docs/docs/getting-started/installation/helm.md
apps/docs/docs/management/certificates/index.mdx
apps/docs/docs/widgets/app/index.mdx
apps/docs/docs/widgets/bookmarks/index.mdx
apps/docs/docs/widgets/smart-home-entity-state/index.mdx
apps/docs/docs/widgets/smart-home-execute-automation/index.mdx
apps/nextjs/src/app/api/mcp/[transport]/route.ts
apps/nextjs/src/components/board/items/widget-context-menu.tsx
apps/nextjs/src/components/board/sections/gridstack/use-gridstack.ts
e2e/onboarding.spec.ts
package.json
packages/api/src/router/widgets/smart-home.ts
packages/integrations/src/truenas/test/truenas-integration.spec.ts
packages/translation/src/lang/ca.json
packages/translation/src/lang/cs.json
packages/translation/src/lang/de-CH.json
packages/translation/src/lang/el.json
packages/translation/src/lang/en-gb.json
packages/translation/src/lang/es.json
packages/translation/src/lang/et.json
packages/translation/src/lang/fr.json
packages/translation/src/lang/hr.json
packages/translation/src/lang/hu.json
packages/translation/src/lang/lt.json
packages/translation/src/lang/lv.json
packages/translation/src/lang/no.json
packages/translation/src/lang/pt-br.json
packages/translation/src/lang/pt.json
packages/translation/src/lang/ro.json
packages/translation/src/lang/ru.json
packages/translation/src/lang/sl.json
packages/translation/src/lang/sv.json
packages/translation/src/lang/uk.json
packages/translation/src/lang/vi.json
packages/widgets/src/health-monitoring/component.tsx
packages/widgets/src/system-disks/component.tsx

Current hard blockers

BLOCKER — integrate histories: reconcile all 54 dev-only commits and resolve the 42 current merge conflicts without dropping either branch's behavior.
BLOCKER — production dependency audit: the baseline mise exec -- pnpm audit --prod --audit-level high reported 141 findings: 4 critical, 65 high, 62 moderate and 10 low. The isolated combined graph with #6775, #6776 and #6788 has 0 critical, 2 high, 20 moderate and 9 low. Merge the two critical fixes first, rebase #6788, repeat the audit on that exact lockfile, and explicitly accept or wait for a published image-size fix.
BLOCKER — direct authentication advisories: merge and review #6775, then revalidate every authentication provider on the combined candidate. The isolated PR removes the critical next-auth and @auth/core findings.
BLOCKER — weekly promotion automation: merge #6770 and prove its success, failure and no-release paths in controlled workflow runs. It turns the observed no-version-bump failure into a successful no-op.
BLOCKER — scheduled notifications: merge #6770 and prove scheduled start, success, major and failure notices in a non-public Discord channel.
BLOCKER — MCP public origin: merge #6779 and repeat discovery/login/401 challenges through the actual production reverse proxy and subpath before publishing MCP as GA-ready.
BLOCKER — documentation release: merge #6770, which removes the false handoff to the archived homarr-labs/documentation repository. Confirm the authoritative monorepo GitHub Pages workflow deploys apps/docs when the v2 docs reach dev, then verify the public site and Algolia recrawl.
BLOCKER — branch rules: the strong v2 release ruleset targets the legacy refs/heads/v2, not refs/heads/release/v2. The active release branch does not receive those required checks.
BLOCKER — production deployment guard: the release workflow publishes after a main push without a protected production environment, while main currently requires no status checks. Decide and test the exact human approval/check boundary before the release window.
BLOCKER — final upgrade rehearsal: perform backup, migration, restore and rollback rehearsals from real v1.76.2 installations for SQLite, MySQL and PostgreSQL.
BLOCKER — upgrade guide: review and merge #6774, then verify the canonical guide against all three real upgrade rehearsals and the final image/tag.
BLOCKER — beta feedback: reproduce or close every unresolved report in the public v2 beta issue.
BLOCKER — release scope: explicitly include or defer the open llama.cpp PR and every release-sensitive fix listed below before feature freeze.
BLOCKER — production defaults: review and merge #6771, then repeat the disabled/enabled API and UI smoke on the combined candidate.
BLOCKER — final immutable candidate: nominate one SHA, freeze it, and repeat all mandatory checks on that exact SHA after it is in dev.

1. Ownership and release control

Name the release owner: ________________.
Name the database/backup owner: ________________.
Name the infrastructure/GHCR owner: ________________.
Name the documentation owner: ________________.
Name the Workshop owner: ________________.
Name the Discord/support owner: ________________.
Agree on the feature-freeze time: ________________.
Agree on the production merge window: ________________.
Agree on rollback decision authority: ________________.
Create one release tracking issue and copy/link this checklist there if GitHub assignment is required.
Assign an owner and deadline to every accepted blocker.
Record explicit written acceptance for any unresolved non-blocking risk.
Confirm at least two humans will attend the final go/no-go and release window.

2. Integrate `release/v2` into `dev`

Freeze new features on release/v2.
Refresh origin/main, origin/dev, origin/release/v2, tags, PRs and rulesets.
Create a temporary integration branch from the current origin/dev.
Merge origin/release/v2 into that integration branch.
Resolve every conflict semantically; do not choose an entire side for translations, migrations, docs or APIs without reviewing both changes.
Re-run the merge rehearsal and confirm zero unresolved entries.
Review every dev-only commit and mark it as preserved, superseded or intentionally rejected.
Specifically preserve or reconcile current dev changes for:
- startup/internal service addresses
- MCP void results
- Home Assistant actions and smart-home refresh behavior
- TrueNAS dataset/pool calculations
- OMV disk-temperature matching
- Unraid CPU/link/board fixes
- custom PUID/PGID startup behavior
- Helm documentation
- contributor and bug-report automation
- all Crowdin translation updates
Confirm root package.json remains version 2.0.0.
Confirm the final promotion commit/PR contains a breaking Conventional Commit signal such as feat!: release Homarr v2.
Regenerate the lockfile only after dependency and conflict decisions are final.
Open the reviewed integration branch as the actual promotion PR into dev.
Require human review and resolve every thread.
Do not use PR #6545 as the production promotion PR; it targets an internal stacked branch.

3. Pull-request triage

Every open PR must be marked include, port only, defer, superseded, or close. New features should default to defer once the release is frozen.

Release-sensitive decisions

#6765 llama.cpp integration and widget — currently targets release/v2, is unstable, has no approval, lacks full CI on its newest head, and has requested responsive/advanced mode work. Finish it completely or defer it before integration.
PORT ONLY #6624 backup restore re-login — focused v2 port opened as #6778; do not merge unrelated branch drift.
PORT ONLY #6631 MCP OAuth base URL — expanded and production-smoked current-v2 port opened as #6779.
SUPERSEDED #6662 board access-control form — current release/v2 already renders the access/danger forms outside the unified outer form; no duplicate port required.
PORT ONLY #6674 weather and NO_EXTERNAL_CONNECTION — focused current-v2 privacy/offline port opened as #6780.
PORT ONLY #6749 Unraid memory utilization — focused current-v2 metric fix opened as #6781.
PORT ONLY #6250 container CPU utilization — focused current-v2 normalization fix opened as #6782.
PORT ONLY #6733 Helm documentation — current chart metadata port opened as #6783; regenerate again after publishing the v2 chart.
DEFER WHOLESALE #6601 broad dependency update — its 6,000-line lock/dependency churn is not a safe release patch. Use #6775, #6776 and #6788 for the focused candidate-specific security work.

Feature/UI candidates to include or defer explicitly

DEFER #6657 OMV volume selection — feature work, not a GA blocker.
DEFER #6645 Beszel GPU metrics — feature work, not a GA blocker.
PORT ONLY #6621 Downloads column width — minimal current-v2 fix opened as #6784; supersedes #6122.
DEFER #6603 isolated pnpm linker/phantom dependencies — broad package-manager/workspace refactor.
DEFER #6572 Hermes Agent integration — large new integration and widget.
DEFER #6562 favicon detection — new network-facing app-form behavior.
DEFER #6561 Komodo integration — large new integration.
DEFER #6546 REST dashboard automation — large API expansion; release separately after threat-model review.
DEFER #6537 dashboard memory work — very large conflicting performance branch; benchmark separately.
DEFER #6518 Sportarr integration — new integration.
DEFER #6517 UGOS integration — conflicting new integration.
DEFER #6515 SABnzbd archived-history options — changes requested remain.
DEFER #6458 API add-item section targeting — changes requested remain.
DEFER #6393 board keyboard shortcuts — conflicting feature work.
PORT ONLY #6295 Nextcloud subpath fix — current-v2 port opened as #6786.
PORT ONLY #6294 nested OIDC claims — current-v2 port opened as #6785 while preserving newer auth guards.
PORT ONLY #6210 UniFi default ports — cleaned current-v2 port opened as #6787.
SUPERSEDED #6148 path-only app URLs — current v2 already accepts safe same-origin paths and blocks unsafe schemes through getSafeAppHref; #5595 is also superseded.

Remaining open `dev` candidates

DEFER #6214 disabled users, #6140 Dawarich, #6144 FileFlows, #6145 Pushover, #4957 Incus and #4549 automatic layout — drafts, conflicting branches or new-feature scope.
CLOSE/SUPERSEDED #6132 dependency group — stale/conflicting dependency churn; use candidate-specific advisory fixes.
Confirm the release owner accepts every recommended DEFER classification above before feature freeze.

Stack and stale-PR cleanup

Close or reframe #6545 after the real promotion PR exists.
Close internal stack PRs #6569, #6555, #6503, #6502, #6482, #6450 and #6356 after confirming their commits are present in release/v2.
CLOSE classification recorded for #6549: its head and base are both dev, and its history includes acknowledged unrelated media changes despite approval.
Close #6549 after preserving any unique issue/history references.
CLOSE/SUPERSEDED classifications recorded for #6122, #6148, #5595, #6621, #6624, #6631, #6674, #6749, #6250, #6294, #6295, #6210 and #6733 after their current-v2 replacement or source-equivalent behavior is merged.
Close those source/duplicate PRs only after the replacement PRs land and their history is linked.
Move all accepted deferred work to a v2.0.x or v2.1 milestone.
Confirm no open PR still targets release/v2 when the candidate is frozen.

Documentation and announcement branches

PR #6760 is merged into release/v2.
Do not merge origin/feat/homarr-v2-release-blog wholesale. It remains two commits behind and nine ahead, but changes 199 files, combines the article with a broad documentation rewrite, deletes many current screenshots and includes apps/docs/.release-research/ scratch material.
Split a focused release-material branch containing only the reviewed Homarr 2.0 blog, required media and GitHub/Reddit/Discord announcement variants; rebase that branch after the product/docs freeze.
Remove private release-research files from the publishable diff.
Replace announcement links to internal stack PR #6545 with the real promotion/release URL.
Replace GA announcement calls to the preview/beta thread with the production release, upgrade guide and support destinations; keep a beta link only if it serves a deliberate archival purpose.
Update the blog path/date if the final publication date differs from 2026/09/03.

4. Security and privacy gate

Re-run mise exec -- pnpm audit --prod --audit-level high on the final candidate.
Reduce all critical production-reachable findings to zero.
Merge #6775's patched @auth/core release and validate every authentication provider on the final candidate.
Merge #6775's patched next-auth release and validate failure-open, email normalization and session behavior on the final candidate.
Merge #6776's patched protobufjs 7.x resolution and rerun the audit on the final candidate.
Merge #6788 after #6775 and #6776, resolve/review the resulting lockfile once, and repeat its typecheck, docs, container and production-audit evidence on the rebased head.
Resolve the repository-wide development-scoped handlebars alert separately or record why it does not block production; it is not present in the candidate's production dependency audit.
#6788 patches the audited high findings for undici, adm-zip, fast-xml-parser, axios, postcss, serialize-javascript, fast-uri, js-yaml, brace-expansion, find-my-way, immutable, svgo, shell-quote, @xmldom/xmldom and their affected paths; #6776 patches protobufjs.
Record a time-bounded risk decision for the two image-size highs. They are limited to Docusaurus MDX image processing during the docs build, but no patched package is currently published. Upgrade immediately when image-size>=2.0.3 becomes available, or hold GA if the security owner does not accept that build-time exposure.
For every accepted advisory, record package path, runtime reachability, mitigating controls, owner and target patch release.
Confirm CodeQL has no open alert on the final SHA.
Confirm secret scanning has no open alert on the final SHA.
Review authentication, API keys, session invalidation, CSRF and authorization boundaries.
Test OIDC, credentials authentication and LLDAP using non-admin and admin users.
Test board, integration, app, user, group, API, MCP and settings permissions.
Verify public boards never expose private integrations, secrets, Custom Widget credentials or assistant context.
Verify logs, analytics and error messages redact tokens, passwords, headers and URLs containing credentials.
Verify Custom Widget URL/SSRF, secret, preview-action and sandbox boundaries.
Verify MCP destructive tools are permission-checked and clearly described.
Review GitHub Actions permissions; repository workflows currently default to write and can approve PRs.
Decide whether release workflows must pin third-party actions to immutable SHAs. SHA pinning is not currently required.

5. Database migration, backup and rollback

v2 adds parallel migrations for Custom Widget v2 tables, layout gutters, layout roles, assistant tables, and header preferences/branding to SQLite, MySQL and PostgreSQL, plus the custom section/gutter migration.

Automated migration validation

SQLite migration suite passes on the final candidate.
MySQL migration suite passes on the final candidate.
PostgreSQL migration suite passes on the final candidate.
Migration journal integrity suite passes.
Schema parity checks pass.
Custom Widget v1 data/board-reference preservation tests pass for all three drivers.
Backup import/export, concurrent restore and temporary-directory cleanup tests pass.
Same-key and changed-key secret re-encryption tests pass.

Real upgrade rehearsal — repeat for every driver

Use a representative v1.76.2 installation with users, groups, boards, apps, integrations, secrets, media, tasks and Custom Widgets.
Record source version, database driver, architecture, image digest and backup checksum.
Back up the database, /appdata, certificates and exact SECRET_ENCRYPTION_KEY.
Upgrade using the exact final-candidate image digest.
Confirm migrations run exactly once and startup becomes healthy.
Restart again and confirm migrations do not repeat or corrupt state.
Verify users, groups, sessions, API keys and permission scopes.
Verify boards, sections, containers, rails, layouts, gutters and breakpoints.
Verify apps, integrations, encrypted secrets and search engines.
Verify Custom Widget v1 archives and v2 definitions/secrets.
Verify assistant configuration/history and branding/header preferences.
Export a v2 backup and restore it into a clean v2 deployment.
Confirm restore explains session invalidation and sends the user cleanly to sign-in.
Test a backup made with a different encryption key.
Test a corrupt, incomplete, oversized and wrong-driver backup.
Restore the original v1 backup as the rollback rehearsal.
State clearly whether v1 can open a v2-migrated database. If unsupported, prohibit rollback with the migrated database and require restoration of the pre-upgrade backup.

6. Product acceptance matrix

Installation and runtime

Docker Compose fresh install.
Docker Compose upgrade from v1.76.2.
amd64 image.
arm64 image, including Raspberry Pi-class hardware.
SQLite, MySQL and PostgreSQL.
Internal Redis and external Redis.
Reverse proxy with HTTPS and WebSocket forwarding.
IPv4-only, IPv6-only where supported, and dual-stack behavior.
Custom PUID/PGID with bind mounts and named volumes.
Docker and Podman sockets, including multiple socket configuration.
Kubernetes and current Helm chart.
Unraid, TrueNAS, Synology, QNAP, Portainer and Proxmox documented paths.
Source installation with Node 24.18.0 and pnpm 11.15.1.
_FILE secret variants and trusted certificates.
Restart, health-check and graceful-shutdown behavior.
Offline/NO_EXTERNAL_CONNECTION behavior.
Low-memory startup and a large real dashboard.

Authentication, users and onboarding

Fresh onboarding from first request to usable admin dashboard.
Upgrade bypasses onboarding correctly.
Local sign-in, sign-out, expiry, invalid credentials and password recovery.
OIDC and LLDAP sign-in, account linking and logout.
Admin and non-admin navigation.
Create, edit, disable/delete and restore users where supported.
Create groups, assign members and verify permission inheritance.
Public/private board access and home-board selection.
Authentication branding/background does not disclose private app or integration data.

Boards and layouts

Create, rename, duplicate, import, export and delete a board.
Create/edit/delete sections, containers and rails.
Drag, resize, multi-move and move into/out of containers.
Responsive Base, Custom and Mobile layout selection and repair.
Sidebars and collapsible/scrollable containers.
Empty-board and missing-board states.
Edit/view mode transitions, context menus and keyboard interactions.
Mobile phone, tablet, 1080p dense grid and large desktop viewport.
Light/dark theme, background, border radius and custom CSS.
Undo/redo/reset behavior where exposed.

Apps, search and management

App create/edit/delete, favicon/icon selection, ping and Docker association.
Integration create/edit/test/delete and app linking.
Search engines, DDG bangs and external search.
Spotlight modes, commands and permission filtering.
Media management and release search.
Logs, contextual widget timestamps and redaction.
Task list, manual trigger, cron status and Redis reconnect.
Certificates add/remove/use flow.
Backup download and restore flow.
Server settings, analytics consent, culture, branding and global custom CSS.

Widgets and integrations

Run documentation coverage validation for every registered widget/integration slug.
Smoke every one of the 59 current widget documentation categories against its actual widget definition.
Smoke each integration family with a real service or documented representative fixture.
Validate normal, loading, empty, partial-data, authentication-error, timeout and offline states.
Validate widget context menus, edit forms, optional integrations and advanced mode.
Validate cache/refetch behavior and WebSocket updates.
Validate chart labels, tables and text at dense/small sizes.
Validate integration actions such as Docker, DNS, download, smart-home and media requests.
Confirm unsupported upstream metrics are shown as unavailable rather than fabricated zeroes.

Custom Widgets, Assistant, MCP and Workshop

Custom Widget create, import, edit, validate, preview, save, install, update, uninstall and rollback.
Custom Widget queries/actions, redacted journal, secrets and invalidation behavior.
Workshop browse, search, detail, screenshot, comments, authentication, publishing and moderation.
Workshop outage does not break already-installed widgets.
Assistant configuration for Homarr, OpenRouter, Ollama and applicable compatible providers.
Assistant conversation, tools, custom CSS and Custom Widget authoring.
Assistant consent/privacy claims match actual telemetry and provider behavior.
MCP HTTP transport, authentication, OAuth discovery/login, API-key access and error responses.
Decide whether Custom Widgets and Workshop remain labelled experimental for GA and define their support policy.

Browser, accessibility and performance

Chromium final-candidate E2E passes.
Firefox smoke passes; current automated E2E is Chromium-only.
WebKit/Safari smoke passes if it is in the supported browser matrix.
Keyboard-only navigation and visible focus states.
Screen-reader labels for forms, dialogs, menus and live restore states.
Reduced-motion behavior and acceptable color contrast.
Compare v1.76.2 and v2 cold start, server memory, browser memory and dashboard refresh time.
Confirm no sustained request storm or duplicate subscriptions on large dashboards.
Confirm widgets do not take the beta-reported 72 seconds to recover after a full page refresh.

7. Public beta feedback closure

Track every report from issue #6600 with a reproducer and fix, or a linked issue and explicit defer decision.

Dense Beszel/widget text scaling — current release/v2 contains merged #6616; still retest the reported 13/23/24-column layouts on the final candidate.
Incorrect v1.74 update indicator — the current public preview displays Version 2.0.0; still verify the final immutable image and update checker report the production tag without a false update.
Full-page widget refresh reported as roughly 5 seconds in v1 versus 72 seconds in v2 — the 2026-09-06 public demo smoke completed an authenticated network-idle reload in 3.2 seconds with no application console errors. Repeat with a large real-provider dashboard and profile server/browser memory before closing.
Date/time widget missing world clocks — reproduced as fixed on the current public preview: keyboard activation opened advanced view with New York, Paris and Tokyo clocks. Retest the final candidate after freeze.
Media Releases widget reported non-functional — current public demo advanced view renders seven populated mock releases. Repeat with every supported real provider before closing the report.
Compact bookmarks reported as not compact — current release/v2 contains merged #6747; visually retest all supported sizes and mobile layouts.
No new beta-thread comments were present after 2026-08-29 when refreshed on 2026-09-06.
Review the beta issue again for new comments immediately before freeze.
Reply with fix/issue links so testers know each report's disposition.
Close or convert the beta thread only after all reports have a disposition.

8. Documentation and placeholder cleanup

User documentation

Review and merge #6774's canonical Upgrade from v1 to v2 page.
Cover backup prerequisites, database migrations, changed environment variables and rollback limitations.
Cover Custom Widget v1-to-v2 migration and archived definitions.
Cover Workshop data/volume backup and restore.
Cover Docker, Helm/Kubernetes, Unraid, TrueNAS, Synology, QNAP, Portainer, Proxmox and source upgrades.
List removed/renamed behavior and known issues.
Verify all environment defaults, image names, ports, paths and commands against source.
Run mise exec -- pnpm turbo build --filter=@homarr/docs on the final docs commit.
Treat every broken link, missing image and invalid MDX page as a blocker.
Verify generated integration/widget coverage after the final registry is frozen.
Verify screenshots against the final UI on desktop and mobile.
Verify Algolia indexing/recrawl after deployment.
Decide whether merging v2 into dev may publish GA-oriented docs before the application release.

Repository and placeholder cleanup

Review and merge #6773's .github/pull_request_template.md update; it points documentation changes at the monorepo and describes the current v2 branch flow.
Decide whether to restore a root README.md. Only docs/README.md currently exists.
Review and merge #6772; it replaces the seven committed href="null" integration links and makes the generator use canonical integration documentation URLs.
Review and merge #6777; it replaces .env.example's SQLite database placeholder with the runnable source-development path ./db.sqlite, documents the separate /appdata/db/db.sqlite container default and keeps other database examples commented.
Review and merge #6771; it comments out UNSAFE_ENABLE_MOCK_INTEGRATION in .env.example.
Repeat #6771's disabled/enabled direct URL, API creation and onboarding smoke on the final candidate.
Review and merge #6777's removal of copy-pastable AUTH_SECRET and SECRET_ENCRYPTION_KEY values; confirm the final source-install guide requires two different random values.
Keep intentional UI input placeholders, test-domain example.com values, the Workshop password replacement example and media-year TBD; these are not unfinished product copy.
Run another focused scan for TODO, TBD, lorem ipsum, coming soon, href="null", fake URLs, temporary files, screenshots from previews and beta-only wording.

Release article and notes

Rebase and review feat/homarr-v2-release-blog after all product decisions are final.
Ensure article claims about performance, privacy, features and compatibility have current evidence.
Curate release notes; autogenerated notes from 562 release-branch commits are not sufficient by themselves.
Run Semantic Release in dry-run mode from a faithful final-candidate branch and inspect the proposed version and changelog.
Ensure the draft GitHub release body stays below GitHub limits and links to the upgrade guide.

9. Workshop production readiness

Decide the production Workshop domain, WORKSHOP_API_URL, WORKSHOP_WEB_URL and WORKSHOP_PUBLIC_ORIGIN.
Snapshot the PocketBase database, files and configuration.
Rehearse the documented v2 Workshop migration/restore procedure.
Verify GitHub OAuth callback URLs and credentials.
Verify allowed origins, email links, administrator access and moderation.
Test amd64 and arm64 Workshop images by immutable digest.
Promote the exact approved Workshop digest from :v2 to its production tag.
Verify Workshop health and a Homarr install/update flow after production promotion.
Verify docs continue to build and render if Workshop is unavailable.
Define Workshop rollback separately from the Homarr application rollback.

10. CI/CD production readiness

Fix before promotion

Merge #6770, then prove the weekly workflow exits successfully with a clear no releasable change result when Semantic Versioning finds no bump.
Merge #6770, then prove scheduled runs notify by default and manual runs respect the notification checkbox.
Prove weekly success, failure and major-release/manual-merge paths in controlled runs.
Correct the v2 release ruleset target or remove the stale legacy branch/rule after preserving required checks.
Add required final checks to main; its current productive ruleset requires review but no status checks.
Require at least one human approval, resolved threads, stale-approval dismissal and no force push/deletion for the final promotion.
Review ruleset bypass actors and limit release bypasses to the necessary bots/owners.
Protect a real production deployment environment and bind the irreversible Semantic Release/tag/publish path to it, or record an explicit alternative control. The current unprotected, unused prod environment is not a gate.
Merge #6770's removal of the false archived-repository handoff and verify the monorepo dev docs deployment is authoritative.
Review and merge #6770's explicit production deployment failure/cancellation notification.
Review and merge #6770's mandatory post-release check that verifies dev contains the Semantic Release commit after synchronization; prove the verification fails loudly when synchronization is incomplete.
Decide whether the absent beta branch is intentional. Remove dead beta logic or create/test a real RC path.
Verify a manual dispatch redeploys the latest existing release and cannot create an unintended tag.

Final candidate checks

Formatting.
Lint.
Full typecheck.
Full production build.
Complete unit suite.
SQLite migration suite.
MySQL migration suite.
PostgreSQL migration suite.
OpenAPI schema check.
Custom Widget architecture and bundle-budget checks.
Workshop integration and image checks.
Container and E2E.
CodeQL for Actions, Go and JavaScript/TypeScript.
amd64 image build.
arm64 image build.
Multi-platform manifest publication.
Docs production build and link validation.
Production dependency audit and signed risk report.
All required checks are attached to the exact final SHA, not only an earlier release/v2 SHA.

Artifact integrity

Produce and test build-alpine-amd64.tar.gz.
Produce and test build-alpine-arm64.tar.gz.
Produce and test build-debian-amd64.tar.gz.
Produce and test build-debian-arm64.tar.gz.
Publish SHA-256 checksums.
Generate/review an SBOM for production images and archives.
Decide and document signature/provenance verification.
Verify the archives and GHCR manifests originate from the same immutable release SHA.

11. Discord and community readiness

Confirm the DISCORD_WEBHOOK and DISCORD_WEBHOOK_AUTOMATIC_RELEASE secret names exist without exposing their values.
Confirm both webhook values still work; their name-level update timestamps are from 2024 and 2023 respectively.
Test release notifications in a non-public/test channel.
Prepare pre-release notice with date, expected impact, backup requirement and upgrade-guide link.
Brief moderators and support maintainers on breaking changes, migrations and rollback.
Prepare FAQ responses for permissions, layouts, Custom Widgets, Workshop, Assistant, MCP and databases.
Prepare success, delay, workflow-failure and rollback messages.
Review the prepared Discord copy in apps/docs/release-announcements/2.0.0/discord.md after merging the release article branch.
Prepare GitHub, Reddit and other community variants from the same verified claims.
Pin/update the relevant Discord channels and remove beta-only install instructions after GA.
Assign people to monitor Discord and GitHub for at least the first 24–48 hours.

12. Final go/no-go

Candidate identity

Final dev SHA: ________________________________________.
Expected version: v2.0.0.
Homarr candidate manifest digest: ________________________________________.
Workshop candidate manifest digest: ________________________________________.
Database rehearsal evidence: ________________________________________.
CI run: ________________________________________.
Docs build/deploy evidence: ________________________________________.
Security report/risk acceptance: ________________________________________.
Rollback procedure: ________________________________________.

Sign-off

Product acceptance owner: ________________ / date: ________________.
Security owner: ________________ / date: ________________.
Database owner: ________________ / date: ________________.
Infrastructure owner: ________________ / date: ________________.
Docs/communications owner: ________________ / date: ________________.
Final release owner GO: ________________ / date: ________________.
A rollback owner is online and the pre-upgrade backups are accessible.
No unchecked hard blocker remains without written acceptance.

13. Release-day execution

Trigger or create the dev -> main release PR.
Verify the workflow proposes exactly v2.0.0 and identifies a major bump.
Confirm the major PR did not auto-merge.
Recheck the PR diff, approvals, required checks and final candidate SHA.
Human-merge the PR into main during the release window.
Watch Semantic Release create the v2.0.0 tag and draft release.
Watch amd64 and arm64 production image builds.
Watch all four release archives upload.
Watch ghcr.io/homarr-labs/homarr:v2.0.0 publish.
Verify ghcr.io/homarr-labs/homarr:latest resolves to the same multi-platform manifest.
Verify the GitHub release is public, not draft/prerelease, and contains the curated notes and upgrade-guide link.
Download and smoke-test each release archive.
Verify image version and /api/health revision against the release SHA.
Verify the real deployed/runtime image digest, not only the registry tag.
Promote and verify Workshop production.
Verify public documentation and Algolia search.
Verify Discord/community announcements.
Verify post-release synchronization puts the Semantic Release commit back into dev.
Run a production smoke: sign-in, board load, widget query, integration query, WebSocket update, task, backup and Workshop browse/install.

14. Rollback triggers and execution

Define rollback thresholds for startup failure, migration failure, authentication lockout, widespread blank boards, data loss, image failure and critical security regression.
Stop new writes if data integrity is uncertain.
Capture logs, exact image digest and database state before rollback.
Re-point latest only if the release owner invokes rollback.
Restore the pre-v2 database/appdata backup when v1 cannot read the migrated database.
Verify v1.76.2 health, authentication, boards, integrations and backups after rollback.
Publish the prepared rollback notice.
Keep v2.0.0 artifacts/digests recorded for investigation; do not silently overwrite evidence.

15. Post-release follow-through

Monitor release workflow, GHCR pulls, startup errors, migration errors and Workshop errors.
Monitor Discord, GitHub issues/discussions and support channels for 24–48 hours.
Maintain a public known-issues list.
Triage v2 reports separately from pre-existing v1 issues.
Prepare v2.0.1 for fixes that are safer than rollback.
Remove or redirect homarr-test:v2 and preview instructions when no longer needed.
Confirm beta users have a supported path to GA.
Close/repurpose the v2.0.0 milestone.
Close obsolete stack branches and PRs after preserving history.
Hold a short retrospective covering integration drift, security backlog, CI failures, docs handoff and beta feedback.

Refresh commands

Run these from a clean Homarr checkout. They are evidence helpers, not substitutes for reviewing the results.

git fetch origin main dev release/v2 v2 next --tags --prune
git show -s --format='%H %ci %s' origin/main origin/dev origin/release/v2
git rev-list --left-right --count origin/dev...origin/release/v2
git diff --shortstat origin/dev...origin/release/v2
gh pr list --repo homarr-labs/homarr --state open --limit 100
gh run list --repo homarr-labs/homarr --workflow deployment-weekly-release.yml --limit 10
gh run list --repo homarr-labs/homarr --workflow deployment-docker-image.yml --limit 10
gh release list --repo homarr-labs/homarr --limit 10
mise exec -- pnpm audit --prod --audit-level high
docker buildx imagetools inspect ghcr.io/homarr-labs/homarr-test:v2
docker buildx imagetools inspect ghcr.io/homarr-labs/workshop:v2

Never print secret values while collecting release evidence.

50 KiB Raw Blame History Unescape Escape