From 68dcbc9b16d40a8748bd891d5769a6a45c8c8a4b Mon Sep 17 00:00:00 2001
From: Emil Simeonov <emil@theliberatededge.org>
Date: Thu, 18 Jun 2026 04:41:09 +0200
Subject: [PATCH] GRM-12: docs: update .env.example with GITEA_ADMIN_TOKEN and
 scope requirements

---
 .env.example | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/.env.example b/.env.example
index b4e9acd..c15dac7 100644
--- a/.env.example
+++ b/.env.example
@@ -5,6 +5,15 @@ GITEA_URL=https://git.example.com
 # Admin → Actions → Runners → Create Registration Token
 GITEA_REGISTRATION_TOKEN=your-registration-token
 
+# Gitea admin API token for post-install integration test (optional).
+# The runner registration token above is NOT sufficient for the
+# /api/v1/admin/runners endpoint; it is only valid for registration.
+# To verify the runner appears in Gitea after install, generate a
+# personal access token with at least the "admin" scope:
+#   Settings → Applications → Generate New Token → scope: admin
+# If left unset, the integration test is skipped gracefully.
+# GITEA_ADMIN_TOKEN=your-admin-api-token
+
 # Default SSH user for remote hosts (optional, overrides --user)
 # GITEA_RUNNER_USER=ubuntu