codex-agent-repository-kit/README.md

Codex Agent Repository Kit

Reusable setup kit for new or existing repositories that should be easy for Codex agents, humans, and CI workflows to maintain.

This README is for humans. Agent-facing rules live in AGENTS.md, agent-quickstart.md, new-repository.md, and existing-project.md.

What This Kit Adds

• AGENTS.md and .codex/project.md for agent context.
• Optional Gitea workflows for build, security scan, cleanup, dependency check, release dry run, and template compliance.
• Release, security, handoff, changelog, and contribution templates.
• README blueprint templates for projects that want generated README output.
• Stack notes for Node, Electron, Python, Docker, and static-site projects.

Recommended New Repository Setup

1. Create the repository in Gitea.
2. Clone it locally with SSH.
3. Copy this kit into the repository with Codex or manually from files/.
4. Replace placeholders with real project values.
5. Add repository secrets for CI publishing.
6. Commit and push the baseline.
7. Let the Gitea workflows report any missing setup.

Runner Policy

This kit assumes these are the only available build runners:

Runner	Type	Allowed labels
global-runner-1	Gitea global runner	ubuntu-latest, ubuntu-24.04, ubuntu-22.04
global-runner-2	Gitea global runner	ubuntu-latest, ubuntu-24.04, ubuntu-22.04
global-runner-3	Gitea global runner	ubuntu-latest, ubuntu-24.04, ubuntu-22.04

Agents must run project builds, tests, audits, package jobs, installers, dependency setup, and releases on those Gitea Ubuntu runners. They must not run those heavy project commands on the user's local machine.

Do not add Windows or macOS runners. If a project appears to need platform-specific tooling, use an open-source Linux-compatible workaround that runs on the Ubuntu runners.

Lightweight local checks are still acceptable when they do not install dependencies or create build artifacts, for example git status --short, rg, JSON validation, manifest path checks, API status checks, and git diff --check.

SSH Setup

Generate a key if you do not already have one:

ssh-keygen -t ed25519 -C "you@example.com"

Start the SSH agent and add the key:

Start-Service ssh-agent
ssh-add $env:USERPROFILE\.ssh\id_ed25519

Show the public key:

Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub

Add that public key in Gitea:

Profile -> Settings -> SSH / GPG Keys -> Add Key

Clone with SSH:

git clone ssh://git@git.wilkensxl.de:2222/OWNER/REPOSITORY.git
cd REPOSITORY

Optional SSH config:

Host git.wilkensxl.de
  HostName git.wilkensxl.de
  User git
  Port 2222
  IdentityFile ~/.ssh/id_ed25519

With that config, this shorter clone URL also works:

git clone git@git.wilkensxl.de:OWNER/REPOSITORY.git

Verify the remote:

git remote -v
git status --short

Applying The Kit With Codex

For a new repository, start Codex in the target repository and use:

Use the Codex Agent Repository Kit.
Read manifest.json, then use new-repository.md.
Create the smallest useful baseline for this repository.
Replace placeholders with real values from this repository.
Keep commands truthful and do not invent scripts that cannot run.
Do not create a release.

For an existing repository:

Use the Codex Agent Repository Kit.
Read manifest.json, then use existing-project.md.
Retrofit the baseline without replacing existing project structure or README knowledge.
Preserve current CI behavior and project style.
Do not create a release.

Manual Copy Map

Use manifest.json as the source of truth. Common targets:

Template	Target
files/AGENTS.md	AGENTS.md
files/project.md	.codex/project.md
files/build-gitea.yml	.gitea/workflows/build.yml
files/security-scan-gitea.yml	.gitea/workflows/security-scan.yml
files/repo-cleanup-gitea.yml	.gitea/workflows/repo-cleanup.yml
files/dependency-check-gitea.yml	.gitea/workflows/dependency-check.yml
files/release-dry-run-gitea.yml	.gitea/workflows/release-dry-run.yml
files/template-compliance-gitea.yml	.gitea/workflows/template-compliance.yml
files/SECURITY.md	SECURITY.md
files/CHANGELOG.md	CHANGELOG.md
files/CONTRIBUTING.md	CONTRIBUTING.md
files/release-checklist.md	docs/release-checklist.md
files/security-review.md	docs/security-review.md
files/agent-handoff.md	docs/agent-handoff.md

