Compare commits
6 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
2534640e54 | ||
|
|
a4245a1563 | ||
|
|
5ba44fcb03 | ||
|
|
a14ed9a6d9 | ||
|
|
719bc8cca5 | ||
|
|
95b47abf9e |
69
AGENTS.md
Normal file
69
AGENTS.md
Normal file
@@ -0,0 +1,69 @@
|
||||
# Agent Instructions For This Repository
|
||||
|
||||
This file is for Codex agents working on the Codex Agent Repository Kit itself. The public `README.md` is for humans and should stay focused on setup and usage.
|
||||
|
||||
## Start Of Task
|
||||
|
||||
- Check `git status --short`.
|
||||
- If the working tree is clean, run `git pull --ff-only` before editing.
|
||||
- If local changes exist, preserve them and do not overwrite user work.
|
||||
- Conserve context tokens: use `rg`, targeted file reads, and short summaries instead of loading unrelated files or long logs.
|
||||
|
||||
## Runner Policy
|
||||
|
||||
- The only supported build runners are the Gitea global runners `global-runner-1`, `global-runner-2`, and `global-runner-3`.
|
||||
- Use only these Linux runner labels in workflow templates and generated setup instructions: `ubuntu-latest`, `ubuntu-24.04`, and `ubuntu-22.04`.
|
||||
- Never run project builds, tests, audits, package jobs, installers, dependency bootstraps, or release jobs on the local machine. Use the Gitea Ubuntu runners so the user's machine stays clean.
|
||||
- Do not introduce Windows or macOS runners. If a project appears to need Windows-specific tooling, document or implement an open-source Linux-compatible workaround that runs on the Ubuntu runners.
|
||||
- Lightweight local checks are allowed when they do not install dependencies or create build artifacts, for example JSON parsing, manifest path checks, `rg`, `git diff --check`, and API status checks.
|
||||
|
||||
## Repository Purpose
|
||||
|
||||
This repository ships reusable baseline files for other repositories:
|
||||
|
||||
- `files/` contains templates copied into target repositories.
|
||||
- `agent-quickstart.md`, `new-repository.md`, and `existing-project.md` are agent workflows.
|
||||
- `manifest.json` is the source of truth for copy targets and placeholders.
|
||||
- `profiles/` contains stack-specific guidance.
|
||||
|
||||
## Editing Rules
|
||||
|
||||
- Keep repository owner, repository name, project names, and local paths dynamic. This kit intentionally targets `https://git.wilkensxl.de` and SSH port `2222`, so keep that host/port consistent in user-facing setup and Gitea workflow defaults.
|
||||
- Keep workflow examples and generated CI defaults on the supported Ubuntu runner labels only.
|
||||
- If a new placeholder is introduced, update `manifest.json`, the README placeholder list, and placeholder scans in workflow templates.
|
||||
- Keep `README.md` user-facing. Put agent operating rules in this file or the workflow docs.
|
||||
- Keep `files/AGENTS.md` generic; it is copied into target repositories and must not describe this repository specifically.
|
||||
- Do not include secrets, tokens, private data, or sensitive logs in docs, issues, commits, or release notes.
|
||||
|
||||
## Follow-up Work
|
||||
|
||||
- Create focused tracker issues for real follow-up work that is outside the current scope or can be done independently.
|
||||
- Do not create issues for work that can be safely completed in the current task.
|
||||
- If issue creation is unavailable, update `docs/agent-handoff.md` with the blocker and next steps.
|
||||
|
||||
## Verification
|
||||
|
||||
Before committing:
|
||||
|
||||
```powershell
|
||||
Get-Content manifest.json | ConvertFrom-Json | Out-Null
|
||||
Get-Content manifest.schema.json | ConvertFrom-Json | Out-Null
|
||||
Get-Content files\blueprint.json | ConvertFrom-Json | Out-Null
|
||||
git diff --check
|
||||
```
|
||||
|
||||
Also verify:
|
||||
|
||||
- every `manifest.json` copyMap source exists,
|
||||
- every profile path exists,
|
||||
- reusable files contain no private instance defaults such as a specific username or private host,
|
||||
- `README.md` documents every placeholder listed in `manifest.json`.
|
||||
|
||||
## Release
|
||||
|
||||
- Bump `manifest.json` version.
|
||||
- Update `CHANGELOG.md`.
|
||||
- Commit changes.
|
||||
- Create an annotated tag such as `v1.0.2`.
|
||||
- Push `main` and tags.
|
||||
- Create or update the Gitea release when a valid API token is available.
|
||||
29
CHANGELOG.md
29
CHANGELOG.md
@@ -2,6 +2,35 @@
|
||||
|
||||
All notable changes to the Codex Agent Repository Kit are documented here.
|
||||
|
||||
## 1.0.6 - 2026-05-16
|
||||
|
||||
- Added a runner policy that limits project build, test, audit, package, installer, dependency setup, and release work to `global-runner-1`, `global-runner-2`, and `global-runner-3`.
|
||||
- Documented the supported Ubuntu labels: `ubuntu-latest`, `ubuntu-24.04`, and `ubuntu-22.04`.
|
||||
- Clarified that heavy project commands must not run on the user's local machine and that Windows or macOS runners should be replaced with Linux-compatible workflow workarounds.
|
||||
|
||||
## 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.
|
||||
- Documented SSH clone URLs for port `2222` and optional SSH config.
|
||||
- Restored Gitea workflow and README badge defaults for the intended Gitea instance while keeping repository owner and repository name dynamic.
|
||||
|
||||
## 1.0.3 - 2026-05-15
|
||||
|
||||
- Updated repository handoff notes after verifying the refreshed local `GITEA_TOKEN`.
|
||||
- Confirmed live issue creation and Gitea release API access for this repository.
|
||||
|
||||
## 1.0.2 - 2026-05-15
|
||||
|
||||
- Split the repository documentation into a human-facing setup `README.md` and a repository-specific agent instruction file in `AGENTS.md`.
|
||||
- Expanded the human README with full new-repository setup guidance, SSH setup, Gitea token permissions, local token configuration, repository secrets, package publishing, and release checks.
|
||||
- Documented the recommended Gitea token permission matrix shown in the token UI.
|
||||
|
||||
## 1.0.1 - 2026-05-15
|
||||
|
||||
- Added agent guidance to create focused tracker issues for actionable follow-up work that is outside the current scope or independently parallelizable.
|
||||
|
||||
476
README.md
476
README.md
@@ -1,66 +1,140 @@
|
||||
# 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:
|
||||
|
||||
- `agent-quickstart.md`: shortest prompts and decision tree for Codex agents.
|
||||
- `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.
|
||||
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>
|
||||
|
||||
## README Section Divider
|
||||
## What This Kit Adds
|
||||
|
||||
Generated README files should use the shared rainbow section divider between major sections.
|
||||
- `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.
|
||||
|
||||
The divider is configured in `files/blueprint.json` as the `section-line` template:
|
||||
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
||||
|
||||
```md
|
||||
{{ template:section-line }}
|
||||
## 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.
|
||||
|
||||
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
||||
|
||||
## 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`.
|
||||
|
||||
<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:
|
||||
|
||||
```powershell
|
||||
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
|
||||
.
|
||||
|-- 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
|
||||
Profile -> Settings -> SSH / GPG Keys -> Add Key
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```bash
|
||||
git clone ssh://git@git.wilkensxl.de:2222/OWNER/REPOSITORY.git
|
||||
cd REPOSITORY
|
||||
```
|
||||
|
||||
Optional SSH config:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```bash
|
||||
git clone git@git.wilkensxl.de:OWNER/REPOSITORY.git
|
||||
```
|
||||
|
||||
Verify the remote:
|
||||
|
||||
```bash
|
||||
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>
|
||||
|
||||
## Copy Map
|
||||
## Applying The Kit With Codex
|
||||
|
||||
| Template | Destination |
|
||||
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.
|
||||
```
|
||||
|
||||
<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:
|
||||
|
||||
| Template | Target |
|
||||
| --- | --- |
|
||||
| `files/AGENTS.md` | `AGENTS.md` |
|
||||
| `files/project.md` | `.codex/project.md` |
|
||||
@@ -70,30 +144,18 @@ 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/release-dry-run-gitea.yml` | `.gitea/workflows/release-dry-run.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/CHANGELOG.md` | `CHANGELOG.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/release-notes.md` | `docs/release-notes.md` |
|
||||
|
||||
Start with `agent-quickstart.md` when using this kit through Codex.
|
||||
|
||||
`manifest.json` contains the same copy map in a machine-readable format for agents.
|
||||
|
||||
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
|
||||
## Required Placeholder Values
|
||||
|
||||
Replace these after copying:
|
||||
Replace or remove all placeholders before considering a repository ready:
|
||||
|
||||
```text
|
||||
PROJECT_NAME
|
||||
@@ -108,7 +170,6 @@ PROJECT_STACK
|
||||
DOWNLOAD_URL
|
||||
CI_URL
|
||||
RELEASES_URL
|
||||
GITEA_SERVER_URL
|
||||
BUILD_COMMAND
|
||||
TEST_COMMAND
|
||||
LINT_COMMAND
|
||||
@@ -121,172 +182,205 @@ PROJECT_VERSION
|
||||
COMMIT_OR_VERSION
|
||||
```
|
||||
|
||||
If a placeholder does not apply, remove it instead of inventing fake information.
|
||||
|
||||
Agents must not leave unresolved placeholders in copied files unless the value is genuinely unknown and marked as `PENDING`.
|
||||
|
||||
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.
|
||||
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>
|
||||
|
||||
## Agent Responsibilities
|
||||
## Token Overview
|
||||
|
||||
When applying this kit, an agent should:
|
||||
Use separate tokens for separate jobs.
|
||||
|
||||
- read `manifest.json` first,
|
||||
- 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.
|
||||
| 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.
|
||||
|
||||
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
||||
|
||||
## Scheduled Security Automation
|
||||
## Gitea Token Permissions
|
||||
|
||||
`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:
|
||||
For both tokens, choose this repository access level:
|
||||
|
||||
```text
|
||||
GET GITEA_SERVER_URL/api/v1/repos/REPOSITORY_OWNER/REPOSITORY_NAME/actions/runs
|
||||
Authorization: token GITEA_TOKEN
|
||||
Repository and Organization Access: All (public, private, and limited)
|
||||
```
|
||||
|
||||
`REGISTRY_TOKEN` is still the intended secret name for CI package publishing inside `.gitea/workflows/build.yml`.
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
||||
|
||||
## Gitea Workflow Loop
|
||||
## Setting Local Tokens
|
||||
|
||||
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.
|
||||
Set a local token for Codex or shell-based API work.
|
||||
|
||||
## Follow-up Issues
|
||||
Current PowerShell session:
|
||||
|
||||
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.
|
||||
```powershell
|
||||
$env:GITEA_TOKEN = "paste-token-here"
|
||||
```
|
||||
|
||||
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.
|
||||
Persist for the current Windows user:
|
||||
|
||||
Each issue should include:
|
||||
```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 "https://git.wilkensxl.de/api/v1/repos/REPOSITORY_OWNER/REPOSITORY_NAME" `
|
||||
-Headers $headers
|
||||
```
|
||||
|
||||
Test issue access:
|
||||
|
||||
```powershell
|
||||
Invoke-RestMethod `
|
||||
-Uri "https://git.wilkensxl.de/api/v1/repos/REPOSITORY_OWNER/REPOSITORY_NAME/issues?state=open&limit=1" `
|
||||
-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:
|
||||
|
||||
```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.
|
||||
|
||||
<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.
|
||||
|
||||
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 `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.
|
||||
|
||||
An issue should include:
|
||||
|
||||
- observed problem,
|
||||
- impact or reason it matters,
|
||||
- affected files, commands, or workflows,
|
||||
- impact,
|
||||
- affected files or commands,
|
||||
- suggested next steps,
|
||||
- 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.
|
||||
|
||||
## Gitea Artifacts And Packages
|
||||
|
||||
Actions artifacts and Gitea packages are separate storage paths.
|
||||
|
||||
- `actions/upload-artifact` makes a workflow-run artifact. It does not create an entry in the Gitea Package Registry.
|
||||
- Use `actions/upload-artifact@v3` for Gitea/Act compatibility unless the target runner is known to support newer artifact actions.
|
||||
- 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`.
|
||||
- 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.
|
||||
- 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`.
|
||||
- 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.
|
||||
- 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.
|
||||
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>
|
||||
|
||||
## Agent Prompt For A New Repo
|
||||
## Release Checklist For A New Repo
|
||||
|
||||
```text
|
||||
Use templates/codex-project/new-repository.md.
|
||||
Create the Codex repository baseline for this project.
|
||||
Adapt placeholders to this repository.
|
||||
Keep the existing stack choices minimal and do not add unnecessary frameworks.
|
||||
Do not create a release.
|
||||
```
|
||||
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.
|
||||
|
||||
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
||||
|
||||
## Agent Prompt For An Existing Repo
|
||||
## Updating The Kit In A Project
|
||||
|
||||
When this kit changes, update target repositories conservatively:
|
||||
|
||||
```bash
|
||||
git status --short
|
||||
git pull --ff-only
|
||||
```
|
||||
|
||||
Then ask Codex:
|
||||
|
||||
```text
|
||||
Use templates/codex-project/existing-project.md.
|
||||
Retrofit the Codex repository baseline.
|
||||
Preserve existing project style and README knowledge.
|
||||
Add only the files and commands that fit this repo.
|
||||
Do not restructure application code unless required.
|
||||
Do not create a release.
|
||||
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.
|
||||
```
|
||||
|
||||
@@ -12,6 +12,10 @@ Use matching profiles/*.md guidance after detecting the stack.
|
||||
Conserve context tokens: search first, read only relevant files, summarize large outputs, and avoid 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.
|
||||
If local changes exist, do not overwrite them; fetch or report the blocker before editing.
|
||||
Treat global-runner-1, global-runner-2, and global-runner-3 as the only supported build runners.
|
||||
Run project builds, tests, audits, package jobs, installers, dependency setup, and releases only on Gitea Ubuntu runners with ubuntu-latest, ubuntu-24.04, or ubuntu-22.04.
|
||||
Never run those heavy project commands on the user's local machine.
|
||||
Use open-source Linux-compatible workflow workarounds instead of adding Windows or macOS runners.
|
||||
For releasable projects, add or preserve scheduled security automation.
|
||||
For active projects, add or preserve non-destructive scheduled repository cleanup checks.
|
||||
For Codex-maintained projects, add or preserve dependency, release dry-run, and template compliance checks when useful.
|
||||
@@ -23,7 +27,7 @@ Update README.md whenever blueprint.md or blueprint.json changes.
|
||||
Create tracker issues for real, actionable follow-ups that are outside the current scope or independently parallelizable; use docs/agent-handoff.md when no issue tracker is available.
|
||||
Exclude Codex kit metadata from user-facing release, package, installer, archive, and GitHub/Gitea upload artifacts unless explicitly requested.
|
||||
Run git diff --check before finishing.
|
||||
Run the cheapest reliable verification command, or explain why it could not run.
|
||||
Run lightweight local validation before finishing, and run the cheapest reliable project verification through Gitea Actions or explain why runner verification could not run.
|
||||
```
|
||||
|
||||
## New Repository Prompt
|
||||
@@ -38,7 +42,8 @@ Use manifest.json as the source of truth for copy targets.
|
||||
Keep the README generator only if it adds value.
|
||||
When using the README generator, keep the rainbow `{{ template:section-line }}` divider between major sections.
|
||||
Do not create a release.
|
||||
Run the cheapest available verification before finishing.
|
||||
Run lightweight local validation before finishing.
|
||||
Use Gitea Ubuntu runners for project build, test, audit, package, and release commands.
|
||||
```
|
||||
|
||||
## Existing Repository Prompt
|
||||
@@ -52,7 +57,8 @@ Keep commands truthful: do not add commands that cannot run.
|
||||
Use manifest.json as the source of truth for copy targets.
|
||||
When using or adding the README generator, keep the rainbow `{{ template:section-line }}` divider between major sections.
|
||||
Do not create a release.
|
||||
Run the cheapest available verification before finishing.
|
||||
Run lightweight local validation before finishing.
|
||||
Use Gitea Ubuntu runners for project build, test, audit, package, and release commands.
|
||||
```
|
||||
|
||||
## Agent Decision Tree
|
||||
@@ -90,6 +96,10 @@ Does the project have CI?
|
||||
yes -> patch existing workflow
|
||||
no -> add .gitea/workflows/build.yml only when commands are known
|
||||
|
||||
Does any workflow use Windows, macOS, local-machine builds, or unsupported runner labels?
|
||||
yes -> replace it with Gitea Ubuntu runner usage on ubuntu-latest, ubuntu-24.04, or ubuntu-22.04; if a platform-specific step is needed, implement a Linux-compatible workaround
|
||||
no -> continue
|
||||
|
||||
Is the project releasable or does it process user/secrets/config data?
|
||||
yes -> add .gitea/workflows/security-scan.yml or preserve equivalent scheduled security automation
|
||||
no -> document why scheduled security automation is not needed
|
||||
@@ -152,7 +162,7 @@ Is this a private Gitea repo with Actions?
|
||||
|
||||
Did you push a commit that should trigger a workflow?
|
||||
yes -> poll the workflow run until success; if it fails, inspect logs, fix in scope, push again, and keep looping after the follow-up push
|
||||
no -> finish with local verification status
|
||||
no -> finish with lightweight local validation status and explain why runner verification was not required or not available
|
||||
```
|
||||
|
||||
## Minimal File Set
|
||||
|
||||
@@ -1,37 +1,40 @@
|
||||
# Agent Handoff
|
||||
|
||||
Use this file for current repository follow-ups when tracker issues cannot be created.
|
||||
Use this file for current repository follow-ups when tracker issues cannot be created or when a compact session summary is useful.
|
||||
|
||||
## Current State
|
||||
|
||||
The kit now includes guidance for creating focused tracker issues for actionable follow-up work.
|
||||
The kit includes guidance for creating focused tracker issues for actionable follow-up work. The local `GITEA_TOKEN` has been refreshed and verified.
|
||||
|
||||
## Changes Made
|
||||
|
||||
- Added issue creation guidance to the agent rules, quickstart, README, new/existing repository workflows, and manifest.
|
||||
- Added handoff guidance for cases where issue creation is unavailable or too sensitive.
|
||||
- Updated the kit version to `1.0.1`.
|
||||
- Updated the kit version to `1.0.2`.
|
||||
- Created a live follow-up issue after token access was restored.
|
||||
- Created the Gitea release entry for `v1.0.2`.
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
| --- | --- |
|
||||
| Issue creation test | Blocked: Gitea API returned `invalid username, password or token` |
|
||||
| Issue creation test | Passed: created issue #1 |
|
||||
| Release API test | Passed: created release entry for `v1.0.2` |
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Whether the local `GITEA_TOKEN` should be refreshed for future issue/release automation.
|
||||
- None at this time.
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Create a focused tracker issue for adding a reusable follow-up issue template once issue API access is available.
|
||||
- Use issue #1 to track adding a reusable follow-up issue template.
|
||||
|
||||
## Follow-up Issues
|
||||
|
||||
| Issue | Status |
|
||||
| --- | --- |
|
||||
| Add reusable issue template for agent follow-ups | Pending issue tracker access |
|
||||
| #1 Add reusable issue template for agent follow-ups | Open |
|
||||
|
||||
## Risks
|
||||
|
||||
- Issue automation cannot be fully validated until a valid token is available.
|
||||
- No known token blocker remains after the refreshed token test.
|
||||
|
||||
@@ -35,6 +35,8 @@ If local changes exist, do not overwrite them. Fetch or report the blocker befor
|
||||
|
||||
Conserve context tokens while inspecting: start with targeted searches and file lists, then read only files that affect the retrofit decision. Do not load generated folders, dependency folders, build outputs, or full logs unless they are directly relevant.
|
||||
|
||||
Treat `global-runner-1`, `global-runner-2`, and `global-runner-3` as the only supported build runners. Project builds, tests, audits, package jobs, installers, dependency setup, and releases must run on Gitea Ubuntu runners with `ubuntu-latest`, `ubuntu-24.04`, or `ubuntu-22.04`, not on the user's local machine. If tooling looks Windows-specific, use an open-source Linux-compatible workaround instead of adding a Windows runner.
|
||||
|
||||
Read:
|
||||
|
||||
```text
|
||||
@@ -122,7 +124,7 @@ The default section divider is the rainbow line from `andreasbm/readme`, configu
|
||||
If CI already exists:
|
||||
|
||||
- add missing audit/check steps,
|
||||
- keep existing runner labels,
|
||||
- replace unsupported runner labels with `ubuntu-latest`, `ubuntu-24.04`, or `ubuntu-22.04`,
|
||||
- keep existing artifact names unless they are broken,
|
||||
- avoid changing deployment behavior.
|
||||
|
||||
@@ -180,8 +182,9 @@ Use the stack-native audit command when possible:
|
||||
Before final response:
|
||||
|
||||
- run `git diff --check`,
|
||||
- run the smallest reliable verification command,
|
||||
- if using Gitea Actions, poll the pushed workflow run until it reaches a terminal state; for private Gitea repositories, use a locally set `GITEA_TOKEN` and `GITEA_SERVER_URL` for read-only API status checks when available,
|
||||
- run only lightweight local validation that does not install dependencies or create build artifacts,
|
||||
- run the smallest reliable project verification command through Gitea Actions on a supported Ubuntu runner,
|
||||
- if using Gitea Actions, poll the pushed workflow run until it reaches a terminal state; for private Gitea repositories on `https://git.wilkensxl.de`, use a locally set `GITEA_TOKEN` for read-only API status checks when available,
|
||||
- if the pushed workflow fails or is cancelled, inspect the failing job/logs, fix in scope, push again, and repeat the workflow check loop; fixing and pushing is not a stopping point,
|
||||
- list files changed,
|
||||
- mention any skipped checks,
|
||||
|
||||
@@ -13,6 +13,10 @@ PROJECT_NAME: PROJECT_DESCRIPTION
|
||||
- Prefer existing project patterns over new abstractions.
|
||||
- Keep changes scoped to the user's request.
|
||||
- Do not commit secrets, `.env` files, private keys, certificates, or tokens.
|
||||
- Treat `global-runner-1`, `global-runner-2`, and `global-runner-3` as the only available build runners.
|
||||
- Run project builds, tests, audits, package jobs, installers, dependency setup, and releases only on Gitea Ubuntu runners with `ubuntu-latest`, `ubuntu-24.04`, or `ubuntu-22.04`.
|
||||
- Do not run those heavy project commands on the user's local machine. Local checks are limited to lightweight reads and validation that do not install dependencies or create build artifacts.
|
||||
- Do not add Windows or macOS runners. Use open-source Linux-compatible tooling or workflow workarounds that run on the Ubuntu runners.
|
||||
- Do not rewrite history or run destructive git commands unless explicitly requested.
|
||||
- Do not create a release unless explicitly requested.
|
||||
- At the start of every user-requested task, briefly check the repository for upstream updates and apply them immediately with a safe fast-forward pull when the working tree is clean. If local changes exist, do not overwrite them; fetch or report the blocker before editing.
|
||||
@@ -46,6 +50,8 @@ AUDIT_COMMAND
|
||||
|
||||
If a command is missing, inspect the project and document the closest safe alternative in `.codex/project.md`.
|
||||
|
||||
Run these commands through Gitea Actions on the configured Ubuntu runners, not on the user's local machine.
|
||||
|
||||
Keep `.codex/project.md` and this `AGENTS.md` aligned when commands, artifact paths, or release rules change.
|
||||
|
||||
## Artifacts
|
||||
@@ -80,7 +86,7 @@ ARTIFACT_NAME
|
||||
## Finish Checklist
|
||||
|
||||
- `git diff --check` passes.
|
||||
- The cheapest reliable verification command has been run, or the reason it could not be run is documented.
|
||||
- Lightweight local validation has passed, and the cheapest reliable runner-based verification command has been run through Gitea Actions or the reason it could not be run is documented.
|
||||
- README, changelog, security review, and release checklist are updated when the change touches release behavior.
|
||||
- `docs/agent-handoff.md` is updated when work is interrupted, risky, or spans multiple sessions.
|
||||
- Independent follow-up work has tracker issues, or `docs/agent-handoff.md` explains why issues could not be created.
|
||||
|
||||
@@ -7,11 +7,13 @@
|
||||
- Do not commit secrets, generated credentials, local `.env` files, or private keys.
|
||||
- Do not create releases unless explicitly requested.
|
||||
- Preserve unrelated user changes.
|
||||
- Use only the configured Gitea Ubuntu runners for project builds, tests, audits, packages, installers, dependency setup, and releases. Do not run those commands on the local machine.
|
||||
- Do not add Windows or macOS runners; use Linux-compatible workarounds that run on `ubuntu-latest`, `ubuntu-24.04`, or `ubuntu-22.04`.
|
||||
- Create focused issues for real follow-up work that is outside the current change or can be worked on independently. Do not put secrets, tokens, private data, or sensitive logs in public issues.
|
||||
|
||||
## Before Committing
|
||||
|
||||
Run the cheapest reliable verification commands for this project:
|
||||
Run the cheapest reliable project verification commands through Gitea Actions:
|
||||
|
||||
```bash
|
||||
LINT_COMMAND
|
||||
@@ -25,7 +27,7 @@ Also run:
|
||||
git diff --check
|
||||
```
|
||||
|
||||
If a command cannot run, document why in the final response or handoff notes.
|
||||
Local checks should stay lightweight and must not install dependencies or create build artifacts. If a runner-based command cannot run, document why in the final response or handoff notes.
|
||||
|
||||
## Pull Requests
|
||||
|
||||
|
||||
@@ -6,12 +6,12 @@
|
||||
{
|
||||
"alt": "Build",
|
||||
"img": "https://img.shields.io/badge/build-Gitea%20Runner-2563eb",
|
||||
"url": "CI_URL"
|
||||
"url": "https://git.wilkensxl.de/REPOSITORY_OWNER/REPOSITORY_NAME/actions"
|
||||
},
|
||||
{
|
||||
"alt": "Version",
|
||||
"img": "https://img.shields.io/badge/version-0.1.0-111827",
|
||||
"url": "RELEASES_URL"
|
||||
"url": "https://git.wilkensxl.de/REPOSITORY_OWNER/REPOSITORY_NAME/releases"
|
||||
}
|
||||
],
|
||||
"headingPrefix": {
|
||||
|
||||
@@ -58,7 +58,7 @@ jobs:
|
||||
if [ -z "${repository_owner}" ] || [ "${repository_owner}" = "${GITHUB_REPOSITORY}" ]; then
|
||||
repository_owner="REPOSITORY_OWNER"
|
||||
fi
|
||||
gitea_server="${GITHUB_SERVER_URL:-GITEA_SERVER_URL}"
|
||||
gitea_server="${GITHUB_SERVER_URL:-https://git.wilkensxl.de}"
|
||||
gitea_server="${gitea_server%/}"
|
||||
package_dir="package-registry"
|
||||
latest_url="${gitea_server}/api/packages/${repository_owner}/generic/${package_name}/latest"
|
||||
|
||||
@@ -24,6 +24,10 @@ README_COMMAND
|
||||
|
||||
If a command does not exist, document the closest safe alternative. Do not invent commands that cannot run.
|
||||
|
||||
Project build, test, audit, package, installer, dependency setup, and release commands must run on Gitea Ubuntu runners only. Supported labels are `ubuntu-latest`, `ubuntu-24.04`, and `ubuntu-22.04` on `global-runner-1`, `global-runner-2`, and `global-runner-3`.
|
||||
|
||||
Local checks are limited to lightweight validation that does not install dependencies or create build artifacts.
|
||||
|
||||
## Stack
|
||||
|
||||
```text
|
||||
@@ -63,11 +67,11 @@ ARTIFACT_NAME
|
||||
Before a release:
|
||||
|
||||
1. run the release checklist,
|
||||
2. verify CI is green,
|
||||
2. verify CI is green on a supported Gitea Ubuntu runner,
|
||||
3. verify download links,
|
||||
4. update README and changelog,
|
||||
5. verify release artifacts exclude Codex kit metadata such as `AGENTS.md`, `.codex/`, `blueprint.md`, `blueprint.json`, template workflows, and agent handoff notes unless the user explicitly wants those shipped,
|
||||
6. create a tag,
|
||||
7. create the release.
|
||||
7. create the release through Gitea Actions or the Gitea API.
|
||||
|
||||
Do not create releases unless the user explicitly asks for a release.
|
||||
|
||||
@@ -9,9 +9,11 @@
|
||||
## Quality
|
||||
|
||||
- [ ] Working tree is clean.
|
||||
- [ ] Lint/type checks pass.
|
||||
- [ ] Tests pass or missing tests are documented.
|
||||
- [ ] Build succeeds in CI.
|
||||
- [ ] Lightweight local validation passes without installing dependencies or creating build artifacts.
|
||||
- [ ] Lint/type checks pass on a Gitea Ubuntu runner.
|
||||
- [ ] Tests pass on a Gitea Ubuntu runner or missing tests are documented.
|
||||
- [ ] Build succeeds in CI on `ubuntu-latest`, `ubuntu-24.04`, or `ubuntu-22.04`.
|
||||
- [ ] No project build, test, audit, package, installer, dependency setup, or release command was run on the local machine.
|
||||
|
||||
## Security
|
||||
|
||||
@@ -32,5 +34,5 @@
|
||||
|
||||
- [ ] Git tag created.
|
||||
- [ ] Release notes written.
|
||||
- [ ] Release published.
|
||||
- [ ] Release published from Gitea Actions or through the Gitea API, not by running local release tooling.
|
||||
- [ ] Post-release download smoke test completed.
|
||||
|
||||
@@ -34,7 +34,7 @@ jobs:
|
||||
done
|
||||
|
||||
placeholder_paths=(README.md AGENTS.md .codex docs .gitea)
|
||||
placeholder_pattern='PROJECT_NAME|PROJECT_DESCRIPTION|REPOSITORY_OWNER|REPOSITORY_NAME|PACKAGE_NAME|ARTIFACT_NAME|ARTIFACT_OUTPUT_DIRECTORY|DOWNLOAD_URL|CI_URL|RELEASES_URL|GITEA_SERVER_URL|BUILD_COMMAND|TEST_COMMAND|LINT_COMMAND|AUDIT_COMMAND|COMMIT_OR_VERSION'
|
||||
placeholder_pattern='PROJECT_NAME|PROJECT_DESCRIPTION|REPOSITORY_OWNER|REPOSITORY_NAME|PACKAGE_NAME|ARTIFACT_NAME|ARTIFACT_OUTPUT_DIRECTORY|DOWNLOAD_URL|CI_URL|RELEASES_URL|BUILD_COMMAND|TEST_COMMAND|LINT_COMMAND|AUDIT_COMMAND|COMMIT_OR_VERSION'
|
||||
|
||||
for path in "${placeholder_paths[@]}"; do
|
||||
[ -e "$path" ] || continue
|
||||
|
||||
@@ -54,7 +54,7 @@ jobs:
|
||||
run: |
|
||||
found=0
|
||||
paths=(AGENTS.md README.md SECURITY.md CHANGELOG.md .codex docs .gitea blueprint.md blueprint.json)
|
||||
pattern='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|GITEA_SERVER_URL|BUILD_COMMAND|TEST_COMMAND|LINT_COMMAND|AUDIT_COMMAND|README_COMMAND|INSTALL_COMMAND|DEV_COMMAND|PACKAGE_MANAGER|PROJECT_VERSION|COMMIT_OR_VERSION'
|
||||
pattern='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'
|
||||
|
||||
for path in "${paths[@]}"; do
|
||||
[ -e "$path" ] || continue
|
||||
|
||||
@@ -1,12 +1,15 @@
|
||||
{
|
||||
"name": "codex-agent-repository-kit",
|
||||
"version": "1.0.1",
|
||||
"version": "1.0.6",
|
||||
"description": "Universal repository baseline for Codex-assisted projects.",
|
||||
"agentResponsibilities": [
|
||||
"Read manifest.json before copying files.",
|
||||
"Use copyMap target paths unless the repository already has an equivalent convention.",
|
||||
"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.",
|
||||
"Use only the configured Gitea Ubuntu runners global-runner-1, global-runner-2, and global-runner-3 for project builds, tests, audits, package jobs, installers, dependency setup, and releases.",
|
||||
"Never run heavy project commands on the user's local machine; keep local verification limited to lightweight checks that do not install dependencies or create build artifacts.",
|
||||
"Do not add Windows or macOS runners; use open-source Linux-compatible workarounds that run on ubuntu-latest, ubuntu-24.04, or ubuntu-22.04.",
|
||||
"Check git status before editing and before finishing.",
|
||||
"Preserve unrelated user changes.",
|
||||
"Replace applicable placeholders and remove non-applicable placeholder sections.",
|
||||
@@ -18,7 +21,7 @@
|
||||
"Add or preserve non-destructive scheduled repository cleanup checks for active projects.",
|
||||
"Add or preserve dependency, release dry-run, and template compliance checks when they fit the project.",
|
||||
"Run git diff --check before finishing.",
|
||||
"Run the cheapest reliable verification command or document why it could not run.",
|
||||
"Run lightweight local validation before finishing, then use Gitea Actions for project verification or document why runner verification could not run.",
|
||||
"After pushing workflow-triggering commits, poll Gitea workflow runs until success or a concrete blocker."
|
||||
],
|
||||
"securityAutomation": {
|
||||
@@ -195,7 +198,6 @@
|
||||
"DOWNLOAD_URL",
|
||||
"CI_URL",
|
||||
"RELEASES_URL",
|
||||
"GITEA_SERVER_URL",
|
||||
"BUILD_COMMAND",
|
||||
"TEST_COMMAND",
|
||||
"LINT_COMMAND",
|
||||
|
||||
@@ -32,6 +32,8 @@ If local changes exist, do not overwrite them. Fetch or report the blocker befor
|
||||
|
||||
Conserve context tokens while inspecting: start with targeted searches and file lists, then read only files that affect the baseline decision. Do not load generated folders, dependency folders, build outputs, or full logs unless they are directly relevant.
|
||||
|
||||
Treat `global-runner-1`, `global-runner-2`, and `global-runner-3` as the only supported build runners. Project builds, tests, audits, package jobs, installers, dependency setup, and releases must run on Gitea Ubuntu runners with `ubuntu-latest`, `ubuntu-24.04`, or `ubuntu-22.04`, not on the user's local machine. If tooling looks Windows-specific, use an open-source Linux-compatible workaround instead of adding a Windows runner.
|
||||
|
||||
Identify:
|
||||
|
||||
- repository name,
|
||||
@@ -95,7 +97,6 @@ PROJECT_STACK
|
||||
DOWNLOAD_URL
|
||||
CI_URL
|
||||
RELEASES_URL
|
||||
GITEA_SERVER_URL
|
||||
BUILD_COMMAND
|
||||
TEST_COMMAND
|
||||
LINT_COMMAND
|
||||
@@ -174,6 +175,8 @@ build
|
||||
upload artifacts
|
||||
```
|
||||
|
||||
Use only the supported Gitea Ubuntu runner labels. Do not add Windows, macOS, self-hosted local-machine, or undocumented runner labels.
|
||||
|
||||
Only publish artifacts to a package registry when the artifact names and credentials are known. `actions/upload-artifact` creates a workflow-run artifact, not a Gitea Package Registry package. If users need a package/download entry, add a separate generic package upload step with `REGISTRY_TOKEN`, copy artifacts to URL-safe filenames before upload, and verify the final package URL after the workflow succeeds.
|
||||
|
||||
Keep Codex kit files tracked in the source repository when they help agents, but exclude them from user-facing release, package, installer, archive, and GitHub/Gitea upload artifacts unless the user explicitly wants repository-maintenance files shipped. Typical excluded paths are `AGENTS.md`, `.codex/`, `blueprint.md`, `blueprint.json`, template workflow files, and `docs/agent-handoff.md`.
|
||||
@@ -194,10 +197,10 @@ When the setup reveals real follow-up work that is outside the current scope or
|
||||
|
||||
Before final response:
|
||||
|
||||
- run formatting or validation if available,
|
||||
- run the cheapest reliable verification command,
|
||||
- run lightweight local validation if available and it does not install dependencies or create build artifacts,
|
||||
- run the cheapest reliable project verification command through Gitea Actions on a supported Ubuntu runner,
|
||||
- check `git diff --check`,
|
||||
- if using Gitea Actions, poll the pushed workflow run until it reaches a terminal state; for private Gitea repositories, use a locally set `GITEA_TOKEN` and `GITEA_SERVER_URL` for read-only API status checks when available,
|
||||
- if using Gitea Actions, poll the pushed workflow run until it reaches a terminal state; for private Gitea repositories on `https://git.wilkensxl.de`, use a locally set `GITEA_TOKEN` for read-only API status checks when available,
|
||||
- if the pushed workflow fails or is cancelled, inspect the failing job/logs, fix in scope, push again, and repeat the workflow check loop; fixing and pushing is not a stopping point,
|
||||
- summarize changed files,
|
||||
- do not create a release unless explicitly requested.
|
||||
|
||||
Reference in New Issue
Block a user