ci: only read the Depends on lines, and let the label be the gate

Documents the variable added in https://gitea.com/gitea/runner/pulls/1204 and drops the `valid_volumes` requirement for `bind_workdir`, gone since https://gitea.com/gitea/runner/pulls/1203.

Assisted by Claude (Fable 5.1).

---------

Co-authored-by: Lunny Xiao <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/535
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: silverwind <[email protected]>

.gitea/workflows/depends_upstream.yaml

@@ -0,0 +1,48 @@
+# The status check context of this job is "checks / depends-upstream
+# (pull_request)", which the required status check `checks / *` of the protected
+# main branch matches, so a pull request waiting for gitea cannot be merged.
+# It is a workflow of its own so that a label change does not cancel the build
+# and the preview deployment of the `checks` workflow in test.yaml.
+#
+# The check script comes from the pull request, like the workflow file itself:
+# `pull_request` runs both from the head, so taking the script from the base
+# branch would not gain anything and would leave this workflow unable to run on
+# the pull request that adds it.
+name: checks
+
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - edited
+      - labeled
+      - unlabeled
+
+concurrency:
+  group: depends-upstream-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  depends-upstream:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - name: check the upstream dependencies
+        env:
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          # optional, only lifts the rate limit of the unauthenticated github api
+          GITHUB_COM_TOKEN: ${{ secrets.GITHUB_COM_TOKEN }}
+        run: |
+          set -euo pipefail
+
+          # read the description and the labels from the api instead of the
+          # event context, so nothing from a pull request body is expanded into
+          # this script
+          api="${GITHUB_API_URL:-$GITHUB_SERVER_URL/api/v1}/repos/$GITHUB_REPOSITORY"
+          curl --silent --show-error --fail --output pull.json "$api/pulls/$PR_NUMBER"
+
+          ./scripts/check-upstream-deps.sh pull.json

.gitea/workflows/test.yaml

@@ -94,7 +94,7 @@ jobs:
             body="$(printf '%s Preview: %s\n' "$marker" "$PREVIEW_URL")"
           fi
 
-          jq -n --arg body "$body" '{body: $body}' > patch.json
+          printf '%s' "$body" | jq -Rs '{body: .}' > patch.json
           curl --silent --show-error --fail --output /dev/null \
             -X PATCH "$api" \
             -H "Authorization: token $DEPLOY_TOKEN" \

.gitea/workflows/unlabel_depends_upstream.yaml

@@ -0,0 +1,29 @@
+name: unlabel merged upstream dependencies
+
+on:
+  schedule:
+    - cron: '15 */6 * * *' # every 6 hours, quarter past
+  workflow_dispatch:
+
+jobs:
+  unlabel:
+    if: github.repository == 'gitea/docs'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - name: drop the label from the pull requests upstream caught up with
+        env:
+          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
+          GITHUB_COM_TOKEN: ${{ secrets.GITHUB_COM_TOKEN }}
+        run: |
+          set -euo pipefail
+
+          if [ -z "${DEPLOY_TOKEN:-}" ]; then
+            echo "secrets.DEPLOY_TOKEN is missing, cannot remove the label"
+            exit 1
+          fi
+
+          export GITEA_API="${GITHUB_API_URL:-$GITHUB_SERVER_URL/api/v1}/repos/$GITHUB_REPOSITORY"
+          ./scripts/unlabel-upstream-deps.sh

README.md

@@ -48,6 +48,38 @@ The order of the top level sidebar groups comes from `sidebars.js` (and
 `versioned_sidebars/` for released versions), the label and order of every other
 group from the `_category_.json` of its directory.
 
