https://github.com/goonobu-dot/codex-maintainer-action
GitHub Action that runs codex-maintainer-kit to generate OSS maintenance briefs, task queues, and artifacts.
https://github.com/goonobu-dot/codex-maintainer-action
codex github-actions maintainer open-source openai oss-tools
Last synced: about 1 month ago
JSON representation
GitHub Action that runs codex-maintainer-kit to generate OSS maintenance briefs, task queues, and artifacts.
- Host: GitHub
- URL: https://github.com/goonobu-dot/codex-maintainer-action
- Owner: goonobu-dot
- License: mit
- Created: 2026-06-15T01:19:08.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-06-15T14:30:23.000Z (about 1 month ago)
- Last Synced: 2026-06-15T16:17:31.234Z (about 1 month ago)
- Topics: codex, github-actions, maintainer, open-source, openai, oss-tools
- Language: Python
- Size: 16.6 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Codex Maintainer Action
GitHub Action wrapper for [`codex-maintainer-kit`](https://github.com/goonobu-dot/codex-maintainer-kit).
It runs the CLI in GitHub Actions and generates Codex-ready maintenance artifacts for open source repositories:
- `OSS_MAINTENANCE_AUDIT.md`
- `MAINTAINER_BRIEF.md`
- `CODEX_TASKS.md`
- `codex-tasks.json`
- `CODEX_REVIEW.md`
The action also writes a GitHub Actions job summary with the audit score, review risk, and artifact paths. The intent is human-reviewed OSS maintenance. The action surfaces work, drafts task queues, and stores artifacts. It does not auto-merge, auto-release, or grant Codex write access.
## Usage
```yaml
name: Codex maintenance
on:
workflow_dispatch:
schedule:
- cron: "0 9 * * 1"
jobs:
codex-maintenance:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: goonobu-dot/codex-maintainer-action@v0.2.0
with:
output-dir: codex-maintenance
```
## Inputs
| Input | Default | Description |
| --- | --- | --- |
| `repo-path` | `.` | Repository path to inspect. |
| `output-dir` | `codex-maintenance` | Directory where generated files are written. |
| `kit-ref` | `v0.3.0` | Branch, tag, or commit of `codex-maintainer-kit` to install. |
| `comment-pr` | `false` | Post a short pull request comment with artifact paths and maintainer review guidance. |
| `upload-artifact` | `true` | Upload generated files as an artifact. |
| `artifact-name` | `codex-maintenance` | Artifact name. |
## Outputs
| Output | Description |
| --- | --- |
| `output-dir` | Directory containing generated maintenance files. |
| `maintenance-audit` | Path to `OSS_MAINTENANCE_AUDIT.md`. |
| `maintainer-brief` | Path to `MAINTAINER_BRIEF.md`. |
| `codex-tasks` | Path to `CODEX_TASKS.md`. |
| `codex-tasks-json` | Path to `codex-tasks.json`. |
| `codex-review` | Path to `CODEX_REVIEW.md`. |
## Pull Request Comment Mode
PR comments are disabled by default. Enable them only on pull request workflows where you want maintainers to see the generated artifact paths directly in the conversation:
```yaml
permissions:
contents: read
pull-requests: write
on:
pull_request:
jobs:
codex-maintenance:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: goonobu-dot/codex-maintainer-action@v0.2.0
with:
comment-pr: "true"
output-dir: codex-maintenance
```
The comment is intentionally short. It points to generated artifacts and repeats the human review rule instead of pasting full reports into the PR.
## Choosing `kit-ref`
`kit-ref` controls which `codex-maintainer-kit` release the action installs.
Use a pinned release tag for normal repositories:
```yaml
with:
kit-ref: v0.3.0
```
Pinned tags make workflow output stable and easier to review. Use a full commit SHA when you need maximum reproducibility for regulated or high-trust maintenance workflows. Use `main` only when testing the newest CLI behavior before a release; avoid `main` in production workflows because generated output can change without warning.
## Relationship To Codex Maintainer Kit
`codex-maintainer-kit` is the CLI. This repository is the GitHub-native runner.
Use the CLI locally when a maintainer wants to inspect a repository by hand. Use this action when a repository should regularly produce maintenance artifacts through GitHub Actions.
## Security Model
- No secrets are required.
- The action reads the checked-out repository and writes generated files to `output-dir`.
- Generated files are uploaded as workflow artifacts when `upload-artifact` is `true`.
- Pull request comments are posted only when `comment-pr` is `true` and the workflow grants `pull-requests: write`.
- A human maintainer reviews generated tasks before opening PRs or merging changes.
## Development
Run local contract tests:
```bash
python3 -m pytest -p no:cacheprovider tests -q
```
## License
MIT