feat!: release v2 (#6545)

Co-authored-by: Artur <145776561+arturict@users.noreply.github.com>
Co-authored-by: arturict <arturict@users.noreply.github.com>
Co-authored-by: Thomas <thomas@ajnart.fr>
Co-authored-by: Afonso Jorge Ramos <afonsojorgeramos@gmail.com>
Co-authored-by: Danura30082 <danura30082+github@gmail.com>
Co-authored-by: Kushie <122986913+kushiemoon-dev@users.noreply.github.com>
Co-authored-by: ajnart <thomas@ajnart.fr>
Co-authored-by: ajnart <thomas@ajnart.dev>
Co-authored-by: chenjun <chenjun@foxmail.com>
Co-authored-by: Wikibear <wikibear@users.noreply.github.com>
Co-authored-by: Bergasha <bergasha@gmail.com>
Co-authored-by: leafyelin <43306196+leafyelin@users.noreply.github.com>
Co-authored-by: Lucas Araujo <lucas.lra@gmail.com>
Co-authored-by: GreenMonito <86085570+GreenMonito@users.noreply.github.com>
Co-authored-by: Nerdy-Technician <roffo@nerdy-technician.social>
Co-authored-by: Jun <34545896+jcstrong@users.noreply.github.com>
Co-authored-by: Edmond Abraham <54119952+gitedmond@users.noreply.github.com>
Co-authored-by: thrawnx <tight.bulb9384@fastmail.com>
Co-authored-by: Chris <58918656+nordada@users.noreply.github.com>
Co-authored-by: yi111 <153097222+Yi-111-a@users.noreply.github.com>
Co-authored-by: Yanis <naamaneyanis@gmail.com>
Co-authored-by: Wikibear <me@sej.de>
Co-authored-by: alessiottavo <93441886+alessiottavo@users.noreply.github.com>

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -25,6 +25,18 @@ body:
     attributes:
       label: Additional information
       description: Add any other information related to the bug here, screenshots if applicable.
+  - type: input
+    id: exactBuild
+    attributes:
+      label: Exact build or image
+      description: For preview or development builds, include the commit SHA or image digest. A moving tag such as v2 is not enough to identify the build.
+      placeholder: "Commit SHA, image digest, or release version"
+  - type: input
+    id: lastWorkingVersion
+    attributes:
+      label: Last working version
+      description: If this worked before, include the last version or build where you tried the same action. Leave blank if unknown.
+      placeholder: "Version or commit SHA"
   - type: dropdown
     id: version
     attributes:

.github/ISSUE_TEMPLATE/custom_widget_bug.yml

@@ -0,0 +1,48 @@
+name: 🐞 Custom Widget bug
+description: Report a problem with a Custom JSX widget, its requests, preview, or editor
+title: "bug: custom widget "
+labels: ["needs triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Share a small reproduction so we can distinguish widget code, upstream API, and Homarr problems.
+        Remove API keys, passwords, tokens, cookies, authorization headers, private URLs, and personal data from everything you share, including exports and screenshots. Replace private hosts with `https://example.invalid` while preserving relevant paths and response structure.
+  - type: textarea
+    id: behavior
+    attributes:
+      label: Actual and expected behavior
+      description: Describe what happens and what you expected. Include the exact error text and a sanitized screenshot if useful.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to reproduce
+      description: Include the affected request or control, relevant widget options, and whether this occurs in Test, preview, or on the dashboard. For layout issues, include the widget size and desktop or mobile viewport.
+    validations:
+      required: true
+  - type: textarea
+    id: definition
+    attributes:
+      label: Sanitized widget definition
+      description: Paste or attach the exported JSON with sources, requests, options, and JSX template. Prefer the smallest definition that reproduces the problem. If export fails, include the relevant JSX and request configuration. Check for private URLs and sensitive data before sharing.
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Include the exact Homarr release, commit SHA, or image digest; installation method; browser/version; and desktop or mobile OS. For request issues, include the source type (HTTP or integration), integration kind, and upstream service version. Do not include server URLs or credentials.
+      placeholder: |
+        Homarr version / commit / image digest:
+        Installation method:
+        Browser and OS:
+        Source type, integration kind, and service version:
+    validations:
+      required: true
+  - type: textarea
+    id: diagnostics
+    attributes:
+      label: Sanitized API response and logs
+      description: For request or data issues, include the request ID, method, relative API path, HTTP status, and a small response sample preserving field names and types. Add relevant Homarr or browser console errors. Remove sensitive values and private URLs; leave blank for purely visual issues.

.github/actions/extract-build-artifact/action.yaml

@@ -20,7 +20,7 @@ runs:
   using: "composite"
   steps:
     - name: Prebuilt debian dependencies
-      uses: homarr-labs/homarr/.github/actions/prebuilt-debian@dev
+      uses: ./.github/actions/prebuilt-debian
       id: prebuilt-debian
       with:
         architecture: ${{ inputs.architecture }}

.github/actions/prebuilt-debian/action.yaml

@@ -11,9 +11,6 @@ outputs:
 runs:
   using: "composite"
   steps:
-    - uses: actions/checkout@v7
-      with:
-        persist-credentials: false
     - name: Set up Docker Buildx
       uses: docker/setup-buildx-action@v4
 

.github/pull_request_template.md

@@ -4,18 +4,18 @@
   <h3>Homarr</h3>
 </div>
 
-**Thank you for your contribution. Please ensure that your pull request meets the following pull request:**
+**Thank you for your contribution. Please ensure that your pull request meets the following requirements:**
 
-- [ ] Builds without warnings or errors (`pnpm build`, autofix with `pnpm format:fix`)
-- [ ] Pull request targets `dev` branch
+- [ ] Relevant checks pass without warnings or errors
+- [ ] Pull request targets the intended base branch (`dev` by default; `release/v2` for v2 release work)
 - [ ] Commits follow the [conventional commits guideline](https://www.conventionalcommits.org/en/v1.0.0/)
-- [ ] No shorthand variable names are used (eg. `x`, `y`, `i` or any abbrevation)
-- [ ] Documentation is up to date. Create a pull request [here](https://github.com/homarr-labs/documentation/).
-- [ ] When using AI; No temp files are checked in, the code style follows the rest of the project
+- [ ] No shorthand variable names are used (for example, `x`, `y`, `i`, or abbreviations)
+- [ ] User-facing changes include matching documentation updates under `apps/docs`
+- [ ] When using AI, no temporary files are checked in and the code style follows the rest of the project
 
 **When contributing a new integration or widget:**
 
 - [ ] I confirmed manually that the integration or widget is working with a real system and performed basic smoke
-  tests (e.g. what happens if it is offline)
+      tests (e.g. what happens if it is offline)
 - [ ] Optional but recommended: I confirm that I am willing to be added to the `CODEOWNERS` of this feature and will
-  provide support and maintain the integration (e.g. in case of breaking or failure)
+      provide support and maintain the integration (e.g. in case of breaking or failure)

.github/workflows/autofix.yml

@@ -1,47 +1,35 @@
-name: Auto-fix lint and format
+name: Formatting
 
 on:
   pull_request:
     types: [opened, synchronize, reopened]
-    branches: ["*"]
+    branches: ["**"]
 
 permissions:
-  contents: write
+  contents: read
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
   cancel-in-progress: true
 
 jobs:
-  autofix:
-    name: Auto-fix
-    if: github.event.pull_request.head.repo.id == github.repository_id
+  format:
+    name: Check formatting
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
       - uses: actions/checkout@v7
         with:
           fetch-depth: 0
-          ref: ${{ github.head_ref }}
+          persist-credentials: false
 
       - name: Setup
         uses: ./tooling/github/setup
 
-      - name: Get changed files
-        id: changed
+      - name: Check changed files
         env:
           BASE_REF: ${{ github.base_ref }}
         run: |
-          git diff --name-only --diff-filter=ACMR "origin/${BASE_REF}...HEAD" -- '*.ts' '*.tsx' '*.js' '*.jsx' > /tmp/changed-files
-          echo "count=$(wc -l < /tmp/changed-files | tr -d '[:space:]')" >> $GITHUB_OUTPUT
-
-      - name: Auto-fix lint + format
-        if: steps.changed.outputs.count != '0'
-        run: |
-          xargs -r -a /tmp/changed-files pnpm exec oxlint --fix || true
-          xargs -r -a /tmp/changed-files pnpm exec oxfmt --write
-
-      - name: Commit fixes
-        uses: stefanzweifel/git-auto-commit-action@v7
-        with:
-          commit_message: "style: auto-fix lint and format"
+          git diff --name-only --diff-filter=ACMR -z "origin/${BASE_REF}...HEAD" -- \
+            '*.css' '*.js' '*.json' '*.jsonc' '*.jsx' '*.md' '*.mdx' '*.scss' '*.ts' '*.tsx' '*.yaml' '*.yml' \
+            | xargs -0 -r pnpm exec oxfmt --check --

.github/workflows/bot-auto-merge-reconcile.yml

@@ -20,7 +20,7 @@ jobs:
         uses: actions/create-github-app-token@v3
         with:
           private-key: ${{ secrets.RENOVATE_APPROVE_PRIVATE_KEY }}
-          client-id: ${{ secrets.RENOVATE_APPROVE_APP_ID }}
+          client-id: ${{ vars.RENOVATE_APPROVE_CLIENT_ID }}
           permission-pull-requests: write # required to enable auto-merge
 
       - name: Install GitHub CLI

.github/workflows/bot-pr-automerge.yml

@@ -28,7 +28,7 @@ jobs:
         uses: actions/create-github-app-token@v3
         with:
           private-key: ${{ secrets.RENOVATE_APPROVE_PRIVATE_KEY }}
-          client-id: ${{ secrets.RENOVATE_APPROVE_APP_ID }}
+          client-id: ${{ vars.RENOVATE_APPROVE_CLIENT_ID }}
           permission-pull-requests: write # required to approve a pull request and enable auto-merge
 
       - name: Install GitHub CLI

.github/workflows/ci.yml

@@ -3,13 +3,15 @@ name: CI
 on:
   pull_request:
     types: [opened, synchronize, reopened, ready_for_review]
-    branches: ["*"]
+    branches: ["**"]
   pull_request_target:
     types: [closed]
-    branches: ["*"]
+    branches: ["**"]
   push:
-    branches: [main, dev, beta, next]
+    branches: [main, dev, beta, next, v2, release/v2]
   merge_group:
+  release:
+    types: [published]
   workflow_dispatch:
     inputs:
       operation:
@@ -34,8 +36,10 @@ permissions:
   contents: read
 
 concurrency:
-  group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.event.pull_request.number || inputs.pr_number || github.ref }}
-  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+  # Every event for a PR shares one group so a close event cancels stale image
+  # publication and a newer synchronize run cannot be overwritten by an older run.
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || inputs.pr_number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' || github.event_name == 'pull_request_target' || github.event_name == 'workflow_dispatch' || github.ref != 'refs/heads/main' }}
 
 env:
   FORCE_COLOR: 3
@@ -45,11 +49,17 @@ env:
   PREVIEW_IMAGE: ghcr.io/homarr-labs/homarr-test
 
 jobs:
+  database-validation:
+    name: Database validation
+    if: github.event_name != 'pull_request_target' && (github.event_name != 'release' || startsWith(github.event.release.tag_name, 'v2.')) && (github.event_name != 'workflow_dispatch' || inputs.operation != 'cleanup')
+    uses: ./.github/workflows/database.yml
+
   fast-gate:
     name: Fast gate
-    if: github.event_name != 'pull_request_target' && (github.event_name != 'workflow_dispatch' || inputs.operation != 'cleanup')
+    needs: database-validation
+    if: ${{ !cancelled() && github.event_name != 'pull_request_target' && (github.event_name != 'release' || startsWith(github.event.release.tag_name, 'v2.')) && (github.event_name != 'workflow_dispatch' || inputs.operation != 'cleanup') }}
     runs-on: ubuntu-latest
-    timeout-minutes: 15
+    timeout-minutes: 20
     env:
       TURBO_API: ${{ secrets.TURBO_API }}
       TURBO_TEAM: ${{ secrets.TURBO_TEAM }}
@@ -59,6 +69,11 @@ jobs:
       TURBO_SCM_HEAD: ${{ github.sha }}
       TURBO_PLATFORM: linux/amd64
     steps:
+      - name: Require database validation
+        env:
+          DATABASE_RESULT: ${{ needs.database-validation.result }}
+        run: test "$DATABASE_RESULT" = success
+
       - uses: actions/checkout@v7
         if: "!env.ACT"
         with:
@@ -87,21 +102,29 @@ jobs:
       - name: Validate workspace configuration
         run: pnpm lint:ws
 
-      - name: Run unit tests
-        run: pnpm test
+      - name: Validate Custom Widget architecture
+        run: pnpm check:custom-widgets
+
+      - name: Validate checked-in OpenAPI schema
+        run: pnpm check:openapi
+
+      - name: Validate Custom Widget bundle budget
+        run: |
+          pnpm turbo run build --filter=@homarr/nextjs
+          pnpm check:custom-widget-bundle
 
   container:
-    name: Container and E2E
-    needs: fast-gate
+    name: Container and migration smoke
+    # Legacy converter verification is opt-in, not a release publication gate.
+    needs: [fast-gate, preview-amd64]
     if: |
-      github.event_name == 'merge_group' ||
-      (github.event_name == 'pull_request' && github.event.pull_request.draft == false) ||
-      (github.event_name == 'workflow_dispatch' && (inputs.operation == 'validate' || inputs.operation == 'publish'))
+      !cancelled() && needs.fast-gate.result == 'success' &&
+      github.event_name == 'workflow_dispatch' && inputs.operation == 'validate'
     runs-on: ubuntu-latest
     timeout-minutes: 30
     permissions:
       contents: read
-      packages: write
+      packages: read
     steps:
       - uses: actions/checkout@v7
         if: "!env.ACT"
@@ -112,12 +135,21 @@ jobs:
       - name: Setup
         uses: ./tooling/github/setup
 
+      - name: Reuse amd64 preview image
+        if: needs.preview-amd64.outputs.digest != '' && !env.ACT
+        env:
+          DIGEST: ${{ needs.preview-amd64.outputs.digest }}
+        run: |
+          echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
+          docker pull "${PREVIEW_IMAGE}@${DIGEST}"
+          docker tag "${PREVIEW_IMAGE}@${DIGEST}" homarr-e2e
+
       - name: Set up Docker Buildx
-        if: "!env.ACT"
+        if: needs.preview-amd64.outputs.digest == '' && !env.ACT
         uses: docker/setup-buildx-action@v4
 
       - name: Build container once
-        if: "!env.ACT"
+        if: needs.preview-amd64.outputs.digest == '' && !env.ACT
         uses: docker/build-push-action@v7
         with:
           context: .
@@ -132,8 +164,8 @@ jobs:
             org.opencontainers.image.source=${{ github.server_url }}/${{ github.repository }}
             org.opencontainers.image.revision=${{ github.sha }}
             org.opencontainers.image.ref.name=pr-${{ github.event.pull_request.number || inputs.pr_number || 'none' }}
-          cache-from: type=gha,scope=homarr-linux-amd64
-          cache-to: type=gha,scope=homarr-linux-amd64,mode=max
+          cache-from: type=gha,scope=homarr-e2e
+          cache-to: type=gha,scope=homarr-e2e,mode=max
           secrets: |
             TURBO_API=${{ secrets.TURBO_API }}
             TURBO_TEAM=${{ secrets.TURBO_TEAM }}
@@ -173,8 +205,14 @@ jobs:
         if: steps.playwright-cache.outputs.cache-hit == 'true'
         run: pnpm exec playwright install-deps chromium
 
-      - name: Run E2E tests
-        run: pnpm test:e2e
+      - name: Install standalone converter test dependencies
+        run: npm ci --prefix tools/mysql-to-sqlite
+
+      - name: Verify converted database boots and survives restart
+        env:
+          NODE_ENV: development
+          CI: "true"
+        run: pnpm exec vitest run --project e2e e2e/mysql-conversion.spec.ts --maxWorkers 1
 
       - name: Upload E2E artifacts
         if: failure() && !env.ACT
@@ -184,37 +222,189 @@ jobs:
           path: e2e/test-results/
           retention-days: 7
 
-      - name: Determine preview tag
-        id: preview
-        if: |
-          !env.ACT &&
-          (
-            (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository) ||
-            (github.event_name == 'workflow_dispatch' && inputs.operation == 'publish')
-          )
-        env:
-          PR_NUMBER: ${{ github.event.pull_request.number || inputs.pr_number }}
-        run: echo "tag=pr-${PR_NUMBER}" >> "$GITHUB_OUTPUT"
+  preview-amd64:
+    name: Build amd64 preview image
+    needs: fast-gate
+    if: |
+      (
+        (github.event_name == 'pull_request' && github.event.pull_request.draft == false && github.event.pull_request.head.repo.full_name == github.repository) ||
+        (github.event_name == 'push' && github.ref == 'refs/heads/release/v2') ||
+        (github.event_name == 'workflow_dispatch' && inputs.operation == 'publish')
+      )
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: read
+      packages: write
+    outputs:
+      digest: ${{ steps.preview-build.outputs.digest }}
+    steps:
+      - uses: actions/checkout@v7
+        if: "!env.ACT"
+        with:
+          persist-credentials: false
+          ref: ${{ github.event_name == 'workflow_dispatch' && inputs.ref || '' }}
 
       - name: Log in to GHCR
-        if: steps.preview.outputs.tag != ''
+        if: "!env.ACT"
         uses: docker/login-action@v4
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Push preview image
-        if: steps.preview.outputs.tag != ''
-        env:
-          PREVIEW_TAG: ${{ steps.preview.outputs.tag }}
-        run: |
-          docker tag homarr-ci "${PREVIEW_IMAGE}:${PREVIEW_TAG}"
-          docker push "${PREVIEW_IMAGE}:${PREVIEW_TAG}"
+      - name: Set up Docker Buildx
+        if: "!env.ACT"
+        uses: docker/setup-buildx-action@v4
 
-      - name: Show Act publication result
-        if: env.ACT
-        run: echo "Act validated the publication path; external GHCR writes are disabled locally."
+      - name: Build and push amd64 preview image by digest
+        id: preview-build
+        if: "!env.ACT"
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          network: host
+          platforms: linux/amd64
+          outputs: type=image,"name=${{ env.PREVIEW_IMAGE }}",push-by-digest=true,name-canonical=true,push=true
+          cache-from: type=gha,scope=homarr-linux-amd64
+          cache-to: type=gha,scope=homarr-linux-amd64,mode=max
+          secrets: |
+            TURBO_API=${{ secrets.TURBO_API }}
+            TURBO_TEAM=${{ secrets.TURBO_TEAM }}
+            TURBO_TOKEN=${{ secrets.TURBO_TOKEN }}
+            TURBO_REMOTE_CACHE_SIGNATURE_KEY=${{ secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY }}
+
+  preview-arm64:
+    name: Build arm64 preview image
+    needs: fast-gate
+    if: |
+      (
+        (github.event_name == 'pull_request' && github.event.pull_request.draft == false && github.event.pull_request.head.repo.full_name == github.repository) ||
+        (github.event_name == 'push' && github.ref == 'refs/heads/release/v2') ||
+        (github.event_name == 'workflow_dispatch' && inputs.operation == 'publish')
+      )
+    runs-on: ubuntu-24.04-arm
+    timeout-minutes: 20
+    permissions:
+      contents: read
+      packages: write
+    outputs:
+      digest: ${{ steps.preview-build.outputs.digest }}
+    steps:
+      - uses: actions/checkout@v7
+        if: "!env.ACT"
+        with:
+          persist-credentials: false
+          ref: ${{ github.event_name == 'workflow_dispatch' && inputs.ref || '' }}
+
+      - name: Log in to GHCR
+        if: "!env.ACT"
+        uses: docker/login-action@v4
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up Docker Buildx
+        if: "!env.ACT"
+        uses: docker/setup-buildx-action@v4
+
+      - name: Build and push arm64 preview image by digest
+        id: preview-build
+        if: "!env.ACT"
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          network: host
+          platforms: linux/arm64
+          outputs: type=image,"name=${{ env.PREVIEW_IMAGE }}",push-by-digest=true,name-canonical=true,push=true
+          cache-from: type=gha,scope=homarr-linux-arm64
+          cache-to: type=gha,scope=homarr-linux-arm64,mode=max
+          secrets: |
+            TURBO_API=${{ secrets.TURBO_API }}
+            TURBO_TEAM=${{ secrets.TURBO_TEAM }}
+            TURBO_TOKEN=${{ secrets.TURBO_TOKEN }}
+            TURBO_REMOTE_CACHE_SIGNATURE_KEY=${{ secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY }}
+
+  publish-preview:
+    name: Publish multi-platform preview image
+    needs: [fast-gate, preview-amd64, preview-arm64]
+    if: |
+      !cancelled() &&
+      needs.fast-gate.result == 'success' &&
+      needs.preview-amd64.result == 'success' &&
+      needs.preview-arm64.result == 'success' &&
+      (
+        (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository) ||
+        (github.event_name == 'push' && github.ref == 'refs/heads/release/v2') ||
+        (github.event_name == 'workflow_dispatch' && inputs.operation == 'publish')
+      )
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+      packages: write
+      pull-requests: read
+    env:
+      PREVIEW_TAG: ${{ github.event_name == 'push' && 'v2' || format('pr-{0}', github.event.pull_request.number || inputs.pr_number) }}
+    steps:
+      - name: Log in to GHCR
+        if: "!env.ACT"
+        uses: docker/login-action@v4
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up Docker Buildx
+        if: "!env.ACT"
+        uses: docker/setup-buildx-action@v4
+
+      - name: Verify PR head before publication
+        if: github.event_name == 'pull_request'
+        uses: actions/github-script@v8
+        env:
+          EXPECTED_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        with:
+          script: |
+            const { data: pull } = await github.rest.pulls.get({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: context.payload.pull_request.number,
+            });
+            if (pull.state !== "open") {
+              core.setFailed(`PR #${pull.number} is ${pull.state}; refusing to publish its preview.`);
+              return;
+            }
+            if (pull.head.sha !== process.env.EXPECTED_HEAD_SHA) {
+              core.setFailed(`PR #${pull.number} moved from ${process.env.EXPECTED_HEAD_SHA} to ${pull.head.sha}.`);
+            }
+
+      - name: Publish preview manifest
+        if: "!env.ACT"
+        env:
+          AMD64_DIGEST: ${{ needs.preview-amd64.outputs.digest }}
+          ARM64_DIGEST: ${{ needs.preview-arm64.outputs.digest }}
+        run: |
+          tags=(-t "${PREVIEW_IMAGE}:${PREVIEW_TAG}")
+          docker buildx imagetools create "${tags[@]}" \
+            "${PREVIEW_IMAGE}@${AMD64_DIGEST}" \
+            "${PREVIEW_IMAGE}@${ARM64_DIGEST}"
+
+      - name: Verify preview manifest platforms
+        if: "!env.ACT"
+        run: |
+          tags=("${PREVIEW_TAG}")
+          for tag in "${tags[@]}"; do
+            image="${PREVIEW_IMAGE}:${tag}"
+            manifest="$(docker buildx imagetools inspect "$image" --raw)"
+            for architecture in amd64 arm64; do
+              jq --exit-status --arg architecture "$architecture" \
+                'any(.manifests[]; .platform.os == "linux" and .platform.architecture == $architecture)' \
+                <<<"$manifest" >/dev/null
+            done
+            docker buildx imagetools inspect "$image"
+          done
 
   cleanup:
     name: Clean up preview image
@@ -251,6 +441,14 @@ jobs:
               core.info(`No package version found with tag "${tag}"`);
               return;
             }
+            const targetTags = target.metadata?.container?.tags ?? [];
+            const extraTags = targetTags.filter((targetTag) => targetTag !== tag);
+            if (extraTags.length > 0) {
+              core.warning(
+                `Package version ${target.id} also carries tag(s) ${extraTags.map((targetTag) => `"${targetTag}"`).join(", ")}; refusing cleanup.`,
+              );
+              return;
+            }
             await github.rest.packages.deletePackageVersionForOrg({
               package_type: "container",
               package_name: packageName,

.github/workflows/crowdin-schedule-download.yml

@@ -22,7 +22,7 @@ jobs:
         uses: actions/create-github-app-token@v3
         with:
           private-key: ${{ secrets.CROWDIN_APP_PRIVATE_KEY }}
-          client-id: ${{ secrets.CROWDIN_APP_ID }}
+          client-id: ${{ vars.CROWDIN_CLIENT_ID }}
           permission-contents: write # required to commit to crowdin branch
           permission-pull-requests: write # required to create pull request
 

.github/workflows/database.yml

@@ -0,0 +1,100 @@
+name: Database migrations
+
+on:
+  workflow_call:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  NODE_ENV: development
+  CI: "true"
+  SKIP_ENV_VALIDATION: "true"
+  TURBO_TELEMETRY_DISABLED: "1"
+
+jobs:
+  changes:
+    runs-on: ubuntu-latest
+    outputs:
+      migrations: ${{ steps.select.outputs.migrations }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Select database checks
+        id: select
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.merge_group.base_sha || github.event.before }}
+        shell: bash
+        run: |
+          migrations=false
+          if [[ "$EVENT_NAME" != pull_request && "$EVENT_NAME" != merge_group && "$EVENT_NAME" != push ]] ||
+             [[ -z "$BASE_SHA" || "$BASE_SHA" =~ ^0+$ ]] ||
+             ! git cat-file -e "$BASE_SHA^{commit}" 2>/dev/null; then
+            migrations=true
+          else
+            changed_files=$(mktemp)
+            trap 'rm -f "$changed_files"' EXIT
+            comparison="$BASE_SHA...HEAD"
+            if [[ "$EVENT_NAME" = push ]]; then comparison="$BASE_SHA..HEAD"; fi
+            git diff --name-only -z "$comparison" > "$changed_files"
+            while IFS= read -r -d '' file; do
+              case "$file" in
+                packages/db/*|packages/core/src/infrastructure/db/*|packages/core/src/infrastructure/certificates/*|packages/auth/*|packages/api/src/router/onboard*|packages/api/src/router/test/onboard*|packages/onboarding/*|apps/nextjs/src/app/api/backup/*|apps/nextjs/src/app/*/init/*|Dockerfile|scripts/run.sh|scripts/entrypoint.sh|deployments/*|package.json|packages/core/package.json|packages/common/package.json|packages/definitions/package.json|packages/server-settings/package.json|packages/validation/package.json|mise.toml|pnpm-lock.yaml|pnpm-workspace.yaml|patches/*|vitest*|tooling/github/*|.github/workflows/database.yml|.github/workflows/ci.yml)
+                  migrations=true
+                  ;;
+              esac
+            done < "$changed_files"
+          fi
+          echo "migrations=$migrations" >> "$GITHUB_OUTPUT"
+
+  journals:
+    name: Migration journals
+    needs: changes
+    if: needs.changes.outputs.migrations == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: ./tooling/github/setup
+      - run: pnpm exec vitest run --project db-node packages/db/test/migration-journal.spec.ts
+
+  migrations:
+    name: SQLite and PostgreSQL migrations
+    needs: changes
+    if: needs.changes.outputs.migrations == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: ./tooling/github/setup
+      - name: Reject retired database configuration
+        run: pnpm exec vitest run --project dom packages/core/src/infrastructure/db/env.spec.ts
+      - run: pnpm exec vitest run --project db-node --project integration packages/db/test/sqlite-migration.spec.ts packages/db/test/postgresql-migration.spec.ts packages/db/proxy-reader.integration.spec.ts --maxWorkers 1
+
+  database-gate:
+    name: Database gate
+    needs: [changes, journals, migrations]
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: Require selected database checks
+        env:
+          CHANGES: ${{ needs.changes.result }}
+          JOURNALS: ${{ needs.journals.result }}
+          MIGRATIONS: ${{ needs.migrations.result }}
+          RUN_MIGRATIONS: ${{ needs.changes.outputs.migrations }}
+        run: |
+          test "$CHANGES" = success
+          test "$RUN_MIGRATIONS" = true || test "$RUN_MIGRATIONS" = false
+          if [ "$RUN_MIGRATIONS" = true ]; then
+            test "$JOURNALS" = success
+            test "$MIGRATIONS" = success
+          fi

.github/workflows/deployment-beta-release.yml

@@ -16,10 +16,10 @@ permissions:
 jobs:
   create-and-merge-pr:
     runs-on: ubuntu-latest
-    timeout-minutes: 2
+    timeout-minutes: 10
     steps:
       - name: Discord notification
-        if: ${{ github.event.inputs.send-notifications }}
+        if: ${{ inputs.send-notifications }}
         env:
           DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
         uses: Ilshidur/action-discord@0.4.0
@@ -37,11 +37,22 @@ jobs:
           branch: next
       - name: Create pull request
         id: create-pull-request
-        run: 'gh pr create --title "chore(release): release ${{ steps.semver.outputs.next }}-beta" --body "Detected change to be ``${{ steps.semver.outputs.bump }}``<br/>Bump version from ``${{ steps.semver.outputs.current }}`` to ``${{ steps.semver.outputs.next }}-beta``" --base beta --head next --label automerge'
+        run: |
+          pr_url="$(gh pr list --base beta --head next --state open --json url --jq '.[0].url // empty')"
+          if [[ -z "$pr_url" ]]; then
+            pr_url="$(gh pr create \
+              --title "chore(release): release ${{ steps.semver.outputs.next }}-beta" \
+              --body "Detected change to be ${{ steps.semver.outputs.bump }}<br/>Bump version from ${{ steps.semver.outputs.current }} to ${{ steps.semver.outputs.next }}-beta" \
+              --base beta \
+              --head next \
+              --label automerge)"
+          fi
+          echo "url=$pr_url" >> "$GITHUB_OUTPUT"
+          echo "pr_number=${pr_url##*/}" >> "$GITHUB_OUTPUT"
         env:
           GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
       - name: Discord notification
-        if: ${{ github.event.inputs.send-notifications }}
+        if: ${{ inputs.send-notifications }}
         env:
           DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
         uses: Ilshidur/action-discord@0.4.0
@@ -52,19 +63,19 @@ jobs:
         uses: actions/create-github-app-token@v3
         with:
           private-key: ${{ secrets.RENOVATE_APPROVE_PRIVATE_KEY }}
-          client-id: ${{ secrets.RENOVATE_APPROVE_APP_ID }}
+          client-id: ${{ vars.RENOVATE_APPROVE_CLIENT_ID }}
           permission-pull-requests: write
       - name: Approve PR
         env:
           GITHUB_TOKEN: ${{ steps.obtainApprovalToken.outputs.token }}
         run: |
-          gh pr review --approve --body "Automatically approved by GitHub Action"
+          gh pr review "${{ steps.create-pull-request.outputs.url }}" --approve --body "Automatically approved by GitHub Action"
       - name: Obtain token
         id: obtainMergeToken
         uses: actions/create-github-app-token@v3
         with:
           private-key: ${{ secrets.RENOVATE_MERGE_PRIVATE_KEY }}
-          client-id: ${{ secrets.RENOVATE_MERGE_APP_ID }}
+          client-id: ${{ vars.RENOVATE_MERGE_CLIENT_ID }}
           permission-contents: write # write to beta branch (due to merge)
           permission-pull-requests: write # merge pull request
       - id: automerge
@@ -82,21 +93,21 @@ jobs:
           MERGE_REQUIRED_APPROVALS: 0 # do not require approvals
 
       - name: Merged Discord notification
-        if: ${{ steps.automerge.outputs.mergeResult == 'merged' && github.event.inputs.send-notifications }}
+        if: ${{ steps.automerge.outputs.mergeResult == 'merged' && inputs.send-notifications }}
         env:
           DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
         uses: Ilshidur/action-discord@0.4.0
         with:
           args: "Merged PR ${{ steps.create-pull-request.outputs.url }} for release ${{ steps.semver.outputs.next }}-beta"
       - name: Major Bump Discord notification
-        if: ${{ steps.semver.outputs.bump == 'major' && github.event.inputs.send-notifications }}
+        if: ${{ steps.semver.outputs.bump == 'major' && inputs.send-notifications }}
         env:
           DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
         uses: Ilshidur/action-discord@0.4.0
         with:
           args: "The release PR must be manually merged because the next version is a major version: ${{ steps.create-pull-request.outputs.url }} for release ${{ steps.semver.outputs.next }}-beta"
       - name: Discord Fail Notification
-        if: failure() && github.event.inputs.send-notifications
+        if: ${{ failure() && inputs.send-notifications }}
         env:
           DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
         uses: Ilshidur/action-discord@0.4.0

.github/workflows/deployment-docker-image.yml

@@ -13,7 +13,7 @@ on:
         type: boolean
         required: false
         default: true
-        description: Send notifications
+        description: Send notifications when redeploying an existing release
 
 permissions:
   contents: write # Required to update package.json version
@@ -38,10 +38,11 @@ jobs:
       SKIP_RELEASE: ${{ github.event_name == 'workflow_dispatch' || github.ref_name == 'dev' || github.ref_name == 'next' }}
     outputs:
       version: ${{ steps.read-semver.outputs.version || steps.version-fallback.outputs.version }}
-      git_ref: ${{ steps.read-git-ref.outputs.ref || github.ref }}
+      git_ref: ${{ steps.read-git-ref.outputs.ref || steps.read-semver.outputs.version || github.ref }}
       skipped: ${{ env.SKIP_RELEASE }}
+      upstream_sync: ${{ steps.update-upstream.outcome }}
     steps:
-      - run: echo "Skipping release for workflow_dispatch event"
+      - run: echo "Manual dispatch redeploys the latest existing release without creating a new one"
         if: env.SKIP_RELEASE == 'true'
         # The below generated version fallback represents a normalized branch name, for example "feature/branch-name" -> "feature-branch-name"
       - run: echo "version="$(echo ${{github.ref_name}} | sed 's/[^a-zA-Z0-9\-]/-/g') >> "$GITHUB_OUTPUT"
@@ -54,12 +55,13 @@ jobs:
         uses: actions/create-github-app-token@v3
         with:
           private-key: ${{ secrets.RENOVATE_MERGE_PRIVATE_KEY }}
-          client-id: ${{ secrets.RENOVATE_MERGE_APP_ID }}
+          client-id: ${{ vars.RENOVATE_MERGE_CLIENT_ID }}
           permission-contents: write # required to commit package.json & changelog changes, merge them to dev / next and publish the release
 
       - uses: actions/checkout@v7
-        if: env.SKIP_RELEASE == 'false'
+        if: env.SKIP_RELEASE == 'false' || github.ref_name == 'main' || github.ref_name == 'beta'
         with:
+          fetch-depth: 0
           persist-credentials: false
       - uses: pnpm/action-setup@v6
         if: env.SKIP_RELEASE == 'false'
@@ -68,10 +70,29 @@ jobs:
         with:
           node-version: 24.18.0
           package-manager-cache: false
-      - name: Install dependencies
+      - name: Verify major release intent
         if: env.SKIP_RELEASE == 'false'
         run: |
-          pnpm install
+          latest_tag="$(git describe --tags --abbrev=0)"
+          latest_major="${latest_tag#v}"
+          latest_major="${latest_major%%.*}"
+          package_version="$(jq --raw-output '.version' package.json)"
+          package_major="${package_version%%.*}"
+
+          if (( package_major <= latest_major )); then
+            exit 0
+          fi
+
+          if git log --format='%s%n%b' "${latest_tag}..HEAD" \
+            | grep --extended-regexp --quiet '(^[[:alnum:]-]+(\([^)]*\))?!:)|(^BREAKING[ -]CHANGE:)'; then
+            exit 0
+          fi
+
+          echo "::error::package.json declares ${package_version}, but commits since ${latest_tag} contain no breaking-change signal. Use a conventional ! commit or BREAKING CHANGE footer so Semantic Release creates the intended major version."
+          exit 1
+      - name: Install dependencies
+        if: env.SKIP_RELEASE == 'false'
+        run: pnpm install --frozen-lockfile
       - name: Run Semantic Release
         if: env.SKIP_RELEASE == 'false'
         env:
@@ -95,8 +116,10 @@ jobs:
         run: |
           echo "ref=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
       - name: Update dev / next branch
+        id: update-upstream
         if: env.SKIP_RELEASE == 'false'
-        continue-on-error: true # Prevent pipeline from failing when merge fails
+        # Finish publishing the already-created release, then fail in the publish job if synchronization did not work.
+        continue-on-error: true
         env:
           GITHUB_TOKEN: ${{ steps.obtainToken.outputs.token }}
           UPSTREAM_BRANCH: ${{ github.ref_name == 'main' && 'dev' || 'next' }}
@@ -203,9 +226,14 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
+      - uses: actions/checkout@v7
+        if: needs.release.outputs.skipped == 'false'
+        with:
+          ref: ${{ needs.release.outputs.git_ref }}
+          persist-credentials: false
       - name: Extract amd64
         if: needs.release.outputs.skipped == 'false'
-        uses: homarr-labs/homarr/.github/actions/extract-build-artifact@dev
+        uses: ./.github/actions/extract-build-artifact
         with:
           digest: "${{ env.GHCR_REPO }}@${{ needs.build-amd64.outputs.digest }}"
           architecture: amd64
@@ -219,9 +247,14 @@ jobs:
     runs-on: ubuntu-24.04-arm
     timeout-minutes: 5
     steps:
+      - uses: actions/checkout@v7
+        if: needs.release.outputs.skipped == 'false'
+        with:
+          ref: ${{ needs.release.outputs.git_ref }}
+          persist-credentials: false
       - name: Extract arm64
         if: needs.release.outputs.skipped == 'false'
-        uses: homarr-labs/homarr/.github/actions/extract-build-artifact@dev
+        uses: ./.github/actions/extract-build-artifact
         with:
           digest: "${{ env.GHCR_REPO }}@${{ needs.build-arm64.outputs.digest }}"
           architecture: arm64
@@ -244,7 +277,7 @@ jobs:
         uses: actions/create-github-app-token@v3
         with:
           private-key: ${{ secrets.RENOVATE_MERGE_PRIVATE_KEY }}
-          client-id: ${{ secrets.RENOVATE_MERGE_APP_ID }}
+          client-id: ${{ vars.RENOVATE_MERGE_CLIENT_ID }}
           permission-contents: write # required to publish the release
 
       - name: Log in to the Container registry
@@ -281,9 +314,30 @@ jobs:
         run: |
           gh release edit --repo ${{ github.repository }} ${{ needs.release.outputs.version }} --draft=false
 
+      - name: Verify dev / next synchronization
+        if: needs.release.outputs.skipped == 'false' && needs.release.outputs.upstream_sync != 'success'
+        run: |
+          echo "::error::The released commit was not synchronized back to the upstream development branch."
+          exit 1
+
       - name: Discord notification
+        if: github.event_name != 'workflow_dispatch' || inputs['send-notifications']
         env:
           DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
         uses: Ilshidur/action-discord@0.4.0
         with:
           args: "Successfully deployed images for branch **${{ github.ref_name }}**. Tagged as **${{env.NEXT_VERSION}}**."
+
+  notify-failure:
+    name: Notify deployment failure
+    if: ${{ always() && (failure() || cancelled()) && (github.event_name != 'workflow_dispatch' || inputs['send-notifications']) }}
+    needs: [release, build-amd64, build-arm64, extract-asset-amd64, extract-asset-arm64, publish]
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    steps:
+      - name: Discord failure notification
+        env:
+          DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
+        uses: Ilshidur/action-discord@0.4.0
+        with:
+          args: "The deployment for branch **${{ github.ref_name }}** failed or was cancelled: [run ${{ github.run_number }}](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})"

.github/workflows/deployment-docs.yml

@@ -37,12 +37,17 @@ jobs:
         run: pnpm turbo build --filter=@homarr/docs
         env:
           CI: "true"
+      - name: Validate exported links and search
+        run: |
+          pnpm --filter @homarr/docs validate:links
+          pnpm --filter @homarr/docs verify:search
+          pnpm --filter @homarr/docs verify:seo
       - name: Setup Pages
         uses: actions/configure-pages@v6
       - name: Upload pages artifact
         uses: actions/upload-pages-artifact@v5
         with:
-          path: "apps/docs/build"
+          path: "apps/docs/out"
 
   deploy:
     runs-on: ubuntu-latest

.github/workflows/deployment-weekly-release.yml

@@ -19,10 +19,10 @@ permissions:
 jobs:
   create-and-merge-pr:
     runs-on: ubuntu-latest
-    timeout-minutes: 2
+    timeout-minutes: 10
     steps:
       - name: Discord notification
-        if: ${{ github.event.inputs.send-notifications }}
+        if: ${{ github.event_name == 'schedule' || inputs.send-notifications }}
         env:
           DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
         uses: Ilshidur/action-discord@0.4.0
@@ -38,13 +38,30 @@ jobs:
         with:
           token: ${{ github.token }}
           branch: dev
+          noNewCommitBehavior: silent
+          noVersionBumpBehavior: silent
+      - name: No release needed
+        if: ${{ steps.semver.outputs.bump == '' || steps.semver.outputs.bump == 'none' }}
+        run: echo "No release-worthy commits were found since ${{ steps.semver.outputs.current }}." >> "$GITHUB_STEP_SUMMARY"
       - name: Create pull request
         id: create-pull-request
-        run: 'gh pr create --title "chore(release): automatic release ${{ steps.semver.outputs.next }}" --body "**This is an automatic release**.<br/>Manual action may be required for major bumps.<br/>Detected change to be ``${{ steps.semver.outputs.bump }}``<br/>Bump version from ``${{ steps.semver.outputs.current }}`` to ``${{ steps.semver.outputs.next }}``" --base main --head dev --label automerge'
+        if: ${{ steps.semver.outputs.bump != '' && steps.semver.outputs.bump != 'none' }}
+        run: |
+          pr_url="$(gh pr list --base main --head dev --state open --json url --jq '.[0].url // empty')"
+          if [[ -z "$pr_url" ]]; then
+            pr_url="$(gh pr create \
+              --title "chore(release): automatic release ${{ steps.semver.outputs.next }}" \
+              --body "**This is an automatic release**.<br/>Manual action may be required for major bumps.<br/>Detected change to be ``${{ steps.semver.outputs.bump }}``<br/>Bump version from ``${{ steps.semver.outputs.current }}`` to ``${{ steps.semver.outputs.next }}``" \
+              --base main \
+              --head dev \
+              --label automerge)"
+          fi
+          echo "url=$pr_url" >> "$GITHUB_OUTPUT"
+          echo "pr_number=${pr_url##*/}" >> "$GITHUB_OUTPUT"
         env:
           GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
       - name: Discord notification
-        if: ${{ github.event.inputs.send-notifications }}
+        if: ${{ steps.create-pull-request.outcome == 'success' && (github.event_name == 'schedule' || inputs.send-notifications) }}
         env:
           DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
         uses: Ilshidur/action-discord@0.4.0
@@ -52,26 +69,29 @@ jobs:
           args: "Created a release PR ${{ steps.create-pull-request.outputs.url }} for version ${{ steps.semver.outputs.next }} (new behaviour: ${{ steps.semver.outputs.bump }})"
       - name: Obtain token
         id: obtainApprovalToken
+        if: ${{ steps.create-pull-request.outcome == 'success' }}
         uses: actions/create-github-app-token@v3
         with:
           private-key: ${{ secrets.RENOVATE_APPROVE_PRIVATE_KEY }}
-          client-id: ${{ secrets.RENOVATE_APPROVE_APP_ID }}
+          client-id: ${{ vars.RENOVATE_APPROVE_CLIENT_ID }}
           permission-pull-requests: write
       - name: Approve PR
+        if: ${{ steps.create-pull-request.outcome == 'success' }}
         env:
           GITHUB_TOKEN: ${{ steps.obtainApprovalToken.outputs.token }}
         run: |
-          gh pr review --approve --body "Automatically approved by GitHub Action"
+          gh pr review "${{ steps.create-pull-request.outputs.url }}" --approve --body "Automatically approved by GitHub Action"
       - name: Obtain token
         id: obtainMergeToken
+        if: ${{ steps.create-pull-request.outcome == 'success' }}
         uses: actions/create-github-app-token@v3
         with:
           private-key: ${{ secrets.RENOVATE_MERGE_PRIVATE_KEY }}
-          client-id: ${{ secrets.RENOVATE_MERGE_APP_ID }}
+          client-id: ${{ vars.RENOVATE_MERGE_CLIENT_ID }}
           permission-contents: write # write to main branch (due to merge)
           permission-pull-requests: write # merge pull request
       - id: automerge
-        if: ${{ steps.semver.outputs.bump != 'major' }}
+        if: ${{ steps.create-pull-request.outcome == 'success' && steps.semver.outputs.bump != 'major' }}
         name: automerge
         uses: "pascalgn/automerge-action@v0.16.4"
         env:
@@ -85,21 +105,21 @@ jobs:
           MERGE_REQUIRED_APPROVALS: 0 # do not require approvals
 
       - name: Merged Discord notification
-        if: ${{ steps.automerge.outputs.mergeResult == 'merged' && github.event.inputs.send-notifications }}
+        if: ${{ steps.automerge.outputs.mergeResult == 'merged' && (github.event_name == 'schedule' || inputs.send-notifications) }}
         env:
           DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
         uses: Ilshidur/action-discord@0.4.0
         with:
           args: "Merged PR ${{ steps.create-pull-request.outputs.url }} for release ${{ steps.semver.outputs.next }}"
       - name: Major Bump Discord notification
-        if: ${{ steps.semver.outputs.bump == 'major' && github.event.inputs.send-notifications }}
+        if: ${{ steps.semver.outputs.bump == 'major' && (github.event_name == 'schedule' || inputs.send-notifications) }}
         env:
           DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
         uses: Ilshidur/action-discord@0.4.0
         with:
           args: "The release PR must be manually merged because the next version is a major version: ${{ steps.create-pull-request.outputs.url }} for release ${{ steps.semver.outputs.next }}"
       - name: Discord Fail Notification
-        if: failure() && github.event.inputs.send-notifications
+        if: ${{ failure() && (github.event_name == 'schedule' || inputs.send-notifications) }}
         env:
           DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
         uses: Ilshidur/action-discord@0.4.0

.github/workflows/docs-algolia-recrawl.yml

@@ -1,58 +0,0 @@
-name: "[Docs] Algolia Recrawl"
-
-on:
-  workflow_run:
-    workflows: ["[Deployment] Documentation"]
-    types: [completed]
-    branches: [dev]
-  workflow_dispatch:
-
-permissions:
-  contents: read
-
-jobs:
-  recrawl:
-    if: >-
-      ${{
-        (github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.event != 'pull_request')
-        || github.event_name == 'workflow_dispatch'
-      }}
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    steps:
-      - uses: actions/checkout@v7
-
-      - name: Setup
-        uses: ./tooling/github/setup
-
-      - name: Check Algolia crawler secrets
-        run: |
-          missing=0
-          for secret in ALGOLIA_CRAWLER_ID ALGOLIA_CRAWLER_USER_ID ALGOLIA_CRAWLER_API_KEY; do
-            if [ -z "${!secret}" ]; then
-              echo "::warning::Missing repository secret: $secret"
-              missing=1
-            fi
-          done
-          if [ "$missing" -eq 1 ]; then
-            echo "Add crawler secrets to enable automatic recrawls."
-            exit 1
-          fi
-        env:
-          ALGOLIA_CRAWLER_ID: ${{ secrets.ALGOLIA_CRAWLER_ID }}
-          ALGOLIA_CRAWLER_USER_ID: ${{ secrets.ALGOLIA_CRAWLER_USER_ID }}
-          ALGOLIA_CRAWLER_API_KEY: ${{ secrets.ALGOLIA_CRAWLER_API_KEY }}
-
-      - name: Wait for GitHub Pages to serve the new deployment
-        run: sleep 60
-
-      - name: Trigger Algolia DocSearch recrawl
-        uses: cssnr/algolia-crawler-action@v2
-        with:
-          crawler_id: ${{ secrets.ALGOLIA_CRAWLER_ID }}
-          crawler_user_id: ${{ secrets.ALGOLIA_CRAWLER_USER_ID }}
-          crawler_api_key: ${{ secrets.ALGOLIA_CRAWLER_API_KEY }}
-
-      - name: Verify search index
-        working-directory: apps/docs
-        run: pnpm verify:search

.github/workflows/docs-update-contributors.yml

@@ -33,7 +33,7 @@ jobs:
       - name: Commit updated contributors
         uses: EndBug/add-and-commit@v10
         with:
-          add: "apps/docs/static"
+          add: "apps/docs/public"
           default_author: github_actor
           message: "chore(docs): update contributors"
           push: true

.github/workflows/docs-update-openapi.yml

@@ -26,41 +26,13 @@ jobs:
       - name: Copy env
         run: cp .env.example .env
 
-      - name: Start dev server
-        run: pnpm --filter @homarr/nextjs dev &
-        env:
-          TURBO_TELEMETRY_DISABLED: 1
-          DISABLE_TELEMETRY: 1
-
-      - name: Wait for server and fetch spec
-        run: |
-          set -euo pipefail
-          for i in $(seq 1 30); do
-            if curl -fsS http://localhost:3000/api/openapi -o /tmp/openapi.json 2>/dev/null; then
-              echo "Server is up, spec fetched"
-              break
-            fi
-            echo "Waiting for server... ($i/30)"
-            sleep 3
-          done
-
-          if [ ! -f /tmp/openapi.json ]; then
-            echo "::error::Server failed to start within timeout"
-            exit 1
-          fi
-
-          jq -e '.openapi and .paths' /tmp/openapi.json > /dev/null || {
-            echo "::error::Fetched file is not a valid OpenAPI spec"
-            exit 1
-          }
-
-          cp /tmp/openapi.json apps/docs/static/api/open-api-schema.json
-          echo "OpenAPI spec updated ($(jq '.paths | length' /tmp/openapi.json) paths)"
+      - name: Generate and validate OpenAPI spec
+        run: pnpm scripts:update-openapi
 
       - name: Commit updated spec
         uses: EndBug/add-and-commit@v10
         with:
-          add: "apps/docs/static/api/"
+          add: "apps/docs/public/api/"
           default_author: github_actor
           message: "chore(docs): update OpenAPI spec"
           push: true

.github/workflows/on-pr-prebuilt-debian-validate.yml

@@ -5,7 +5,7 @@ permissions:
 
 on:
   pull_request:
-    branches: ["*"]
+    branches: ["**"]
     paths: [".github/actions/prebuilt-debian/**", "deployments/prebuilt-debian/**"]
 
 jobs:

.github/workflows/on-pr-renovate-validate.yml

@@ -5,7 +5,7 @@ permissions:
 
 on:
   pull_request:
-    branches: ["*"]
+    branches: ["**"]
     paths: [".github/renovate.json5"]
 
 jobs:

.github/workflows/on-release.yml

@@ -5,39 +5,6 @@ on:
     types: [released]
 
 jobs:
-  trigger-docs-release:
-    name: Trigger Documentation Release
-    runs-on: ubuntu-latest
-    timeout-minutes: 2
-    steps:
-      - name: Obtain token
-        id: obtainToken
-        uses: actions/create-github-app-token@v3
-        with:
-          private-key: ${{ secrets.HOMARR_DOCS_RELEASE_APP_PRIVATE_KEY }}
-          client-id: ${{ vars.HOMARR_DOCS_RELEASE_APP_ID }}
-          owner: homarr-labs
-          repositories: |
-            documentation
-          permission-contents: write # required to dispatch repository workflow
-      - name: Trigger documentation release
-        env:
-          GITHUB_TOKEN: ${{ steps.obtainToken.outputs.token }}
-          SOURCE_TAG: ${{ github.event.release.tag_name }}
-        run: |
-          curl -X POST \
-            -H "Authorization: token $GITHUB_TOKEN" \
-            -H "Accept: application/vnd.github+json" \
-            https://api.github.com/repos/homarr-labs/documentation/dispatches \
-            -d @- <<EOF
-          {
-            "event_type": "trigger-release",
-            "client_payload": {
-              "tag": "${SOURCE_TAG}"
-            }
-          }
-          EOF
-
   update-bug-report-template:
     name: Update Bug Report Template
     runs-on: ubuntu-latest
@@ -48,7 +15,7 @@ jobs:
         uses: actions/create-github-app-token@v3
         with:
           private-key: ${{ secrets.RENOVATE_MERGE_PRIVATE_KEY }}
-          client-id: ${{ secrets.RENOVATE_MERGE_APP_ID }}
+          client-id: ${{ vars.RENOVATE_MERGE_CLIENT_ID }}
           permission-contents: write # required to commit to branch
           permission-pull-requests: write # required to create pr & enable automerge
       - name: Checkout code

.github/workflows/skip-renovate-stability-days.yml

@@ -1,5 +1,6 @@
 permissions:
   statuses: write
+  contents: read
 
 on:
   pull_request:
@@ -16,12 +17,20 @@ jobs:
         env:
           GH_TOKEN: ${{secrets.GITHUB_TOKEN}}
         run: |
-          gh api \
-          --method POST \
-          -H "Accept: application/vnd.github+json" \
-          -H "X-GitHub-Api-Version: 2022-11-28" \
-          /repos/${{github.repository}}/statuses/${{github.event.pull_request.head.sha}} \
-          -f 'state=success' \
-          -f 'target_url=https://docs.renovatebot.com/configuration-options#minimumreleaseage' \
-          -f 'description=Skipped for non renovate branches' \
-          -f 'context=renovate/stability-days'
+          for attempt in 1 2 3 4 5; do
+            if gh api \
+              --method POST \
+              -H "Accept: application/vnd.github+json" \
+              -H "X-GitHub-Api-Version: 2022-11-28" \
+              /repos/${{github.repository}}/statuses/${{github.event.pull_request.head.sha}} \
+              -f 'state=success' \
+              -f 'target_url=https://docs.renovatebot.com/configuration-options#minimumreleaseage' \
+              -f 'description=Skipped for non renovate branches' \
+              -f 'context=renovate/stability-days' \
+              --silent; then
+              exit 0
+            fi
+            echo "status POST failed (attempt $attempt/5), retrying in 5s"
+            sleep 5
+          done
+          exit 1

.github/workflows/update-contributors.yml

@@ -15,16 +15,13 @@ jobs:
   update-contributors:
     runs-on: ubuntu-latest
     timeout-minutes: 2
-    strategy:
-      matrix:
-        node-version: [22]
     steps:
       - name: Obtain token
         id: obtainToken
         uses: actions/create-github-app-token@v3
         with:
           private-key: ${{ secrets.HOMARR_UPDATE_CONTRIBUTORS_PRIVATE_KEY }}
-          client-id: ${{ vars.HOMARR_UPDATE_CONTRIBUTORS_APP_ID }}
+          client-id: ${{ vars.HOMARR_UPDATE_CONTRIBUTORS_CLIENT_ID }}
           permission-contents: write # required to commit to branch
           permission-pull-requests: write # required to create pr & enable automerge
 
@@ -34,10 +31,10 @@ jobs:
           GITHUB_TOKEN: ${{ steps.obtainToken.outputs.token }}
 
       - uses: pnpm/action-setup@v6
-      - name: Use Node.js ${{ matrix.node-version }}
+      - name: Use Node.js
         uses: actions/setup-node@v6
         with:
-          node-version: ${{ matrix.node-version }}
+          node-version: 24.18.0
           cache: "pnpm"
 
       - name: Run update script

.github/workflows/update-integration-list.yml

@@ -24,7 +24,7 @@ jobs:
         uses: actions/create-github-app-token@v3
         with:
           private-key: ${{ secrets.HOMARR_UPDATE_CONTRIBUTORS_PRIVATE_KEY }}
-          client-id: ${{ vars.HOMARR_UPDATE_CONTRIBUTORS_APP_ID }}
+          client-id: ${{ vars.HOMARR_UPDATE_CONTRIBUTORS_CLIENT_ID }}
           permission-contents: write # required to commit to branch
           permission-pull-requests: write # required to create pr & enable automerge
       - name: Checkout code

.github/workflows/validate-docs.yml

@@ -0,0 +1,54 @@
+name: Validate documentation
+
+on:
+  pull_request:
+    paths:
+      - "apps/docs/**"
+      - "apps/nextjs/src/app/api/**"
+      - "packages/definitions/src/**"
+      - "packages/widgets/src/**"
+      - "packages/custom-widgets/src/**"
+      - "packages/ui/src/**"
+      - "packages/workshop/src/**"
+      - "packages/api/src/**"
+      - "packages/auth/src/**"
+      - "packages/integrations/src/**"
+      - "tooling/**"
+      - "pnpm-lock.yaml"
+      - "package.json"
+      - "pnpm-workspace.yaml"
+      - "turbo.json"
+      - ".github/workflows/deployment-docs.yml"
+      - ".github/workflows/validate-docs.yml"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: validate-docs-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  docs:
+    name: Build and validate docs
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      SKIP_ENV_VALIDATION: true
+    steps:
+      - uses: actions/checkout@v7
+      - name: Setup
+        uses: ./tooling/github/setup
+      - name: Validate the published API schema against the application
+        run: pnpm check:openapi
+      - name: Validate browser access and API schema rendering
+        run: pnpm exec vitest run 'apps/nextjs/src/app/api/[...trpc]/route.spec.ts' apps/docs/src/lib/openapi.spec.ts
+      - name: Build docs
+        run: pnpm --filter @homarr/docs build
+        env:
+          CI: "true"
+      - name: Validate exported links, search, and metadata
+        run: |
+          pnpm --filter @homarr/docs validate:links
+          pnpm --filter @homarr/docs verify:search
+          pnpm --filter @homarr/docs verify:seo

.github/workflows/workshop.yml

@@ -0,0 +1,200 @@
+name: Workshop
+
+on:
+  pull_request:
+    paths:
+      - ".github/workflows/workshop.yml"
+      - "apps/workshop/**"
+      - "apps/docs/**"
+      - "packages/common/**"
+      - "packages/core/**"
+      - "packages/custom-widgets/**"
+      - "packages/definitions/**"
+      - "packages/db/**"
+      - "packages/server-settings/**"
+      - "packages/settings/**"
+      - "packages/translation/**"
+      - "packages/ui/**"
+      - "packages/validation/**"
+      - "packages/workshop/**"
+      - "tooling/typescript/**"
+      - "patches/**"
+      - "package.json"
+      - "pnpm-lock.yaml"
+      - "pnpm-workspace.yaml"
+      - "turbo.json"
+      - ".npmrc"
+  push:
+    branches: [dev, v2, release/v2, main]
+    paths:
+      - ".github/workflows/workshop.yml"
+      - "apps/workshop/**"
+      - "apps/docs/**"
+      - "packages/common/**"
+      - "packages/core/**"
+      - "packages/custom-widgets/**"
+      - "packages/definitions/**"
+      - "packages/db/**"
+      - "packages/server-settings/**"
+      - "packages/settings/**"
+      - "packages/translation/**"
+      - "packages/ui/**"
+      - "packages/validation/**"
+      - "packages/workshop/**"
+      - "tooling/typescript/**"
+      - "patches/**"
+      - "package.json"
+      - "pnpm-lock.yaml"
+      - "pnpm-workspace.yaml"
+      - "turbo.json"
+      - ".npmrc"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ (github.ref_name == 'v2' || github.ref_name == 'release/v2') && 'v2-preview' || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  production-smoke:
+    if: github.event_name == 'pull_request'
+    name: Production image smoke (${{ matrix.arch }})
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - arch: amd64
+            runner: ubuntu-24.04
+          - arch: arm64
+            runner: ubuntu-24.04-arm
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24.18.0
+      - name: Build and exercise the combined production image
+        run: sh apps/workshop/test-image.sh
+
+  validate:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v7
+      - run: docker compose --env-file apps/workshop/.env.staging.example -f apps/workshop/docker-compose.staging.yml config --quiet
+
+  publish-amd64:
+    if: github.event_name == 'push' && (github.ref_name == 'v2' || github.ref_name == 'release/v2' || github.ref_name == 'main')
+    needs: validate
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    permissions:
+      contents: read
+      packages: write
+    outputs:
+      digest: ${{ steps.build.outputs.digest }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: docker/setup-buildx-action@v4
+      - uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - uses: docker/build-push-action@v7
+        id: build
+        with:
+          context: .
+          file: apps/workshop/Dockerfile
+          target: production
+          platforms: linux/amd64
+          outputs: type=image,"name=ghcr.io/homarr-labs/workshop",push-by-digest=true,name-canonical=true,push=true
+          cache-from: type=gha,scope=workshop-linux-amd64
+          cache-to: type=gha,scope=workshop-linux-amd64,mode=max
+
+  publish-arm64:
+    if: github.event_name == 'push' && (github.ref_name == 'v2' || github.ref_name == 'release/v2' || github.ref_name == 'main')
+    needs: validate
+    runs-on: ubuntu-24.04-arm
+    timeout-minutes: 20
+    permissions:
+      contents: read
+      packages: write
+    outputs:
+      digest: ${{ steps.build.outputs.digest }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: docker/setup-buildx-action@v4
+      - uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - uses: docker/build-push-action@v7
+        id: build
+        with:
+          context: .
+          file: apps/workshop/Dockerfile
+          target: production
+          platforms: linux/arm64
+          outputs: type=image,"name=ghcr.io/homarr-labs/workshop",push-by-digest=true,name-canonical=true,push=true
+          cache-from: type=gha,scope=workshop-linux-arm64
+          cache-to: type=gha,scope=workshop-linux-arm64,mode=max
+
+  publish:
+    if: github.event_name == 'push' && (github.ref_name == 'v2' || github.ref_name == 'release/v2' || github.ref_name == 'main')
+    needs: [publish-amd64, publish-arm64]
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    permissions:
+      contents: read
+      packages: write
+    env:
+      WORKSHOP_IMAGE: ghcr.io/homarr-labs/workshop
+    steps:
+      - uses: docker/setup-buildx-action@v4
+      - uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Verify branch head before publication
+        uses: actions/github-script@v8
+        with:
+          script: |
+            const branchName = context.ref.replace("refs/heads/", "");
+            const { data: branch } = await github.rest.repos.getBranch({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              branch: branchName,
+            });
+            if (branch.commit.sha !== context.sha) {
+              core.setFailed(`Branch ${branchName} moved from ${context.sha} to ${branch.commit.sha}.`);
+            }
+      - name: Publish multi-platform image
+        env:
+          AMD64_DIGEST: ${{ needs.publish-amd64.outputs.digest }}
+          ARM64_DIGEST: ${{ needs.publish-arm64.outputs.digest }}
+        run: |
+          tags=(-t "${WORKSHOP_IMAGE}:sha-${GITHUB_SHA}")
+          if [[ "${GITHUB_REF_NAME}" == "v2" || "${GITHUB_REF_NAME}" == "release/v2" ]]; then
+            tags+=(-t "${WORKSHOP_IMAGE}:v2")
+          fi
+          if [[ "${GITHUB_REF_NAME}" == "main" ]]; then
+            tags+=(-t "${WORKSHOP_IMAGE}:latest")
+          fi
+          docker buildx imagetools create "${tags[@]}" \
+            "${WORKSHOP_IMAGE}@${AMD64_DIGEST}" \
+            "${WORKSHOP_IMAGE}@${ARM64_DIGEST}"
+      - name: Verify multi-platform image
+        run: |
+          image="${WORKSHOP_IMAGE}:sha-${GITHUB_SHA}"
+          manifest="$(docker buildx imagetools inspect "$image" --raw)"
+          for architecture in amd64 arm64; do
+            jq --exit-status --arg architecture "$architecture" \
+              'any(.manifests[]; .platform.os == "linux" and .platform.architecture == $architecture)' \
+              <<<"$manifest" >/dev/null
+          done
+          docker buildx imagetools inspect "$image"