+### Documenting an unreleased feature
+
+A page that describes a gitea change which is not merged yet must wait for it,
+otherwise the site documents something no release has. Say so in the description
+of the pull request, on a line of its own, and add the `depends-on-upstream`
+label:
+
+```
+Depends on: gitea#35851
+```
+
+The label is what blocks the merge: the `depends-upstream` check fails while it
+is set, unless every dependency is verified as merged, and `main` requires the
+`checks` contexts. The check reads the `Depends on:` lines (`gitea#<id>` or the
+full pull request url, several lines are allowed) to find out what to wait for,
+so the label needs at least one of them. A `gitea#<id>` mentioned anywhere else
+in the description is ignored.
+
+Without the label, a dependency that the check finds unmerged still fails it, so
+forgetting the label does not let an unreleased feature through.
+
+The `unlabel merged upstream dependencies` job runs every 6 hours, removes the
+label once every referenced pull request is merged and comments on the pull
+request, which reruns the check. `scripts/check-upstream-deps.sh` is the check
+itself and can be run locally against the json of a pull request.
+
+The check asks the github api whether a pull request is merged, and the runners
+share the 60 requests per hour it allows without authentication. The optional
+`GITHUB_COM_TOKEN` secret (a token without scopes is enough) raises that limit;
+without it an unverifiable dependency only fails the check when the label is
+set.
+
 ## Cutting a version
 
 ```shell

docs/usage/actions/variables.md

@@ -15,6 +15,7 @@ These environment variables are set automatically in every workflow run and can
 | `CI` | Always set to `true`. | `true` |
 | `GITEA_ACTIONS` | Always set to `true`. Useful to distinguish Gitea Actions from other CI systems. | `true` |
 | `GITEA_ACTIONS_RUNNER_VERSION` | The version of the runner executing the workflow. | `1.0.8` |
+| `GITEA_DOCKER_WORKSPACE` | The workspace path as the Docker daemon sees it, for bind mounts into containers a job starts, e.g. `${GITEA_DOCKER_WORKSPACE:-.}/data:/app/data` in a compose file. Only set for jobs running in a container. | `/var/lib/docker/volumes/GITEA-ACTIONS-TASK-42_***/_data` |
 | `GITEA_ENV`<br/>`GITHUB_ENV` | Path to the file that sets environment variables for subsequent steps. | `/home/runner/work/_temp/_runner_file_commands/set_env_***` |
 | `GITEA_OUTPUT`<br/>`GITHUB_OUTPUT` | Path to the file that sets step output parameters. | `/home/runner/work/_temp/_runner_file_commands/set_output_***` |
 | `GITEA_PATH`<br/>`GITHUB_PATH` | Path to the file that adds system `PATH` entries for subsequent steps. | `/home/runner/work/_temp/_runner_file_commands/add_path_***` |

package.json

@@ -13,5 +13,5 @@
   "engines": {
     "node": ">=22"
   },
-  "packageManager": "pnpm@11.22.0"
+  "packageManager": "pnpm@12.2.1"
 }

pnpm-workspace.yaml

@@ -7,5 +7,4 @@ dedupePeerDependents: false
 updateNotifier: false
 ignoreScripts: true
 minimumReleaseAge: 0
-confirmModulesPurge: false
 verifyDepsBeforeRun: false

runner-docs/configuration.md

@@ -106,7 +106,7 @@ Applies to jobs that run in containers.
 | `force_rebuild` | `false` | rebuild local action images even when present. |
 | `require_docker` | `false` | always require a reachable daemon, even for host-only labels. |
 | `docker_timeout` | `0s` | how long to wait for the daemon to become reachable. |
-| `bind_workdir` | `false` | bind-mount the workspace from the host instead of using a docker volume. Needed for jobs that use `docker compose` with bind mounts under Docker-in-Docker. The parent directory must then be mounted into the runner container and listed in `valid_volumes`. |
+| `bind_workdir` | `false` | bind-mount the workspace from the host instead of using a docker volume, so jobs can bind-mount it by its own path into containers they start (`.:/app` in `docker compose`). Not needed when workflows use `GITEA_DOCKER_WORKSPACE`. The parent directory must then be mounted into the runner container. |
 
 :::note Privileged mode and workflow container options
 A workflow's own `jobs.<job_id>.container.options` are untrusted input. While `container.privileged` is disabled, the options that would break out of the container are stripped with a warning in the job log: `--pid`, `--ipc`, `--uts`, `--cgroupns`, `--userns`, `--cap-add`, `--security-opt`, `--device`, `--device-cgroup-rule`, `--gpus`, `--volumes-from`, `--runtime`, `--cgroup-parent` and `--sysctl`. They are honoured once privileged mode is enabled, because the operator has then opted into host access.

runner-docs/reference/cli.md

@@ -103,13 +103,15 @@ Flags:
       --detect-event                     Use first event type from workflow as event that triggered the workflow
   -C, --directory string                 working directory (default ".")
   -n, --dryrun                           dryrun mode
-      --env stringArray                  env to make available to actions with optional value (e.g. --env myenv=foo or --env myenv)
+      --env stringArray                  env to make available to actions with optional value (e.g. --env myenv=foo or --env myenv; override env-file)
       --env-file string                  environment file to read and use as env in the containers (default ".env")
   -E, --event string                     run a event name
   -e, --eventpath string                 path to a JSON event payload file exposed as the event that triggered the workflow
       --gitea-instance string            Gitea instance to use.
   -h, --help                             help for exec
   -i, --image string                     Docker image to use. Use "-self-hosted" to run directly on the host. (default "docker.gitea.com/runner-images:ubuntu-latest")
+      --input stringArray                set an input the workflow declares under its workflow_dispatch or workflow_call trigger, others stay invisible to the inputs context (e.g. --input name=bar; can be specified multiple times with highest precedence)
+      --input-file string                path to an .env-format file containing key=value pairs as baseline workflow inputs (override event inputs)
       --insecure-secrets                 NOT RECOMMENDED! Doesn't hide secrets while printing logs.
   -j, --job string                       run a specific job ID; when several workflow files define that job, also pass --workflows/-W to select the file
       --json                             Output logs in json format

runner-docs/reference/config-example.md

@@ -86,7 +86,7 @@ runner:
   # This ensures bursty output (e.g., npm install) is delivered promptly.
   #log_report_batch_size: 100
   # The interval for reporting task state (step status, timing) to the Gitea instance.
-  # State is also reported immediately on step transitions (start/stop).
+  # State is also reported on step transitions (start/stop) and after each log flush.
   #state_report_interval: 5s
   # Per-attempt deadline for flushing the final logs and task state when a job
   # finishes, on a detached context so a server cancel can't block the acknowledgement.
@@ -234,6 +234,8 @@ container:
   # A volume declared here replaces the one the runner would mount on the same container path, so the
   # tool cache can be kept on the host. Its source must also be allowed by valid_volumes below:
   #   options: --volume /host/toolcache:/opt/hostedtoolcache
+  # With privileged disabled, options that could escape the container (--security-opt, --device,
+  # --cap-add, --pid, ...) are ignored in a workflow's container.options, but keep working here.
   #options:
   # The parent directory of a job's working directory.
   # NOTE: There is no need to add the first '/' of the path as runner will add it automatically.
@@ -254,7 +256,7 @@ container:
   #valid_volumes: []
   # Overrides the docker client host with the specified one.
   # If it's empty, runner will find an available docker host automatically.
-  # If it's "-", runner will find an available docker host automatically, but the docker host won't be mounted to the job containers and service containers.
+  # If it's "-", runner will find an available docker host automatically, but won't mount it into the job and action containers.
   # If it's not empty or "-", the specified docker host will be used. An error will be returned if it doesn't work.
   #docker_host: ""
   # Pull docker image(s) even if already present.

runner-docs_versioned_docs/version-3/reference/config-example.md

@@ -86,7 +86,7 @@ runner:
   # This ensures bursty output (e.g., npm install) is delivered promptly.
   #log_report_batch_size: 100
   # The interval for reporting task state (step status, timing) to the Gitea instance.
-  # State is also reported immediately on step transitions (start/stop).
+  # State is also reported on step transitions (start/stop) and after each log flush.
   #state_report_interval: 5s
   # Per-attempt deadline for flushing the final logs and task state when a job
   # finishes, on a detached context so a server cancel can't block the acknowledgement.
@@ -234,6 +234,8 @@ container:
   # A volume declared here replaces the one the runner would mount on the same container path, so the
   # tool cache can be kept on the host. Its source must also be allowed by valid_volumes below:
   #   options: --volume /host/toolcache:/opt/hostedtoolcache
+  # With privileged disabled, options that could escape the container (--security-opt, --device,
+  # --cap-add, --pid, ...) are ignored in a workflow's container.options, but keep working here.
   #options:
   # The parent directory of a job's working directory.
   # NOTE: There is no need to add the first '/' of the path as runner will add it automatically.
@@ -254,7 +256,7 @@ container:
   #valid_volumes: []
   # Overrides the docker client host with the specified one.
   # If it's empty, runner will find an available docker host automatically.
-  # If it's "-", runner will find an available docker host automatically, but the docker host won't be mounted to the job containers and service containers.
+  # If it's "-", runner will find an available docker host automatically, but won't mount it into the job and action containers.
   # If it's not empty or "-", the specified docker host will be used. An error will be returned if it doesn't work.
   #docker_host: ""
   # Pull docker image(s) even if already present.

scripts/check-upstream-deps.sh

@@ -0,0 +1,142 @@
+#!/bin/bash
+#
+# Fails when a pull request depends on a gitea change that is not merged yet.
+#
+# Usage: ./scripts/check-upstream-deps.sh <pull request json>
+#
+# The json is what the gitea api returns for a pull request; the script reads
+# the description and the labels from it. A dependency is declared on a line of
+# its own in the description:
+#
+#   Depends on: gitea#35851
+#   Depends on: https://github.com/go-gitea/gitea/pull/35851
+#
+# and may be declared several times. Only such lines count, so a pull request
+# that merely mentions gitea#35851 in prose is not held back.
+#
+# The `depends-on-upstream` label is what blocks the merge: it fails the check
+# unless every declared dependency is verified as merged. Without the label, a
+# dependency that is known to be unmerged still fails, so a forgotten label does
+# not let an unreleased feature through.
+#
+# Exit codes: 0 nothing blocks, 1 blocked, 2 usage.
+#
+# Environment:
+#   GITHUB_COM_TOKEN   optional, lifts the rate limit of the github api
+#   UPSTREAM_LABEL     label to look for, `depends-on-upstream` by default
+#   REQUIRE_VERIFIED   set to 1 to also fail when the state cannot be determined
+
+set -euo pipefail
+
+LABEL="${UPSTREAM_LABEL:-depends-on-upstream}"
+PULL_JSON="${1:-}"
+
+if [ -z "$PULL_JSON" ] || [ ! -f "$PULL_JSON" ]; then
+  echo "usage: $0 <pull request json>" >&2
+  exit 2
+fi
+
+body="$(jq -r '.body // ""' "$PULL_JSON")"
+# `label` is a keyword in jq 1.6, which is what the runner image has, so the
+# argument cannot be named after it; `(.labels // [])` keeps it parsable there
+labelled="$(jq -r --arg want "$LABEL" '[(.labels // [])[].name] | index($want) != null' "$PULL_JSON")"
+
+require_verified="${REQUIRE_VERIFIED:-0}"
+if [ "$labelled" = 'true' ]; then
+  # the label says the pull request is not ready, so an unverifiable dependency
+  # keeps it blocked instead of letting it through
+  require_verified=1
+fi
+
+# the ids of the `Depends on:` lines, deduplicated
+refs="$(printf '%s\n' "$body" \
+  | grep -iE '^[[:space:]]*depends[ _-]?on[[:space:]]*:' \
+  | grep -oiE 'gitea#[0-9]+|github\.com/go-gitea/gitea/pull/[0-9]+' \
+  | grep -oE '[0-9]+' \
+  | sort -un || true)"
+
+if [ -z "$refs" ]; then
+  if [ "$labelled" = 'true' ]; then
+    echo "This pull request carries the \"$LABEL\" label but does not say what it"
+    echo "depends on. Add a line to the description, for example:"
+    echo
+    echo "  Depends on: gitea#35851"
+    exit 1
+  fi
+  echo "no upstream dependency declared"
+  exit 0
+fi
+
+github_api() {
+  local url="$1"
+  if [ -n "${GITHUB_COM_TOKEN:-}" ]; then
+    curl --silent --show-error --write-out '\n%{http_code}' \
+      -H "Authorization: Bearer $GITHUB_COM_TOKEN" "$url"
+  else
+    curl --silent --show-error --write-out '\n%{http_code}' "$url"
+  fi
+}
+
+unmerged=0
+unknown=0
+for ref in $refs; do
+  response="$(github_api "https://api.github.com/repos/go-gitea/gitea/pulls/$ref")"
+  code="$(printf '%s' "$response" | tail -n 1)"
+  payload="$(printf '%s' "$response" | sed '$d')"
+
+  case "$code" in
+    200)
+      if [ "$(printf '%s' "$payload" | jq -r '.merged')" = 'true' ]; then
+        echo "gitea#$ref is merged"
+      else
+        echo "gitea#$ref is not merged yet ($(printf '%s' "$payload" | jq -r '.state'))"
+        unmerged=1
+      fi
+      ;;
+    404)
+      echo "gitea#$ref is not a pull request of go-gitea/gitea, reference the pull request that adds the feature"
+      unmerged=1
+      ;;
+    403 | 429)
+      echo "gitea#$ref: the github api rejected the request (rate limit), cannot tell whether it is merged"
+      unknown=1
+      ;;
+    *)
+      echo "gitea#$ref: unexpected response $code from the github api, cannot tell whether it is merged"
+      unknown=1
+      ;;
+  esac
+done
+
+if [ "$unknown" -eq 1 ] && [ -z "${GITHUB_COM_TOKEN:-}" ]; then
+  echo
+  echo "The github api allows 60 unauthenticated requests per hour and address,"
+  echo "which the runners share. Set the GITHUB_COM_TOKEN secret to a token with"
+  echo "no scopes to raise that limit."
+fi
+
+if [ "$unmerged" -eq 1 ] || { [ "$unknown" -eq 1 ] && [ "$require_verified" = '1' ]; }; then
+  echo
+  if [ "$labelled" = 'true' ]; then
+    echo "This pull request is labelled \"$LABEL\", so it stays blocked until every"
+    echo "dependency above is merged into gitea main. The scheduled job removes the"
+    echo "label and reruns this check as soon as that is the case."
+  else
+    echo "The documentation of an unreleased feature can only be merged once the"
+    echo "feature itself is in gitea main. Add the \"$LABEL\" label so the pull"
+    echo "request is picked up by the job that watches for it."
+  fi
+  exit 1
+fi
+
+if [ "$unknown" -eq 1 ]; then
+  echo
+  echo "Could not verify every dependency, letting the check pass: the pull request"
+  echo "does not carry the \"$LABEL\" label."
+  exit 0
+fi
+
+if [ "$labelled" = 'true' ]; then
+  echo
+  echo "every declared dependency is merged, the \"$LABEL\" label can be removed"
+fi