Required Placeholder Values

Replace or remove all placeholders before considering a repository ready:

PROJECT_NAME
PROJECT_DESCRIPTION
REPOSITORY_OWNER
REPOSITORY_NAME
PACKAGE_NAME
ARTIFACT_NAME
ARTIFACT_OUTPUT_DIRECTORY
AUTHOR_NAME
PROJECT_STACK
DOWNLOAD_URL
CI_URL
RELEASES_URL
BUILD_COMMAND
TEST_COMMAND
LINT_COMMAND
AUDIT_COMMAND
README_COMMAND
INSTALL_COMMAND
DEV_COMMAND
PACKAGE_MANAGER
PROJECT_VERSION
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.

Token Overview

Use separate tokens for separate jobs.

Token	Location	Purpose
REGISTRY_TOKEN	Repository secret	CI package publishing from Gitea Actions
GITEA_TOKEN	Local environment or repository secret	Gitea API access for issues, releases, workflow polling, and repository metadata

Repository secrets are available to workflows. They are not visible to local Codex sessions. Local Codex API actions need a local environment variable.

Gitea Token Permissions

For both tokens, choose this repository access level:

Repository and Organization Access: All (public, private, and limited)

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:

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:

issue: Read and Write
package: Read
repository: Read and Write
user: Read

activitypub: No Access
admin: No Access
misc: No Access
notification: No Access
organization: No Access

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.

Setting Local Tokens

Set a local token for Codex or shell-based API work.

Current PowerShell session:

$env:GITEA_TOKEN = "paste-token-here"

Persist for the current Windows user:

setx GITEA_TOKEN "paste-token-here"

Open a new terminal after setx.

Test repository API access:

$headers = @{ Authorization = "token $env:GITEA_TOKEN" }
Invoke-RestMethod `
  -Uri "https://git.wilkensxl.de/api/v1/repos/REPOSITORY_OWNER/REPOSITORY_NAME" `
  -Headers $headers

Test issue access:

Invoke-RestMethod `
  -Uri "https://git.wilkensxl.de/api/v1/repos/REPOSITORY_OWNER/REPOSITORY_NAME/issues?state=open&limit=1" `
  -Headers $headers

Setting Repository Secrets

In Gitea:

Repository -> Settings -> Actions -> Secrets -> Add Secret

Add:

REGISTRY_TOKEN

Use a token with package write access. If you want workflows to create releases or issues too, add a separate secret:

GITEA_TOKEN

Keep package publishing and release or issue automation separate when possible. It makes permission reviews easier.

Package Publishing

files/build-gitea.yml can publish generic packages when REGISTRY_TOKEN is available.

The workflow:

• builds project artifacts,
• copies them to URL-safe filenames,
• uploads immutable versioned packages,
• updates a stable latest package path.

The workflow uses:

GITHUB_SERVER_URL
GITHUB_REPOSITORY_OWNER
GITHUB_REPOSITORY
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.

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.

An issue should include:

• observed problem,
• impact,
• affected files or commands,
• suggested next steps,
• verification already performed.

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.

Release Checklist For A New Repo

Before the first release of a target project:

1. Ensure AGENTS.md and .codex/project.md match the real project.
2. Replace all placeholders or mark genuinely unknown values as PENDING.
3. Configure REGISTRY_TOKEN if packages are published.
4. Configure GITEA_TOKEN only if workflows need issue or release API access.
5. Verify SSH push access.
6. Run lint, test, build, and audit commands on Gitea Ubuntu runners only.
7. Run lightweight local validation such as git diff --check.
8. Confirm release artifacts do not include Codex kit metadata unless explicitly wanted.
9. Push and poll workflows to success or document the blocker.

Updating The Kit In A Project

When this kit changes, update target repositories conservatively:

git status --short
git pull --ff-only

Then ask Codex:

Update this repository's Codex Agent Repository Kit files from the latest kit.
Preserve project-specific README content, commands, release rules, and workflow customizations.
Do not overwrite unrelated changes.