From 28fbaf37d4299a9c6946d2feed903bd0e23e8f30 Mon Sep 17 00:00:00 2001
From: MrSphay <lefiwilkens@gmail.com>
Date: Sun, 3 May 2026 02:08:36 +0200
Subject: [PATCH] Document Gitea token status checks

---
 README.md           | 15 +++++++++++++++
 agent-quickstart.md |  4 ++++
 existing-project.md |  1 +
 files/AGENTS.md     |  2 ++
 new-repository.md   |  1 +
 5 files changed, 23 insertions(+)

diff --git a/README.md b/README.md
index 431e956..8c761c2 100644
--- a/README.md
+++ b/README.md
@@ -76,6 +76,21 @@ AUDIT_COMMAND
 
 If a placeholder does not apply, remove it instead of inventing fake information.
 
+## Gitea API Token
+
+When working with private repositories on `git.wilkensxl.de`, Codex agents may find a local `GITEA_TOKEN` environment variable on the machine.
+
+Use `GITEA_TOKEN` only for read-oriented Gitea API checks unless the user explicitly asks for a write action. Typical safe checks include repository metadata, workflow run status, and package-read visibility. Never print the token, commit it, or copy it into workflow files.
+
+Example status endpoint:
+
+```text
+GET https://git.wilkensxl.de/api/v1/repos/REPOSITORY_OWNER/REPOSITORY_NAME/actions/runs
+Authorization: token GITEA_TOKEN
+```
+
+`REGISTRY_TOKEN` is still the intended secret name for CI package publishing inside `.gitea/workflows/build.yml`.
+
 ## Agent Prompt For A New Repo
 
 ```text
diff --git a/agent-quickstart.md b/agent-quickstart.md
index 2d9b244..95c4511 100644
--- a/agent-quickstart.md
+++ b/agent-quickstart.md
@@ -49,6 +49,10 @@ Does the project have CI?
 Are commands unknown?
   yes -> document PENDING in .codex/project.md
   no  -> wire commands into AGENTS.md and CI
+
+Is this a private Gitea repo with Actions?
+  yes -> if GITEA_TOKEN is set locally, use it for read-only API checks of repository and workflow-run status
+  no  -> use public web/API checks when available
 ```
 
 ## Minimal File Set
diff --git a/existing-project.md b/existing-project.md
index 069343d..536b3b3 100644
--- a/existing-project.md
+++ b/existing-project.md
@@ -145,6 +145,7 @@ Before final response:
 
 - run `git diff --check`,
 - run the smallest reliable verification command,
+- if using Gitea Actions, check the pushed workflow run; for private `git.wilkensxl.de` repositories, use a locally set `GITEA_TOKEN` for read-only API status checks when available,
 - list files changed,
 - mention any skipped checks,
 - do not create a release unless explicitly requested.
diff --git a/files/AGENTS.md b/files/AGENTS.md
index 3df61ab..86a88de 100644
--- a/files/AGENTS.md
+++ b/files/AGENTS.md
@@ -11,6 +11,7 @@ PROJECT_NAME: PROJECT_DESCRIPTION
 - Do not commit secrets, `.env` files, private keys, certificates, or tokens.
 - Do not rewrite history or run destructive git commands unless explicitly requested.
 - Do not create a release unless explicitly requested.
+- If `GITEA_TOKEN` is available locally, use it only for read-only Gitea API checks such as private repository metadata, package-read visibility, and Actions run status. Never print, commit, or store the token.
 
 ## Commands
 
@@ -45,4 +46,5 @@ ARTIFACT_NAME
 - Treat generated credentials and config files as sensitive.
 - Keep external network calls documented.
 - Prefer local processing for user data.
+- Keep CI publishing secrets in repository or organization secrets, not in tracked files. `REGISTRY_TOKEN` is the default package publishing secret name for the Gitea workflow template.
 
diff --git a/new-repository.md b/new-repository.md
index 6ede5e1..246e024 100644
--- a/new-repository.md
+++ b/new-repository.md
@@ -154,6 +154,7 @@ Before final response:
 - run formatting or validation if available,
 - run the cheapest reliable verification command,
 - check `git diff --check`,
+- if using Gitea Actions, check the pushed workflow run; for private `git.wilkensxl.de` repositories, use a locally set `GITEA_TOKEN` for read-only API status checks when available,
 - summarize changed files,
 - do not create a release unless explicitly requested.