scripts/unlabel-upstream-deps.sh

@@ -0,0 +1,80 @@
+#!/bin/bash
+#
+# Removes the `depends-on-upstream` label from every open pull request whose
+# referenced gitea pull requests are all merged, and says so in a comment.
+# Removing the label reruns the `depends-upstream` check of that pull request.
+#
+# Usage: ./scripts/unlabel-upstream-deps.sh
+#
+# Environment:
+#   GITEA_API      api of the repository, e.g. https://gitea.com/api/v1/repos/gitea/docs
+#   DEPLOY_TOKEN   token used to remove the label and to comment
+#   GITHUB_COM_TOKEN  optional, lifts the rate limit of the github api
+#   UPSTREAM_LABEL    label to look for, `depends-on-upstream` by default
+#   DRY_RUN        set to 1 to only report what would happen
+
+set -euo pipefail
+
+LABEL="${UPSTREAM_LABEL:-depends-on-upstream}"
+API="${GITEA_API:?GITEA_API is required}"
+DRY_RUN="${DRY_RUN:-0}"
+
+gitea_api() {
+  local method="$1" url="$2" data="${3:-}"
+  local args=(--silent --show-error --fail -X "$method")
+  if [ -n "${DEPLOY_TOKEN:-}" ]; then args+=(-H "Authorization: token $DEPLOY_TOKEN"); fi
+  if [ -n "$data" ]; then args+=(-H 'Content-Type: application/json' --data "$data"); fi
+  curl "${args[@]}" "$url"
+}
+
+# see the note in check-upstream-deps.sh about the argument name
+label_id="$(gitea_api GET "$API/labels?limit=100" | jq -r --arg want "$LABEL" \
+  '.[] | select(.name == $want) | .id')"
+if [ -z "$label_id" ]; then
+  echo "the repository has no \"$LABEL\" label, nothing to do"
+  exit 0
+fi
+
+pulls="$(gitea_api GET "$API/pulls?state=open&limit=50")"
+indexes="$(printf '%s' "$pulls" | jq -r --arg want "$LABEL" \
+  '.[] | select([(.labels // [])[].name] | index($want) != null) | .number')"
+
+if [ -z "$indexes" ]; then
+  echo "no open pull request carries the \"$LABEL\" label"
+  exit 0
+fi
+
+here="$(cd "$(dirname "$0")" && pwd)"
+work="$(mktemp -d)"
+trap 'rm -rf "$work"' EXIT
+
+for index in $indexes; do
+  gitea_api GET "$API/pulls/$index" > "$work/pull.json"
+
+  # the check script exits 0 when every reference is merged; it needs the label
+  # to be absent from its input to stay quiet about it, so drop it here
+  jq 'del(.labels)' "$work/pull.json" > "$work/pull-unlabelled.json"
+  # REQUIRE_VERIFIED keeps a dependency whose state could not be determined from
+  # counting as merged, which would drop the label too early
+  if ! output="$(REQUIRE_VERIFIED=1 "$here/check-upstream-deps.sh" "$work/pull-unlabelled.json" 2>&1)"; then
+    echo "#$index still waits for upstream:"
+    printf '%s\n' "$output" | sed 's/^/    /'
+    continue
+  fi
+
+  if printf '%s' "$output" | grep -q 'no upstream dependency declared'; then
+    echo "#$index carries the label but declares no dependency, leaving it alone"
+    continue
+  fi
+
+  if [ "$DRY_RUN" = '1' ]; then
+    echo "#$index would lose the label:"
+    printf '%s\n' "$output" | sed 's/^/    /'
+    continue
+  fi
+
+  gitea_api DELETE "$API/issues/$index/labels/$label_id" > /dev/null
+  comment="$(printf 'Every referenced gitea pull request is merged, so the `%s` label was removed and the check was rerun.\n\n%s' "$LABEL" "$output")"
+  gitea_api POST "$API/issues/$index/comments" "$(jq -n --arg body "$comment" '{body: $body}')" > /dev/null
+  echo "#$index unlabelled"
+done

