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>
2026-10-02 21:00:14 +02:00
1 parent 3a53bb77aa
commit fcd7c979df
@@ -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 --
@@ -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
@@ -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
@@ -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,
@@ -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

@@ -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
@@ -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
@@ -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 }})"
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -5,7 +5,7 @@ permissions:

 on:
  pull_request:
-    branches: ["*"]
+    branches: ["**"]
    paths: [".github/actions/prebuilt-debian/**", "deployments/prebuilt-debian/**"]

 jobs:
@@ -5,7 +5,7 @@ permissions:

 on:
  pull_request:
-    branches: ["*"]
+    branches: ["**"]
    paths: [".github/renovate.json5"]

 jobs:
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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"