diff --git a/.gitea/workflows/build-docs.yaml b/.gitea/workflows/build-docs.yaml
index 66fcc75..1e21690 100644
--- a/.gitea/workflows/build-docs.yaml
+++ b/.gitea/workflows/build-docs.yaml
@@ -21,32 +21,38 @@ jobs:
         with:
           path: api-company
 
+      # NOTE: cross-repo checkouts use SIBLING_REPOS_TOKEN, NOT the auto-injected
+      # GITEA_TOKEN. Gitea's automatic GITEA_TOKEN is scoped to THIS repo only,
+      # so checking out other repos fails with
+      # "Determining the default branch → not found". GITEA_TOKEN is also a
+      # reserved secret name that cannot be overridden, hence a separate secret.
+      # SIBLING_REPOS_TOKEN must be a PAT with read access to the API repos.
       - name: Checkout zip-enrichment
         uses: actions/checkout@v4
         with:
           repository: leeworks-agents/zip-enrichment
-          token: ${{ secrets.GITEA_TOKEN }}
+          token: ${{ secrets.SIBLING_REPOS_TOKEN }}
           path: zip-enrichment
 
       - name: Checkout holidays
         uses: actions/checkout@v4
         with:
           repository: leeworks-agents/holidays
-          token: ${{ secrets.GITEA_TOKEN }}
+          token: ${{ secrets.SIBLING_REPOS_TOKEN }}
           path: holidays
 
       - name: Checkout air-quality
         uses: actions/checkout@v4
         with:
           repository: leeworks-agents/air-quality
-          token: ${{ secrets.GITEA_TOKEN }}
+          token: ${{ secrets.SIBLING_REPOS_TOKEN }}
           path: air-quality
 
       - name: Checkout vin-decoder
         uses: actions/checkout@v4
         with:
           repository: leeworks-agents/vin-decoder
-          token: ${{ secrets.GITEA_TOKEN }}
+          token: ${{ secrets.SIBLING_REPOS_TOKEN }}
           path: vin-decoder
 
       - name: Copy openapi.yaml specs into docs-site
diff --git a/.gitea/workflows/validate-flux.yaml b/.gitea/workflows/validate-flux.yaml
index 20bb552..88998ac 100644
--- a/.gitea/workflows/validate-flux.yaml
+++ b/.gitea/workflows/validate-flux.yaml
@@ -13,9 +13,11 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Install kustomize
+        # The Gitea act runner image runs as root and has no `sudo`, so install
+        # straight into a writable bin dir instead of `sudo mv … /usr/local/bin`.
         run: |
           curl -sL "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh" | bash
-          sudo mv kustomize /usr/local/bin/
+          install -m 0755 kustomize /usr/local/bin/kustomize
 
       - name: kustomize build flux/
         run: kustomize build flux/ > /dev/null