sites/docs/astro.config.mjs

@@ -126,6 +126,7 @@ export default defineConfig({
         Header: './src/components/Header.astro',
         LanguageSelect: './src/components/LanguageSelect.astro',
         MarkdownContent: './src/components/MarkdownContent.astro',
+        Sidebar: './src/components/Sidebar.astro',
         SiteTitle: './src/components/SiteTitle.astro',
         PageFrame: './src/components/PageFrame.astro',
       },

sites/docs/package.json

@@ -11,12 +11,12 @@
     "check": "astro check"
   },
   "dependencies": {
-    "@astrojs/starlight": "0.41.7",
+    "@astrojs/starlight": "0.41.11",
     "@astrojs/starlight-docsearch": "0.7.0",
     "@gitea-docs/content-loader": "workspace:*",
     "@pagefind/default-ui": "1.5.2",
-    "astro": "7.2.3",
-    "sharp": "0.35.3",
+    "astro": "7.2.10",
+    "sharp": "0.35.4",
     "starlight-openapi": "0.26.1"
   },
   "devDependencies": {

sites/docs/src/components/ProductNav.astro

@@ -0,0 +1,78 @@
+---
+import { t } from '../config/strings';
+import { productNav } from '../lib/versions';
+
+interface Props {
+  variant: 'header' | 'sidebar';
+}
+
+const meta = Astro.locals.starlightRoute.entry.data.gitea;
+const strings = t(meta?.locale ?? 'en-us');
+const products = productNav(meta);
+const { variant } = Astro.props;
+---
+
+<nav class:list={['gitea-product-nav', `gitea-product-nav-${variant}`]} aria-label="Products">
+  {
+    products.map((product) => (
+      <a href={product.href} aria-current={product.current ? 'page' : undefined}>
+        {strings.products[product.id] ?? product.label}
+      </a>
+    ))
+  }
+</nav>
+
+<style>
+  .gitea-product-nav a {
+    color: var(--sl-color-gray-2);
+    text-decoration: none;
+    white-space: nowrap;
+  }
+
+  .gitea-product-nav a:hover {
+    color: var(--sl-color-white);
+  }
+
+  .gitea-product-nav-header {
+    display: none;
+    gap: 0.75rem;
+    font-size: var(--sl-text-sm);
+  }
+
+  .gitea-product-nav-header a[aria-current='page'] {
+    color: var(--sl-color-white);
+    font-weight: 600;
+  }
+
+  .gitea-product-nav-sidebar {
+    display: flex;
+    flex-direction: column;
+    gap: 0.5rem;
+    padding-bottom: 1rem;
+    border-bottom: 1px solid var(--sl-color-hairline-light);
+  }
+
+  .gitea-product-nav-sidebar a {
+    display: block;
+    border-radius: 0.25rem;
+    padding: 0.3em 0.5rem;
+    font-size: var(--sl-text-sm);
+    line-height: 1.4;
+  }
+
+  .gitea-product-nav-sidebar a[aria-current='page'] {
+    color: var(--sl-color-text-invert);
+    background-color: var(--sl-color-text-accent);
+    font-weight: 600;
+  }
+
+  @media (min-width: 72rem) {
+    .gitea-product-nav-header {
+      display: flex;
+    }
+
+    .gitea-product-nav-sidebar {
+      display: none;
+    }
+  }
+</style>

sites/docs/src/components/Sidebar.astro

@@ -0,0 +1,13 @@
+---
+import Default from '@astrojs/starlight/components/Sidebar.astro';
+import ProductNav from './ProductNav.astro';
+
+/**
+ * The product navigation is hidden from the header until the 72rem layout
+ * breakpoint, so it is rendered at the top of the sidebar for the layouts in
+ * between (and for the mobile menu below 50rem).
+ */
+---
+
+<ProductNav variant="sidebar" />
+<Default />

sites/docs/src/components/SiteTitle.astro

@@ -1,29 +1,17 @@
 ---
 import Default from '@astrojs/starlight/components/SiteTitle.astro';
-import { t } from '../config/strings';
-import { productNav } from '../lib/versions';
+import ProductNav from './ProductNav.astro';
 
 /**
  * The starlight header has no navigation links, the gitea site needs the four
  * products next to the logo. Rendered next to the site title so the rest of the
  * header (search, theme, pickers) keeps working untouched.
  */
-const meta = Astro.locals.starlightRoute.entry.data.gitea;
-const strings = t(meta?.locale ?? 'en-us');
-const products = productNav(meta);
 ---
 
 <div class="gitea-site-title">
   <Default><slot /></Default>
-  <nav class="gitea-nav" aria-label="Products">
-    {
-      products.map((product) => (
-        <a href={product.href} class:list={[{ current: product.current }]}>
-          {strings.products[product.id] ?? product.label}
-        </a>
-      ))
-    }
-  </nav>
+  <ProductNav variant="header" />
 </div>
 
 <style>
@@ -33,26 +21,4 @@ const products = productNav(meta);
     gap: 1rem;
     overflow: hidden;
   }
