|
|
|
@@ -1,66 +1,96 @@
|
|
|
|
# Codex Agent Repository Kit
|
|
|
|
# Codex Agent Repository Kit
|
|
|
|
|
|
|
|
|
|
|
|
Reusable baseline files for repositories that should be easy for Codex agents to inspect, modify, build, review, and release.
|
|
|
|
Reusable setup kit for new or existing repositories that should be easy for Codex agents, humans, and CI workflows to maintain.
|
|
|
|
|
|
|
|
|
|
|
|
The kit has three entry points:
|
|
|
|
This README is for humans. Agent-facing rules live in `AGENTS.md`, `agent-quickstart.md`, `new-repository.md`, and `existing-project.md`.
|
|
|
|
|
|
|
|
|
|
|
|
- `agent-quickstart.md`: shortest prompts and decision tree for Codex agents.
|
|
|
|
## What This Kit Adds
|
|
|
|
- `new-repository.md`: agent workflow for a fresh repository.
|
|
|
|
|
|
|
|
- `existing-project.md`: agent workflow for upgrading an existing repository.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The files are intentionally universal. They do not assume Electron, React, Node, or any single stack. Node examples are included only because many Codex projects use them.
|
|
|
|
- `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.
|
|
|
|
|
|
|
|
|
|
|
|
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
|
|
|
## Recommended New Repository Setup
|
|
|
|
|
|
|
|
|
|
|
|
## README Section Divider
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
|
|
Generated README files should use the shared rainbow section divider between major sections.
|
|
|
|
## SSH Setup
|
|
|
|
|
|
|
|
|
|
|
|
The divider is configured in `files/blueprint.json` as the `section-line` template:
|
|
|
|
Generate a key if you do not already have one:
|
|
|
|
|
|
|
|
|
|
|
|
```md
|
|
|
|
```powershell
|
|
|
|
{{ template:section-line }}
|
|
|
|
ssh-keygen -t ed25519 -C "you@example.com"
|
|
|
|
```
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
When a project uses the README blueprint workflow, keep this divider in `blueprint.md` between major sections. Do not replace it with plain `---` unless the target platform cannot render inline images.
|
|
|
|
Start the SSH agent and add the key:
|
|
|
|
|
|
|
|
|
|
|
|
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
|
|
|
```powershell
|
|
|
|
|
|
|
|
Start-Service ssh-agent
|
|
|
|
|
|
|
|
ssh-add $env:USERPROFILE\.ssh\id_ed25519
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## Agent Goal
|
|
|
|
Show the public key:
|
|
|
|
|
|
|
|
|
|
|
|
Give every repository the same predictable anchor points:
|
|
|
|
```powershell
|
|
|
|
|
|
|
|
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Add that public key in Gitea:
|
|
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
```text
|
|
|
|
.
|
|
|
|
Profile -> Settings -> SSH / GPG Keys -> Add Key
|
|
|
|
|-- AGENTS.md
|
|
|
|
|
|
|
|
|-- .codex/
|
|
|
|
|
|
|
|
| `-- project.md
|
|
|
|
|
|
|
|
|-- .gitea/
|
|
|
|
|
|
|
|
| `-- workflows/
|
|
|
|
|
|
|
|
| |-- security-scan.yml
|
|
|
|
|
|
|
|
| |-- repo-cleanup.yml
|
|
|
|
|
|
|
|
| |-- dependency-check.yml
|
|
|
|
|
|
|
|
| |-- release-dry-run.yml
|
|
|
|
|
|
|
|
| |-- build.yml
|
|
|
|
|
|
|
|
| `-- template-compliance.yml
|
|
|
|
|
|
|
|
|-- docs/
|
|
|
|
|
|
|
|
| |-- release-checklist.md
|
|
|
|
|
|
|
|
| `-- security-review.md
|
|
|
|
|
|
|
|
|-- blueprint.md
|
|
|
|
|
|
|
|
|-- blueprint.json
|
|
|
|
|
|
|
|
|-- README.md
|
|
|
|
|
|
|
|
|-- SECURITY.md
|
|
|
|
|
|
|
|
|-- CHANGELOG.md
|
|
|
|
|
|
|
|
`-- .gitignore
|
|
|
|
|
|
|
|
```
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
Use only the files that fit the project. For a tiny script repo, `AGENTS.md`, `README.md`, `SECURITY.md`, and `CHANGELOG.md` may be enough. For an app or releasable tool, add the runner, release checklist, useful scheduled checks, and README blueprint workflow.
|
|
|
|
Clone with SSH:
|
|
|
|
|
|
|
|
|
|
|
|
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
|
|
|
```bash
|
|
|
|
|
|
|
|
git clone git@git.example.com:OWNER/REPOSITORY.git
|
|
|
|
|
|
|
|
cd REPOSITORY
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## Copy Map
|
|
|
|
Verify the remote:
|
|
|
|
|
|
|
|
|
|
|
|
| Template | Destination |
|
|
|
|
```bash
|
|
|
|
|
|
|
|
git remote -v
|
|
|
|
|
|
|
|
git status --short
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Applying The Kit With Codex
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
For a new repository, start Codex in the target repository and use:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
|
|
|
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/AGENTS.md` | `AGENTS.md` |
|
|
|
|
| `files/project.md` | `.codex/project.md` |
|
|
|
|
| `files/project.md` | `.codex/project.md` |
|
|
|
|
@@ -70,30 +100,16 @@ Use only the files that fit the project. For a tiny script repo, `AGENTS.md`, `R
|
|
|
|
| `files/dependency-check-gitea.yml` | `.gitea/workflows/dependency-check.yml` |
|
|
|
|
| `files/dependency-check-gitea.yml` | `.gitea/workflows/dependency-check.yml` |
|
|
|
|
| `files/release-dry-run-gitea.yml` | `.gitea/workflows/release-dry-run.yml` |
|
|
|
|
| `files/release-dry-run-gitea.yml` | `.gitea/workflows/release-dry-run.yml` |
|
|
|
|
| `files/template-compliance-gitea.yml` | `.gitea/workflows/template-compliance.yml` |
|
|
|
|
| `files/template-compliance-gitea.yml` | `.gitea/workflows/template-compliance.yml` |
|
|
|
|
| `files/release-checklist.md` | `docs/release-checklist.md` |
|
|
|
|
|
|
|
|
| `files/security-review.md` | `docs/security-review.md` |
|
|
|
|
|
|
|
|
| `files/blueprint.md` | `blueprint.md` |
|
|
|
|
|
|
|
|
| `files/blueprint.json` | `blueprint.json` |
|
|
|
|
|
|
|
|
| `files/SECURITY.md` | `SECURITY.md` |
|
|
|
|
| `files/SECURITY.md` | `SECURITY.md` |
|
|
|
|
| `files/CHANGELOG.md` | `CHANGELOG.md` |
|
|
|
|
| `files/CHANGELOG.md` | `CHANGELOG.md` |
|
|
|
|
| `files/CONTRIBUTING.md` | `CONTRIBUTING.md` |
|
|
|
|
| `files/CONTRIBUTING.md` | `CONTRIBUTING.md` |
|
|
|
|
| `files/gitignore.template` | `.gitignore` |
|
|
|
|
| `files/release-checklist.md` | `docs/release-checklist.md` |
|
|
|
|
|
|
|
|
| `files/security-review.md` | `docs/security-review.md` |
|
|
|
|
| `files/agent-handoff.md` | `docs/agent-handoff.md` |
|
|
|
|
| `files/agent-handoff.md` | `docs/agent-handoff.md` |
|
|
|
|
| `files/release-notes.md` | `docs/release-notes.md` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Start with `agent-quickstart.md` when using this kit through Codex.
|
|
|
|
## Required Placeholder Values
|
|
|
|
|
|
|
|
|
|
|
|
`manifest.json` contains the same copy map in a machine-readable format for agents.
|
|
|
|
Replace or remove all placeholders before considering a repository ready:
|
|
|
|
|
|
|
|
|
|
|
|
Agents should read `manifest.json` before copying files. It is the source of truth for target paths, required files, optional files, and placeholder names.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
`manifest.schema.json` documents the manifest shape. Stack-specific profile notes live in `profiles/`.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Placeholders
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Replace these after copying:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
```text
|
|
|
|
PROJECT_NAME
|
|
|
|
PROJECT_NAME
|
|
|
|
@@ -121,172 +137,168 @@ PROJECT_VERSION
|
|
|
|
COMMIT_OR_VERSION
|
|
|
|
COMMIT_OR_VERSION
|
|
|
|
```
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
If a placeholder does not apply, remove it instead of inventing fake information.
|
|
|
|
If a value does not apply, remove that section instead of leaving fake data. If a value is genuinely unknown, mark it as `PENDING`.
|
|
|
|
|
|
|
|
|
|
|
|
Agents must not leave unresolved placeholders in copied files unless the value is genuinely unknown and marked as `PENDING`.
|
|
|
|
## Token Overview
|
|
|
|
|
|
|
|
|
|
|
|
Agents must derive `REPOSITORY_OWNER` and `REPOSITORY_NAME` from the target repository remote URL or `GITHUB_REPOSITORY`. Do not reuse the owner from this repository kit's own remote.
|
|
|
|
Use separate tokens for separate jobs.
|
|
|
|
|
|
|
|
|
|
|
|
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
|
|
|
| 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 |
|
|
|
|
|
|
|
|
|
|
|
|
## Agent Responsibilities
|
|
|
|
Repository secrets are available to workflows. They are not visible to local Codex sessions. Local Codex API actions need a local environment variable.
|
|
|
|
|
|
|
|
|
|
|
|
When applying this kit, an agent should:
|
|
|
|
## Gitea Token Permissions
|
|
|
|
|
|
|
|
|
|
|
|
- read `manifest.json` first,
|
|
|
|
For the token permission screen shown in Gitea, choose:
|
|
|
|
- choose `new-repository.md` or `existing-project.md`,
|
|
|
|
|
|
|
|
- read matching `profiles/*.md` guidance after detecting the stack,
|
|
|
|
|
|
|
|
- conserve context tokens by searching first, reading only relevant files, summarizing large outputs, and avoiding generated folders, dependency folders, build outputs, or full logs unless directly relevant,
|
|
|
|
|
|
|
|
- at the start of each user-requested task, check for upstream repository updates and apply them immediately with a safe fast-forward pull when the working tree is clean,
|
|
|
|
|
|
|
|
- check `git status --short` before editing,
|
|
|
|
|
|
|
|
- preserve unrelated user changes,
|
|
|
|
|
|
|
|
- use the manifest copy map for target paths,
|
|
|
|
|
|
|
|
- replace applicable placeholders,
|
|
|
|
|
|
|
|
- remove non-applicable placeholder sections,
|
|
|
|
|
|
|
|
- keep `AGENTS.md` and `.codex/project.md` aligned,
|
|
|
|
|
|
|
|
- update `README.md` whenever README blueprint files change,
|
|
|
|
|
|
|
|
- update security and release docs when release behavior changes,
|
|
|
|
|
|
|
|
- add or preserve scheduled security automation for releasable projects,
|
|
|
|
|
|
|
|
- add or preserve scheduled repository cleanup checks for active projects,
|
|
|
|
|
|
|
|
- add dependency, release dry-run, and template compliance checks when they fit the project,
|
|
|
|
|
|
|
|
- update `docs/agent-handoff.md` when work is interrupted, risky, or multi-session,
|
|
|
|
|
|
|
|
- create focused tracker issues for real follow-up work that is outside the current scope or independently parallelizable, using `docs/agent-handoff.md` when no issue tracker is available,
|
|
|
|
|
|
|
|
- run `git diff --check` before finishing,
|
|
|
|
|
|
|
|
- run the cheapest reliable verification command,
|
|
|
|
|
|
|
|
- poll pushed Gitea workflow runs until success or a concrete blocker.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Scheduled Security Automation
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
`files/security-scan-gitea.yml` provides an optional weekly Gitea workflow for releasable projects.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
It checks:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- stack-specific dependency vulnerabilities,
|
|
|
|
|
|
|
|
- suspicious code patterns,
|
|
|
|
|
|
|
|
- committed secrets or local config files,
|
|
|
|
|
|
|
|
- AI instruction-injection indicators.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The workflow is intentionally conservative. If it fails, an agent should inspect the matches and decide whether they are real risks, documentation examples, or test fixtures. Do not silence the workflow without documenting why.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Scheduled Repository Cleanup
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
`files/repo-cleanup-gitea.yml` provides an optional weekly Gitea workflow for active repositories.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
It reports:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- generated files or dependency folders that were accidentally tracked,
|
|
|
|
|
|
|
|
- large tracked files that may belong in release artifacts or package storage,
|
|
|
|
|
|
|
|
- secret-prone local config files,
|
|
|
|
|
|
|
|
- stale remote branch candidates.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The workflow is intentionally non-destructive. It must not delete files, branches, packages, or releases. Agents should treat failures as maintenance reports, document intentional exceptions, and only remove repository data after explicit user approval.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Dependency Automation
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
`files/dependency-check-gitea.yml` provides a weekly dependency health report.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
It detects common stacks and reports:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- security audit results,
|
|
|
|
|
|
|
|
- outdated Node, Python, Rust, and Go dependencies,
|
|
|
|
|
|
|
|
- Docker base image references that should be reviewed manually.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The workflow does not update lockfiles, create pull requests, or publish packages. Agents should use the report as a starting point for focused dependency update branches.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Release Dry Run
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
`files/release-dry-run-gitea.yml` checks whether a project looks ready to release without creating a release.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
It checks release documents, unresolved placeholders, stack-specific build/test commands where they can be detected, and likely artifact directories. It must not create tags, releases, packages, or uploaded artifacts.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Template Compliance
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
`files/template-compliance-gitea.yml` checks whether a repository still follows the Codex kit baseline.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
It verifies required agent context files, unresolved placeholders, README divider usage for generated READMEs, and recommended workflow presence. Treat failures as maintenance guidance, not as a reason to overwrite project-specific documentation blindly.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Gitea API Token
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
When working with private Gitea repositories, 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
|
|
|
|
```text
|
|
|
|
GET GITEA_SERVER_URL/api/v1/repos/REPOSITORY_OWNER/REPOSITORY_NAME/actions/runs
|
|
|
|
Repository and Organization Access: All (public, private, and limited)
|
|
|
|
Authorization: token GITEA_TOKEN
|
|
|
|
|
|
|
|
|
|
|
|
issue: Read and Write
|
|
|
|
|
|
|
|
package: Read and Write
|
|
|
|
|
|
|
|
repository: Read and Write
|
|
|
|
|
|
|
|
user: Read
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
activitypub: No Access
|
|
|
|
|
|
|
|
admin: No Access
|
|
|
|
|
|
|
|
misc: No Access
|
|
|
|
|
|
|
|
notification: No Access
|
|
|
|
|
|
|
|
organization: No Access
|
|
|
|
```
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
`REGISTRY_TOKEN` is still the intended secret name for CI package publishing inside `.gitea/workflows/build.yml`.
|
|
|
|
These permissions cover:
|
|
|
|
|
|
|
|
|
|
|
|
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
|
|
|
- creating and reading issues,
|
|
|
|
|
|
|
|
- creating and reading releases,
|
|
|
|
|
|
|
|
- uploading package registry files,
|
|
|
|
|
|
|
|
- reading repository metadata,
|
|
|
|
|
|
|
|
- polling workflow runs where the Gitea API allows it.
|
|
|
|
|
|
|
|
|
|
|
|
## Gitea Workflow Loop
|
|
|
|
Use a dedicated bot or automation user when possible.
|
|
|
|
|
|
|
|
|
|
|
|
After pushing commits that trigger a Gitea workflow, Codex agents must keep checking the resulting workflow run before finishing. Poll the run until it reaches a terminal state. If it succeeds, report the successful run. If it fails or is cancelled, inspect the failing job/logs, fix the issue when it is in scope, commit, push, and repeat the check loop for the next run. A fixed failure is not a stopping point; the loop continues after the follow-up push until a workflow succeeds or a concrete out-of-scope blocker is reached. Do not stop after a single in-progress status when the user asked the agent to continue the loop.
|
|
|
|
## Setting Local Tokens
|
|
|
|
|
|
|
|
|
|
|
|
## Follow-up Issues
|
|
|
|
Set a local token for Codex or shell-based API work.
|
|
|
|
|
|
|
|
|
|
|
|
When an agent finds real follow-up work that is outside the current scope or can be worked on independently, it should create a focused tracker issue so humans or other agents can pick it up later or in parallel.
|
|
|
|
Current PowerShell session:
|
|
|
|
|
|
|
|
|
|
|
|
Create issues only for actionable work. Do not create issues for work the agent can safely complete in the current task, duplicate issues, vague reminders, or placeholder TODOs.
|
|
|
|
```powershell
|
|
|
|
|
|
|
|
$env:GITEA_TOKEN = "paste-token-here"
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
Each issue should include:
|
|
|
|
Persist for the current Windows user:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```powershell
|
|
|
|
|
|
|
|
setx GITEA_TOKEN "paste-token-here"
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Open a new terminal after `setx`.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Test repository API access:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```powershell
|
|
|
|
|
|
|
|
$headers = @{ Authorization = "token $env:GITEA_TOKEN" }
|
|
|
|
|
|
|
|
Invoke-RestMethod `
|
|
|
|
|
|
|
|
-Uri "GITEA_SERVER_URL/api/v1/repos/REPOSITORY_OWNER/REPOSITORY_NAME" `
|
|
|
|
|
|
|
|
-Headers $headers
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Test issue access:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```powershell
|
|
|
|
|
|
|
|
Invoke-RestMethod `
|
|
|
|
|
|
|
|
-Uri "GITEA_SERVER_URL/api/v1/repos/REPOSITORY_OWNER/REPOSITORY_NAME/issues?state=open&limit=1" `
|
|
|
|
|
|
|
|
-Headers $headers
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Setting Repository Secrets
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
In Gitea:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
|
|
|
Repository -> Settings -> Actions -> Secrets -> Add Secret
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Add:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
|
|
|
REGISTRY_TOKEN
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Use a token with package write access. If you want workflows to create releases or issues too, add a separate secret:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
|
|
|
GITHUB_SERVER_URL
|
|
|
|
|
|
|
|
GITHUB_REPOSITORY_OWNER
|
|
|
|
|
|
|
|
GITHUB_REPOSITORY
|
|
|
|
|
|
|
|
REGISTRY_TOKEN
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
When those values are unavailable, replace `GITEA_SERVER_URL`, `REPOSITORY_OWNER`, and related placeholders before use.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 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,
|
|
|
|
- observed problem,
|
|
|
|
- impact or reason it matters,
|
|
|
|
- impact,
|
|
|
|
- affected files, commands, or workflows,
|
|
|
|
- affected files or commands,
|
|
|
|
- suggested next steps,
|
|
|
|
- suggested next steps,
|
|
|
|
- verification already performed.
|
|
|
|
- verification already performed.
|
|
|
|
|
|
|
|
|
|
|
|
Never include secrets, tokens, private data, or sensitive logs in public issues. If no issue tracker is available, record the follow-up in `docs/agent-handoff.md` instead.
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
|
|
## Gitea Artifacts And Packages
|
|
|
|
## Release Checklist For A New Repo
|
|
|
|
|
|
|
|
|
|
|
|
Actions artifacts and Gitea packages are separate storage paths.
|
|
|
|
Before the first release of a target project:
|
|
|
|
|
|
|
|
|
|
|
|
- `actions/upload-artifact` makes a workflow-run artifact. It does not create an entry in the Gitea Package Registry.
|
|
|
|
1. Ensure `AGENTS.md` and `.codex/project.md` match the real project.
|
|
|
|
- Use `actions/upload-artifact@v3` for Gitea/Act compatibility unless the target runner is known to support newer artifact actions.
|
|
|
|
2. Replace all placeholders or mark genuinely unknown values as `PENDING`.
|
|
|
|
- To publish a downloadable package, upload it separately to the generic package registry with `curl --upload-file` and a CI secret such as `REGISTRY_TOKEN`.
|
|
|
|
3. Configure `REGISTRY_TOKEN` if packages are published.
|
|
|
|
- Do not place raw build artifact names directly into package URLs. Build tools often emit names with spaces, parentheses, or platform-specific punctuation. Copy artifacts to temporary package files with URL-safe names before uploading.
|
|
|
|
4. Configure `GITEA_TOKEN` only if workflows need issue or release API access.
|
|
|
|
- Keep Codex kit files in source control when they help agents, but exclude them from user-facing release, package, installer, archive, and GitHub/Gitea upload artifacts unless explicitly requested. Typical excluded paths are `AGENTS.md`, `.codex/`, `blueprint.md`, `blueprint.json`, template workflow files, and `docs/agent-handoff.md`.
|
|
|
|
5. Verify SSH push access.
|
|
|
|
- For user-facing downloads, publish both an immutable version such as `PROJECT_VERSION-SHORT_SHA` and a stable `latest` package when the repository owner wants a moving download link.
|
|
|
|
6. Run lint, test, build, and audit commands that exist.
|
|
|
|
- After publishing, verify the actual package URL with an authenticated `HEAD` or lightweight download check. A green build does not always prove the package is visible where users expect it.
|
|
|
|
7. Run `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.
|
|
|
|
|
|
|
|
|
|
|
|
<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
|
|
|
|
|
|
|
|
|
|
|
|
## Agent Prompt For A New Repo
|
|
|
|
When this kit changes, update target repositories conservatively:
|
|
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
```bash
|
|
|
|
Use templates/codex-project/new-repository.md.
|
|
|
|
git status --short
|
|
|
|
Create the Codex repository baseline for this project.
|
|
|
|
git pull --ff-only
|
|
|
|
Adapt placeholders to this repository.
|
|
|
|
|
|
|
|
Keep the existing stack choices minimal and do not add unnecessary frameworks.
|
|
|
|
|
|
|
|
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>
|
|
|
|
Then ask Codex:
|
|
|
|
|
|
|
|
|
|
|
|
## Agent Prompt For An Existing Repo
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
```text
|
|
|
|
Use templates/codex-project/existing-project.md.
|
|
|
|
Update this repository's Codex Agent Repository Kit files from the latest kit.
|
|
|
|
Retrofit the Codex repository baseline.
|
|
|
|
Preserve project-specific README content, commands, release rules, and workflow customizations.
|
|
|
|
Preserve existing project style and README knowledge.
|
|
|
|
Do not overwrite unrelated changes.
|
|
|
|
Add only the files and commands that fit this repo.
|
|
|
|
|
|
|
|
Do not restructure application code unless required.
|
|
|
|
|
|
|
|
Do not create a release.
|
|
|
|
|
|
|
|
```
|
|
|
|
```
|
|
|
|
|
