MrSphay/codex-agent-repository-kit
Template
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 5 Wiki Activity

Clarify token permissions in README

Browse Source
This commit is contained in:
MrSphay
2026-05-15 14:54:31 +02:00
parent 5ba44fcb03
commit a4245a1563
3 changed files with 65 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
CHANGELOG.md
View File

@@ -2,6 +2,12 @@
All notable changes to the Codex Agent Repository Kit are documented here.
## 1.0.5 - 2026-05-15
- Restored the rainbow section divider theme in the human-facing `README.md`.
- Added separate minimal permission guidance for `REGISTRY_TOKEN` and `GITEA_TOKEN`.
- Clarified where package-only and API-capable tokens should be used.
## 1.0.4 - 2026-05-15
- Set the documented Gitea host to `git.wilkensxl.de` instead of a generic URL placeholder.

67
README.md
View File

@@ -4,6 +4,8 @@ Reusable setup kit for new or existing repositories that should be easy for Code
This README is for humans. Agent-facing rules live in `AGENTS.md`, `agent-quickstart.md`, `new-repository.md`, and `existing-project.md`.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## What This Kit Adds
- `AGENTS.md` and `.codex/project.md` for agent context.
@@ -12,6 +14,8 @@ This README is for humans. Agent-facing rules live in `AGENTS.md`, `agent-quicks
- README blueprint templates for projects that want generated README output.
- Stack notes for Node, Electron, Python, Docker, and static-site projects.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Recommended New Repository Setup
1. Create the repository in Gitea.
@@ -22,6 +26,8 @@ This README is for humans. Agent-facing rules live in `AGENTS.md`, `agent-quicks
6. Commit and push the baseline.
7. Let the Gitea workflows report any missing setup.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## SSH Setup
Generate a key if you do not already have one:
@@ -79,6 +85,8 @@ git remote -v
git status --short
```
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Applying The Kit With Codex
For a new repository, start Codex in the target repository and use:
@@ -102,6 +110,8 @@ Preserve current CI behavior and project style.
Do not create a release.
```
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Manual Copy Map
Use `manifest.json` as the source of truth. Common targets:
@@ -123,6 +133,8 @@ Use `manifest.json` as the source of truth. Common targets:
| `files/security-review.md` | `docs/security-review.md` |
| `files/agent-handoff.md` | `docs/agent-handoff.md` |
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Required Placeholder Values
Replace or remove all placeholders before considering a repository ready:
@@ -154,6 +166,8 @@ COMMIT_OR_VERSION
If a value does not apply, remove that section instead of leaving fake data. If a value is genuinely unknown, mark it as `PENDING`.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Token Overview
Use separate tokens for separate jobs.
@@ -165,15 +179,44 @@ Use separate tokens for separate jobs.
Repository secrets are available to workflows. They are not visible to local Codex sessions. Local Codex API actions need a local environment variable.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Gitea Token Permissions
For the token permission screen shown in Gitea, choose:
For both tokens, choose this repository access level:
```text
Repository and Organization Access: All (public, private, and limited)
```
issue: Read and Write
Use separate tokens where possible. A package-only token should not be able to create issues or releases.
### REGISTRY_TOKEN Permissions
Use this token as a repository secret for package publishing from Gitea Actions:
```text
package: Read and Write
repository: Read
user: Read
activitypub: No Access
admin: No Access
issue: No Access
misc: No Access
notification: No Access
organization: No Access
```
These permissions cover generic package uploads while still allowing the workflow to read repository metadata.
### GITEA_TOKEN Permissions
Use this token locally on the PC for Codex API actions, or as a repository secret only when workflows need issue, release, or workflow API access:
```text
issue: Read and Write
package: Read
repository: Read and Write
user: Read
@@ -184,16 +227,12 @@ notification: No Access
organization: No Access
```
These permissions cover:
- creating and reading issues,
- creating and reading releases,
- uploading package registry files,
- reading repository metadata,
- polling workflow runs where the Gitea API allows it.
These permissions cover creating and reading issues, creating and reading releases, reading repository metadata, and polling workflow runs where the Gitea API allows it. `package: Read` is enough for API checks; use `package: Read and Write` only if this same token must publish packages.
Use a dedicated bot or automation user when possible.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Setting Local Tokens
Set a local token for Codex or shell-based API work.
@@ -229,6 +268,8 @@ Invoke-RestMethod `
-Headers $headers
```
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Setting Repository Secrets
In Gitea:
@@ -251,6 +292,8 @@ GITEA_TOKEN
Keep package publishing and release or issue automation separate when possible. It makes permission reviews easier.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Package Publishing
`files/build-gitea.yml` can publish generic packages when `REGISTRY_TOKEN` is available.
@@ -273,6 +316,8 @@ REGISTRY_TOKEN
When those values are unavailable, replace `REPOSITORY_OWNER`, `REPOSITORY_NAME`, and related placeholders before use. The default Gitea server is `https://git.wilkensxl.de`.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Agent Follow-up Issues
Agents should create focused tracker issues for real follow-up work that is outside the current scope or can be handled independently by humans or other agents.
@@ -287,6 +332,8 @@ An issue should include:
Agents must not create issues for vague reminders, duplicate work, or tasks they can safely finish immediately. Sensitive details belong in private channels or `docs/agent-handoff.md`, not public issues.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Release Checklist For A New Repo
Before the first release of a target project:
@@ -301,6 +348,8 @@ Before the first release of a target project:
8. Confirm release artifacts do not include Codex kit metadata unless explicitly wanted.
9. Push and poll workflows to success or document the blocker.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Updating The Kit In A Project
When this kit changes, update target repositories conservatively:

2
manifest.json
View File

@@ -1,6 +1,6 @@
{
"name": "codex-agent-repository-kit",
"version": "1.0.4",
"version": "1.0.5",
"description": "Universal repository baseline for Codex-assisted projects.",
"agentResponsibilities": [
"Read manifest.json before copying files.",