-  .gitea-nav {
-    display: none;
-    gap: 0.75rem;
-    font-size: var(--sl-text-sm);
-  }
-  .gitea-nav a {
-    color: var(--sl-color-gray-2);
-    text-decoration: none;
-    white-space: nowrap;
-  }
-  .gitea-nav a:hover,
-  .gitea-nav a.current {
-    color: var(--sl-color-white);
-  }
-  .gitea-nav a.current {
-    font-weight: 600;
-  }
-  @media (min-width: 72rem) {
-    .gitea-nav {
-      display: flex;
-    }
-  }
 </style>

static/openapi3-latest.json

@@ -32751,6 +32751,9 @@
           },
           "422": {
             "$ref": "#/components/responses/invalidTopicsError"
+          },
+          "423": {
+            "$ref": "#/components/responses/repoArchivedError"
           }
         },
         "summary": "Replace list of topics for a repository",
@@ -32800,6 +32803,9 @@
           },
           "422": {
             "$ref": "#/components/responses/invalidTopicsError"
+          },
+          "423": {
+            "$ref": "#/components/responses/repoArchivedError"
           }
         },
         "summary": "Delete a topic from a repository",
@@ -32847,6 +32853,9 @@
           },
           "422": {
             "$ref": "#/components/responses/invalidTopicsError"
+          },
+          "423": {
+            "$ref": "#/components/responses/repoArchivedError"
           }
         },
         "summary": "Add a topic to a repository",

static/swagger-latest.json

@@ -20099,6 +20099,9 @@
           },
           "422": {
             "$ref": "#/responses/invalidTopicsError"
+          },
+          "423": {
+            "$ref": "#/responses/repoArchivedError"
           }
         }
       }
@@ -20145,6 +20148,9 @@
           },
           "422": {
             "$ref": "#/responses/invalidTopicsError"
+          },
+          "423": {
+            "$ref": "#/responses/repoArchivedError"
           }
         }
       },
@@ -20189,6 +20195,9 @@
           },
           "422": {
             "$ref": "#/responses/invalidTopicsError"
+          },
+          "423": {
+            "$ref": "#/responses/repoArchivedError"
           }
         }
       }