Add NetBird diagnostic checks to deploy job

Surface VPN connection status in the deploy job so netbird failures are
legible instead of a cryptic DeadlineExceeded:
- Pre-flight check for /dev/net/tun + NET_ADMIN before connecting
- id + timeout-minutes:3 on Netbird Connect to bound its wait loop
- Post-connect 'netbird status --detail' with a Management:Connected assert
- Always-run diagnostics + 'netbird down' teardown

.github/workflows/build-docker-images.yml

@@ -56,13 +56,48 @@ jobs:
     needs: build
 
     steps:
+      - name: Pre-flight - verify VPN prerequisites
+        # NetBird brings up a WireGuard interface, which needs a TUN device and
+        # NET_ADMIN inside the job container. Without them, `netbird up` hangs
+        # ~50s and dies with a cryptic "DeadlineExceeded". Check up front so the
+        # failure is obvious and points at the fix (runner config.yaml).
+        run: |
+          echo "::group::NetBird prerequisites"
+          if [ -e /dev/net/tun ]; then
+            echo "OK: /dev/net/tun present"
+          else
+            echo "::error title=Missing TUN device::/dev/net/tun not found. Add --device=/dev/net/tun to the runner's config.yaml container.options."
+            exit 1
+          fi
+          if command -v capsh >/dev/null 2>&1; then
+            capsh --print | grep -q 'cap_net_admin' \
+              && echo "OK: NET_ADMIN present" \
+              || echo "::warning title=NET_ADMIN missing::netbird up will likely time out (DeadlineExceeded) configuring wt0. Add --cap-add=NET_ADMIN to the runner's config.yaml container.options."
+          else
+            echo "note: capsh unavailable, skipping NET_ADMIN check"
+          fi
+          echo "::endgroup::"
+
       - name: Netbird Connect
+        id: netbird
+        timeout-minutes: 3
         uses: Alemiz112/netbird-connect@v1
         with:
           setup-key: ${{ secrets.NETBIRD_SETUP_KEY }}
           hostname: 'gitea-actions-blog'
           management-url: ${{ secrets.NETBIRD_URL }}
 
+      - name: NetBird status
+        # Surface the actual peer/route state in the log and hard-assert that
+        # the management connection is up before attempting any deploys.
+        run: |
+          echo "::group::netbird status"
+          sudo netbird status --detail || true
+          echo "::endgroup::"
+          sudo netbird status | grep -q 'Management: Connected' \
+            && echo "NetBird management connected." \
+            || { echo "::error title=NetBird not connected::Management not connected after netbird up."; exit 1; }
+
       - name: Deploy to RPIC-Cluster
         # RPIC cluster is temporarily out of service. Don't let its failure
         # block the Gimli deploy or fail the whole job. Remove this line once
@@ -84,3 +119,13 @@ jobs:
           key: ${{ secrets.GIMLI_KEY }}
           port: ${{ secrets.SSH_PORT }}
           script: 'docker compose down && docker compose pull && docker compose up -d'
+
+      - name: NetBird diagnostics & disconnect
+        # Runs even on failure: captures final state for debugging and tears the
+        # peer down so stale 'gitea-actions-blog' peers don't pile up.
+        if: always()
+        run: |
+          echo "::group::final netbird status"
+          sudo netbird status --detail || echo "netbird unavailable"
+          echo "::endgroup::"
+          sudo netbird down || true