Compare commits

..
Author SHA1 Message Date
grm-ci-bot 2acc1c0eb6 release: v0.23.0 [skip ci] 2026-08-28 16:15:05 +00:00
kireto a31af2e236 GRM-162: feat: add pre-cache timer, force_pull, and Docker socket options to runner config
Post-merge / detect-and-configure (push) Successful in 1m2s
Post-merge / release-and-maintain (push) Successful in 3m0s
2026-08-28 16:11:34 +00:00
gitea-actions-bot 68a763b942 chore: update badge URLs to commit 9ae4b38a [skip ci] 2026-08-27 16:08:53 +00:00
emo d9dae396bc GRM-172: docs: document pre-pull image usage guidelines
Post-merge / detect-and-configure (push) Successful in 2m52s
Post-merge / release-and-maintain (push) Successful in 1m13s
Co-authored-by: emo <emo@oblachno.com>
2026-08-27 16:04:45 +00:00
gitea-actions-bot 7816733e5e chore: update badge URLs to commit 8dd25f8c [skip ci] 2026-08-26 20:38:17 +00:00
grm-ci-bot 1287785bb8 release: v0.22.1 [skip ci] 2026-08-26 20:37:31 +00:00
emil eabd7059d9 GRM-168: chore: bump devx from v0.51.0 to v0.51.9
Post-merge / detect-and-configure (push) Successful in 2m2s
Post-merge / release-and-maintain (push) Successful in 3m7s
Co-authored-by: emil User <emil.simeonov@tutanota.com>
2026-08-26 20:33:06 +00:00
gitea-actions-bot 9e771096e7 chore: update badge URLs to commit 5ba6b90d [skip ci] 2026-08-26 20:20:55 +00:00
emil 99413d3ead GRM-171: fix: use kireto token for auto-merge approval review
Post-merge / detect-and-configure (push) Successful in 2m0s
Post-merge / release-and-maintain (push) Successful in 1m9s
Co-authored-by: emil User <emil.simeonov@tutanota.com>
2026-08-26 20:17:43 +00:00
emo e6e3ba352f GRM-167: deps: bump devx from v0.50.2 to v0.51.0
Post-merge / detect-and-configure (push) Failing after 3m12s
Post-merge / release-and-maintain (push) Skipped
Co-authored-by: emo <emo@oblachno.com>
2026-08-25 17:01:08 +00:00
gitea-actions-bot 13aab5539a chore: update badge URLs to commit a53d44ef [skip ci] 2026-08-25 01:44:10 +00:00
grm-ci-bot 998e438270 release: v0.22.0 [skip ci] 2026-08-25 01:43:34 +00:00
emil eab452ec04 GRM-165: feat: adopt spec-driven CI gates, create_dependency_pr, and pr-review skill
Post-merge / detect-and-configure (push) Successful in 1m2s
Post-merge / release-and-maintain (push) Successful in 2m14s
Co-authored-by: emil User <emil.simeonov@tutanota.com>
2026-08-25 01:40:50 +00:00
gitea-actions-bot 9609ef2505 chore: update badge URLs to commit 1dce7264 [skip ci] 2026-08-24 03:17:49 +00:00
grm-ci-bot 97e7687e25 release: v0.21.1 [skip ci] 2026-08-24 03:17:13 +00:00
emil f672da1753 GRM-163: fix: use runuser for systemctl --user tasks in gitea_runner role
Post-merge / detect-and-configure (push) Successful in 1m3s
Post-merge / release-and-maintain (push) Successful in 1m27s
Co-authored-by: emil User <emil.simeonov@tutanota.com>
2026-08-24 03:15:17 +00:00
gitea-actions-bot d6549de2e0 chore: update badge URLs to commit a9578eae [skip ci] 2026-08-09 22:51:32 +00:00
grm-ci-bot dc4bb0936d release: v0.21.0 [skip ci] 2026-08-09 22:50:47 +00:00
emo 52477e558a GRM-161: feat(healthcheck): add two-tier disk prune with critical threshold
Post-merge / detect-and-configure (push) Successful in 2m29s
Post-merge / release-and-maintain (push) Successful in 2m14s
2026-08-09 22:46:48 +00:00
gitea-actions-bot 28214de583 chore: update badge URLs to commit 918ffe7d [skip ci] 2026-08-09 11:16:42 +00:00
grm-ci-bot 7fd023d192 release: v0.20.0 [skip ci] 2026-08-09 11:16:01 +00:00
emil 2ffedaa793 GRM-159: feat(healthcheck): add two-tier disk prune with critical threshold
Post-merge / detect-and-configure (push) Successful in 1m38s
Post-merge / release-and-maintain (push) Successful in 2m26s
Co-authored-by: emil User <emil.simeonov@tutanota.com>
2026-08-09 11:12:37 +00:00
gitea-actions-bot e7b2d4e6af chore: update badge URLs to commit e0611a67 [skip ci] 2026-08-08 23:39:03 +00:00
grm-ci-bot bda2af91bc release: v0.19.0 [skip ci] 2026-08-08 23:38:33 +00:00
emil c72dc97f63 GRM-158: feat: use Gitea mirror for Ansible collection installs
Post-merge / detect-and-configure (push) Successful in 1m8s
Post-merge / release-and-maintain (push) Successful in 1m9s
Co-authored-by: emil User <emil.simeonov@tutanota.com>
2026-08-08 23:36:41 +00:00
gitea-actions-bot db9fb6f162 chore: update badge URLs to commit d9e3ee2e [skip ci] 2026-08-06 19:16:49 +00:00
grm-ci-bot d102453960 release: v0.18.8 [skip ci] 2026-08-06 19:16:18 +00:00
kireto 42409d9e47 GRM-160: fix: pin containerd.io to compatible version for Docker 28.x
Post-merge / detect-and-configure (push) Successful in 3m19s
Post-merge / release-and-maintain (push) Successful in 1m19s
Co-authored-by: kireto <kireto@oblachno.com>
2026-08-06 19:12:07 +00:00
gitea-actions-bot 91e880f05c chore: update badge URLs to commit 7b6c9f92 [skip ci] 2026-08-06 09:31:04 +00:00
grm-ci-bot 2d2eaa3291 release: v0.18.7 [skip ci] 2026-08-06 09:30:18 +00:00
kireto 8176a62885 GRM-159: fix: move StartLimit to [Unit] and make prune timer reload conditional
Post-merge / detect-and-configure (push) Successful in 3m49s
Post-merge / release-and-maintain (push) Successful in 3m43s
Co-authored-by: kireto <kireto@oblachno.com>
2026-08-06 09:23:29 +00:00
gitea-actions-bot 443756a508 chore: update badge URLs to commit 36201d0d [skip ci] 2026-08-06 00:00:05 +00:00
grm-ci-bot 340222e041 release: v0.18.6 [skip ci] 2026-08-05 23:59:22 +00:00
kireto 179e47bbb2 GRM-158: fix: pre-configure daemon.json before rootless setuptool + add DBUS_SESSION_BUS_ADDRESS
Post-merge / detect-and-configure (push) Successful in 1m2s
Post-merge / release-and-maintain (push) Successful in 1m38s
Co-authored-by: kireto <kireto@oblachno.com>
2026-08-05 23:57:25 +00:00
gitea-actions-bot 68d16577b3 chore: update badge URLs to commit 169df915 [skip ci] 2026-08-05 20:21:20 +00:00
grm-ci-bot 38607d9f29 release: v0.18.5 [skip ci] 2026-08-05 20:20:43 +00:00
kireto 90139b306b GRM-157: fix: pin Docker 28.x + disable containerd snapshotter + tune prune/disk
Post-merge / detect-and-configure (push) Successful in 1m8s
Post-merge / release-and-maintain (push) Successful in 1m31s
Co-authored-by: kireto <kireto@oblachno.com>
2026-08-05 20:18:38 +00:00
gitea-actions-bot dd475bec0d chore: update badge URLs to commit 83a5b577 [skip ci] 2026-08-05 13:53:01 +00:00
grm-ci-bot 0f0ada3576 release: v0.18.4 [skip ci] 2026-08-05 13:52:28 +00:00
emo 185e41c49e GRM-156: fix: harden rootless Docker daemon resilience on CI runners
Post-merge / detect-and-configure (push) Successful in 1m9s
Post-merge / release-and-maintain (push) Successful in 1m15s
2026-08-05 13:50:34 +00:00
gitea-actions-bot 103741b3ab chore: update badge URLs to commit 7136903b [skip ci] 2026-08-04 14:04:34 +00:00
grm-ci-bot b770d1debf release: v0.18.3 [skip ci] 2026-08-04 14:03:59 +00:00
gitea-admin 2f11489be0 GRM-2: fix: switch default network driver to slirp4netns (pasta TCP RST bug)
Post-merge / detect-and-configure (push) Successful in 1m8s
Post-merge / release-and-maintain (push) Successful in 1m22s
Co-authored-by: oblachno Admin <admin@oblachno.oblachno.fyi>
2026-08-04 14:01:56 +00:00
35 changed files with 1158 additions and 404 deletions
+19 -1
View File
@@ -12,7 +12,6 @@ Quick reference for devx tools when working on this repo.
| Check CI status | `make devx-pr-status` or `make devx-pr-status PR=42 WAIT=1` |
| Fetch CI failure logs | `make devx-pr-logs` or `make devx-pr-logs PR=42 JOB=quality TAIL=50` |
| Add ready-to-merge label | `make devx-pr-label` or `make devx-pr-label PR=42` |
| Post PR review | `make devx-pr-review PR=42 EVENT=APPROVE BODY="..." CHECKLIST=1,2,3,4,5,6,7,8,9,10,11,12,13` |
| Rebase current branch | `make rebase` |
| Rebase PR via API | `make pr-rebase` or `make pr-rebase PR=42` |
@@ -30,6 +29,25 @@ CI runs a `pre-merge-check` job early (after quality + detect-changes)
that validates branch format, PR title, and Vikunja task match.
This fails fast before expensive molecule tests run.
## Spec-Driven CI Gates (Pre-merge)
Every PR must pass these gates before merge:
| Gate | Module | What it checks |
|------|--------|----------------|
| Spec validation | `devx.ci.validate_spec` | Spec file exists at `docs/specs/<TASK-ID>.md`, has REQ-IDs, all ACs checked |
| PR size | `devx.ci.check_pr_size` | Max 500 lines / 10 files (excludes CHANGELOG, badges, locks) |
Full molecule tests still run on every PR (6 scenarios, all platforms).
## Post-merge Auto-publish + Dependency PR
After merge to master, `post-merge.yml`:
1. Runs release (git-cliff semver, tags, publishes to Gitea PyPI)
2. Auto-creates an infra dependency PR (`devx.ci.create_dependency_pr`)
to bump the pinned grm version in `infra/pyproject.toml`
3. Syncs wiki, updates Vikunja task, pushes badges
## Key Rules
- Never manually merge via API — always use auto-merge with `ready-to-merge` label
+272
View File
@@ -0,0 +1,272 @@
# pr-review
Deep, critical PR review with auto-fix. This skill guides the agent
through a thorough review of a pull request, posting inline comments
for each issue found, auto-fixing them, resolving the discussion threads,
and marking the PR as ready-to-merge when no blocking issues remain.
## When to Invoke
Invoke this skill when asked to review a PR, or when a PR is open and
needs review before merge. Do NOT invoke automatically on every PR —
this is an on-demand deep review, not a CI gate.
## Prerequisites
- The PR must be open in a Gitea repo
- The agent needs Gitea MCP access (gitea server)
- The agent needs git push access to the PR's head branch
- The PR should have passed CI (validate job) before deep review
## Review Categories
Review every PR against these 8 categories. For each issue found, post
an inline comment on the specific line, then auto-fix it.
### 1. Functional Correctness
- Does the code actually do what the spec/PR title claims?
- Are edge cases handled? (empty input, null, boundary values, concurrent access)
- Are error paths tested? Not just happy path.
- Does the code handle all return values? (ignored errors, unchecked None)
- Are there off-by-one errors, wrong comparisons, inverted conditions?
- Do loops terminate correctly? (no infinite loops, correct break/continue)
- Are regex patterns correct? (anchored, escaped, non-greedy where needed)
- Are API responses validated before use? (status codes, response shape)
### 2. Completeness
- Are all requirements from the spec implemented? (check each REQ-ID)
- Are all acceptance criteria in the spec checked off?
- Are tests written for all new code paths?
- Are error messages user-facing (wrapped in `_()`)?
- Are new CLI commands documented in `docs/user/cli-commands.md`?
- Are new modules added to architecture docs?
- Are CHANGELOG entries added for user-facing changes?
- Are translations added for new user-facing strings?
### 3. Architecture
- Does the code follow the repo's layer separation? (no business logic in CLI, no direct subprocess in CLI)
- Are new dependencies justified? (no unnecessary new packages)
- Is configuration via env vars / config.py, not hardcoded?
- Are new modules placed in the correct directory? (ci/ vs tools/ vs molecule/)
- Does the code reuse existing utilities? (no reimplemented helpers)
- Are imports circular? (check import chains)
- Is the code testable? (injectable dependencies, no hidden global state)
- Does the code follow existing patterns in the codebase?
### 4. Reliability
- Are external API calls retried with backoff?
- Are timeouts set on all network operations?
- Are file operations atomic? (write to temp, rename)
- Are database operations transactional where needed?
- Are there race conditions? (check shared mutable state)
- Are resources cleaned up in all paths? (finally blocks, context managers)
- Can the code handle partial failures? (one service down, others up)
- Are idempotency guarantees maintained? (safe to retry)
### 5. Robustness
- Does the code fail gracefully? (meaningful error messages, not stack traces)
- Are unexpected inputs handled? (type checking, validation)
- Are there any crash-on-bad-input paths?
- Does the code degrade under load? (backpressure, queue limits)
- Are there resource leaks? (file handles, connections, memory)
- Does the code survive network partitions? (retry, circuit breaker)
- Are there any unhandled exceptions that could crash the process?
- Is logging sufficient to diagnose production issues?
### 6. Security
- Are there hardcoded secrets, tokens, or passwords?
- Is `shell=True` used with user input? (command injection)
- Is `eval()` or `exec()` used? (code injection)
- Are SQL queries parameterized? (no string concatenation)
- Are file paths validated? (no path traversal)
- Are user inputs sanitized before display? (XSS in web contexts)
- Are SSL/TLS verifications disabled without justification?
- Are secrets logged in error messages or debug output?
- Are permissions checked before privileged operations?
- Is sensitive data in memory longer than necessary?
### 7. Technical Excellence
- Are functions under 50 lines? (refactor if longer)
- Is cyclomatic complexity reasonable? (no deeply nested if/else chains)
- Are names meaningful? (no single-letter vars, no misleading names)
- Is dead code removed? (no commented-out blocks, no unused imports)
- Are comments explaining WHY, not WHAT?
- Is the code DRY? (no copy-pasted blocks that should be shared)
- Is the code SOLID? (single responsibility, open/closed)
- Are magic numbers extracted to named constants?
- Is the code formatted per the repo's linter config?
- Are type hints present on all function signatures?
### 8. Test Quality
- Do tests actually test the behavior? (not just that code runs)
- Are tests independent? (no shared mutable state, no order dependency)
- Are tests fast? (no real sleeps, no real network calls, mocked)
- Are edge cases tested? (empty, None, boundary, error paths)
- Are test names descriptive? (test_what_condition_expected_result)
- Are mocks set up correctly? (mocking the right object, not too broad)
- Is coverage 100% for new code? (every branch, every line)
- Are integration tests added for cross-module changes?
- Do tests clean up after themselves? (tmp_path, fixtures)
## Review Procedure
### Step 1: Gather Context
```
1. Read the PR spec (if exists): docs/specs/<TASK-ID>.md
2. Fetch PR details via Gitea MCP: pull_request_read (get_pr, list_pr_files)
3. Read the full diff: git diff origin/master...HEAD
4. Read the PR description and any existing review comments
5. Identify the repo's task prefix (OBL-INFRA, GRM, SSO, DEVX)
```
### Step 2: Review Each File
For each changed file in the PR:
1. Read the full file (not just the diff) to understand context
2. Go through all 8 review categories
3. For each issue found, note: file path, line number, category, severity, description, suggested fix
### Step 3: Post Inline Comments
For each issue found, post an inline review comment using the Gitea MCP:
```
mcp_call_tool: gitea / pull_request_review_write
method: create
owner: <owner>
repo: <repo>
pull_number: <PR number>
state: PENDING (accumulate comments before submitting)
body: "" (empty for now, summary added on submit)
comments: [
{
path: "<file path>",
new_line_num: <line number>,
body: "**[<category>] [<severity>]** <description>\n\n**Suggested fix:**\n```<lang>\n<fixed code>\n```"
}
]
```
Comment format:
```
**[Security] [error]** `shell=True` used with user input — command injection risk.
**Suggested fix:**
```python
subprocess.run(["git", "log", commit], check=True)
```
```
Severity levels:
- `error` — must fix before merge (security, correctness, crash)
- `warning` — should fix before merge (reliability, best practice)
- `info` — consider fixing (style, minor improvement)
### Step 4: Auto-Fix Issues
For each issue that can be safely auto-fixed:
1. Edit the file using the `edit` tool
2. Commit with message: `fix: address review comment — <short description>`
3. Push to the PR's head branch: `git push origin HEAD`
4. Wait for CI to re-run on the push
Auto-fix ALL issues unless:
- The fix requires an architectural decision (ask the user)
- The fix changes public API behavior (ask the user)
- The fix is ambiguous (multiple valid approaches, ask the user)
### Step 5: Resolve Discussion Threads
After auto-fixing an issue and CI passes:
1. Find the review comment thread for that issue
2. Post a reply: `Fixed in <commit-sha>. Closing this thread.`
3. Resolve the discussion (if Gitea supports it via API)
4. If resolving via API is not available, the reply comment serves as resolution
### Step 6: Submit Final Review
After all issues are addressed (fixed or discussed):
```
mcp_call_tool: gitea / pull_request_review_write
method: submit
owner: <owner>
repo: <repo>
pull_number: <PR number>
review_id: <from step 3 create>
state: COMMENT (or APPROVED if no blocking issues remain)
body: <summary — see below>
```
### Step 7: Post Summary
Post a brief summary as a PR comment (via `issue_write / add_comment`):
```
## Deep Review Summary
- **Files reviewed:** N
- **Issues found:** N (N auto-fixed, N require attention)
- **Categories:** security (N), correctness (N), architecture (N), ...
**Outcome:** ✅ Ready to merge — all issues addressed.
**OR**
**Outcome:** ⚠️ N blocking issue(s) remain — see inline comments.
```
Keep the summary to 5-10 bullet points. Do not paste the full review.
### Step 8: Mark PR Ready
If all issues are addressed and no blocking issues remain:
```
mcp_call_tool: gitea / issue_write
method: add_labels
owner: <owner>
repo: <repo>
issue_number: <PR number>
labels: [<label_id for "ready-to-merge">]
```
If blocking issues remain, do NOT add the label. Post a comment
explaining what needs to be resolved before the PR can merge.
## Gitea MCP Tools Reference
| Action | MCP tool | Method |
|--------|----------|--------|
| Get PR details | `pull_request_read` | `get_pr` |
| List PR files | `pull_request_read` | `list_pr_files` |
| Get PR diff | `pull_request_read` | `get_pr_diff` |
| Create review (pending) | `pull_request_review_write` | `create` (state: PENDING) |
| Submit review | `pull_request_review_write` | `submit` (state: APPROVED/COMMENT/REQUEST_CHANGES) |
| Post PR comment | `issue_write` | `add_comment` |
| Add label | `issue_write` | `add_labels` |
| List labels | `label_read` | `list_repo_labels` |
| Merge PR | `pull_request_write` | `merge` (do NOT use — auto-merge handles this) |
## Important Rules
- **Never merge the PR yourself.** Add the `ready-to-merge` label and let
the auto-merge workflow handle it. This ensures CI passes and the
commit message follows the `<PREFIX>-N: <conventional>` format.
- **Never approve your own PR.** If the agent created the PR, post
COMMENT state, not APPROVED.
- **Always push fixes to the PR branch**, not directly to master.
- **Wait for CI after each push** before resolving the discussion thread.
- **Post one review with all comments**, not multiple reviews.
- **The summary must be brief** — 5-10 bullet points max.
- **Severity matters**: only `error` severity blocks the `ready-to-merge` label.
@@ -0,0 +1,130 @@
# Spec-Driven Development
## Overview
Every change starts with a spec. No spec, no code. No code, no PR.
The spec is a markdown file at `docs/specs/<TASK-ID>.md` in the repo.
It contains structured requirements (REQ-IDs) and acceptance criteria
(AC checklist) that CI validates before merge.
## Workflow
1. **Create Vikunja task**`make create-task -- --title "Title" --description "..."`
2. **Write spec** — Create `docs/specs/<TASK-ID>.md` (see template below)
3. **Create branch**`git checkout -b <PREFIX>-N-short-description`
4. **Implement** — Write code with `# Implements: REQ-N` comments
5. **Check ACs** — Tick all acceptance criteria checkboxes in the spec
6. **Push and create PR**`make push-with-pr`
7. **CI validates** — Spec validation, PR size check, fast molecule, lint, tests
8. **Auto-merge** — Add `ready-to-merge` label after review
9. **Auto-deploy** — Post-merge deploys to staging (if nightly gate is green)
## Spec Template
```markdown
# <TASK-ID>: <Title>
## Problem
<What is broken or missing? Why does this change exist?>
## Approach
<How will you solve it? What are the key design decisions?>
REQ-1: <First requirement description>
REQ-2: <Second requirement description>
REQ-3: <Third requirement description>
## Test Plan
- <How will you verify each REQ is implemented correctly?>
- <Include unit tests, molecule scenarios, integration tests>
## Deploy Plan
- <How will this change be deployed?>
- <What order do components need to deploy in?>
- <Are there migrations or one-time operations?>
## Rollback Plan
- <How do you revert if something goes wrong?>
- <What data/state changes are irreversible?>
## Acceptance Criteria
- [ ] REQ-1: <criterion that proves REQ-1 is done>
- [ ] REQ-2: <criterion that proves REQ-2 is done>
- [ ] REQ-3: <criterion that proves REQ-3 is done>
```
## CI Validation
The `devx.ci.validate_spec` module checks:
1. **Spec file exists** at `docs/specs/<TASK-ID>.md` (TASK-ID from branch name)
2. **Required sections present**: Problem, Approach, Test Plan, Deploy Plan, Rollback Plan, Acceptance Criteria
3. **At least one REQ-ID** line (format: `REQ-N: <description>`)
4. **All AC checkboxes checked** (`- [x]`, not `- [ ]`)
If any check fails, CI blocks the PR before expensive jobs run.
## PR Size Limits
CI enforces max 500 lines / 10 files changed (excluding CHANGELOG.md,
README.md, badges, lock files). Oversized PRs are rejected. Split your
work into smaller PRs.
## Code-to-Spec Linking
Each function, task, or template that implements a requirement should
have a comment:
```python
# Implements: REQ-1
def install_sso_bridge():
...
```
```yaml
# Implements: REQ-2
- name: Clone infra repo
git:
...
```
## Fast Molecule (Pre-merge)
CI runs molecule only for **changed roles** (detected via git diff),
with converge + verify only, single platform. This gives quick feedback
(~5-10 min) without the full molecule suite.
## Full Molecule (Nightly)
The complete molecule suite (all scenarios, all platforms) runs nightly
at 02:00 CET on master. If it fails:
- A Gitea issue is created with the `feedback` label
- The `NIGHTLY_STATUS` repo variable is set to `failed:<run_id>`
- All staging deploys are blocked until nightly passes again
## Auto-Deploy on Merge
Every merged PR auto-deploys to staging (if nightly gate is green).
No manual trigger needed. The deploy runs the full pipeline:
provision → deploy-observability → deploy-customer → configure-oidc.
For grm/sso-bridge: post-merge publishes the package, then auto-creates
an infra PR to bump the pinned version. That infra PR auto-deploys when
merged.
## Key Commands
```bash
# Validate spec locally (before pushing)
python -m devx.ci.validate_spec --branch <PREFIX>-N-description
# Check PR size locally
python -m devx.ci.check_pr_size --base origin/master --head HEAD
# See which roles need fast molecule
python -m devx.ci.fast_molecule --base origin/master --head HEAD
# Check nightly gate status
python -m devx.ci.nightly_gate --repo oblachno/infra --action check
```
@@ -35,6 +35,12 @@ produces false failures (missing dependencies, wrong Python version).
| All platforms | `make molecule-all` | All 6 scenarios on all 4 OSes |
| Parallel | `make molecule-all-parallel` | MOLECULE_JOBS=4 |
### Spec-Driven Workflow
Every PR requires a spec file at `docs/specs/<TASK-ID>.md`. See the
`spec-driven-development` skill for the full workflow and template.
CI validates the spec before running expensive jobs.
## Pre-Push Verification
**Before pushing any branch:**
-47
View File
@@ -1,47 +0,0 @@
name: 'Notify on failure'
description: 'Create a Gitea issue when a CI workflow fails (calls devx.ci.notify_failure)'
# Composite action for the common "Notify on failure" step pattern.
# Replaces the repeated inline:
# - name: Notify on failure
# if: failure()
# env:
# CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
# run: |
# . .venv/bin/activate 2>/dev/null || true
# export PATH="$HOME/.local/bin:$PATH"
# python3 -m devx.ci.notify_failure \
# --repo "${{ github.repository }}" \
# --run-id "${{ github.run_id }}" \
# --workflow "ci/validate" \
# --commit "${{ github.sha }}" \
# --auto-login
#
# Gitea 1.27 notes:
# - `if: failure()` is evaluated in the calling workflow's context and
# propagates correctly to composite action steps.
# - `secrets` are not accessible here; the calling workflow's top-level
# `env:` CI_GITEA_API_TOKEN is used via `${{ env.* }}`.
inputs:
workflow:
description: 'Workflow/job name used in the Gitea issue title (e.g., ci/validate)'
required: true
runs:
using: 'composite'
steps:
- name: Notify on failure
if: failure()
shell: bash
env:
CI_GITEA_API_TOKEN: ${{ env.CI_GITEA_API_TOKEN }}
run: |
. .venv/bin/activate 2>/dev/null || true
export PATH="$HOME/.local/bin:$PATH"
python3 -m devx.ci.notify_failure \
--repo "${{ github.repository }}" \
--run-id "${{ github.run_id }}" \
--workflow "${{ inputs.workflow }}" \
--commit "${{ github.sha }}" \
--auto-login
-89
View File
@@ -1,89 +0,0 @@
name: 'Quality checks'
description: 'Run lint, unit tests with coverage, test speed, docs, translations, and security scan'
# Composite action for the 6-step quality check sequence used by the
# devx validate job. Replaces the inline block:
# - Lint all
# - Unit tests with 100% coverage
# - Check unit test speed
# - Documentation gate (coverage + stale refs + lint + version refs + prose)
# - Translation completeness check
# - Dependency security scan
#
# Each step activates the venv defensively (`. .venv/bin/activate 2>/dev/null
# || true`) so the action works whether or not the setup step created a
# venv at the repo root (pre-built CI images symlink /opt/venv to .venv).
#
# Gitea 1.27 notes:
# - Every `run` step needs explicit `shell:`.
# - Inputs are string-typed; numeric thresholds are passed through as
# strings to `devx.tools.check_test_speed`.
inputs:
package:
description: 'Package name for doc version checks (e.g., devx, grm). Empty = no DEVX_DOC_VERSIONS_PKG override.'
required: false
default: ''
test-speed-max:
description: 'Max total test seconds (passed to check_test_speed --max-seconds)'
required: false
default: '15'
test-speed-max-single:
description: 'Max single test seconds (passed to check_test_speed --max-single-seconds)'
required: false
default: '0.5'
translations-file:
description: 'Path to translations.json (empty = default location src/devx/translations.json)'
required: false
default: ''
runs:
using: 'composite'
steps:
- name: Lint all
shell: bash
run: |
. .venv/bin/activate 2>/dev/null || true
export PATH="$HOME/.local/bin:$PATH"
make lint-all
- name: Unit tests with 100% coverage
shell: bash
run: |
. .venv/bin/activate 2>/dev/null || true
make pytest-cov
- name: Check unit test speed
shell: bash
run: |
. .venv/bin/activate 2>/dev/null || true
python3 -m devx.tools.check_test_speed \
--max-seconds "${{ inputs.test-speed-max }}" \
--max-single-seconds "${{ inputs.test-speed-max-single }}"
- name: Documentation gate (coverage + stale refs + lint + version refs + prose)
shell: bash
env:
DEVX_DOC_COVERAGE_STRICT: "1"
DEVX_VALE_LEVEL: warning
run: |
. .venv/bin/activate 2>/dev/null || true
export PATH="$HOME/.local/bin:$PATH"
if [ -n "${{ inputs.package }}" ]; then
export DEVX_DOC_VERSIONS_PKG="${{ inputs.package }}"
fi
make devx-docs-check
- name: Translation completeness check
shell: bash
run: |
. .venv/bin/activate 2>/dev/null || true
if [ -n "${{ inputs.translations-file }}" ]; then
python3 -m devx.ci.check_translations --translations "${{ inputs.translations-file }}"
else
python3 -m devx.ci.check_translations
fi
- name: Dependency security scan
shell: bash
run: |
. .venv/bin/activate 2>/dev/null || true
# Install pip in venv if missing (needed by pip-audit)
.venv/bin/python -m ensurepip 2>/dev/null || true
PIPAPI_PYTHON_LOCATION=$PWD/.venv/bin/python \
pip-audit --desc --skip-editable 2>&1 || true
-37
View File
@@ -1,37 +0,0 @@
name: 'Set up environment'
description: 'Set up CI environment with venv and PATH (calls make setup-image)'
# Composite action for the common "Set up environment" step pattern.
# Replaces the repeated inline:
# - name: Set up environment
# env:
# CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
# run: make setup-image
#
# Gitea 1.27 notes:
# - Every `run` step needs explicit `shell:`.
# - Composite actions cannot access `secrets` directly; they read from
# the `env:` context which the calling workflow must populate.
# - The calling workflow's top-level `env:` block (CI_GITEA_API_TOKEN,
# CI_GITEA_USERNAME) is visible here via `${{ env.* }}`.
inputs:
extras:
description: 'Extra pip install groups passed to make setup-image (e.g., ci,lint,release)'
required: false
default: ''
runs:
using: 'composite'
steps:
- name: Set up environment
shell: bash
env:
CI_GITEA_API_TOKEN: ${{ env.CI_GITEA_API_TOKEN }}
CI_GITEA_USERNAME: ${{ env.CI_GITEA_USERNAME }}
run: |
if [ -n "${{ inputs.extras }}" ]; then
make setup-image EXTRAS="${{ inputs.extras }}"
else
make setup-image
fi
+135 -43
View File
@@ -18,11 +18,7 @@ jobs:
# Saves ~5x checkout+setup overhead vs 6 separate jobs.
validate:
runs-on: docker
container:
image: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-full:latest
credentials:
username: ${{ vars.CI_GITEA_USERNAME }}
password: ${{ secrets.CI_GITEA_API_TOKEN }}
container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-full:latest
timeout-minutes: 15
defaults:
run:
@@ -36,14 +32,45 @@ jobs:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: ./.gitea/actions/setup-env
with:
extras: "ci,lint"
- uses: ./.gitea/actions/quality-checks
with:
package: grm
test-speed-max: "4"
translations-file: src/grm/translations.json
- name: Set up environment
env:
CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
run: make setup-image EXTRAS=ci,lint
# --- quality steps ---
- name: Lint all
run: |
. .venv/bin/activate 2>/dev/null || true
export PATH="$HOME/.local/bin:$PATH"
make lint-all
- name: Unit tests with 100% coverage
run: |
. .venv/bin/activate 2>/dev/null || true
make pytest-cov
- name: Documentation gate (coverage + stale refs + lint + version refs + prose)
env:
DEVX_DOC_COVERAGE_STRICT: "1"
DEVX_DOC_VERSIONS_PKG: grm
DEVX_VALE_LEVEL: warning
run: |
. .venv/bin/activate 2>/dev/null || true
export PATH="$HOME/.local/bin:$PATH"
make devx-docs-check
- name: Translation completeness check
run: |
. .venv/bin/activate 2>/dev/null || true
python3 -m devx.ci.check_translations --translations src/grm/translations.json
- name: Check unit test speed
run: |
. .venv/bin/activate 2>/dev/null || true
python3 -m devx.tools.check_test_speed --max-seconds 4 --max-single-seconds 0.5
- name: Dependency security scan
run: |
. .venv/bin/activate 2>/dev/null || true
# Install pip in venv if missing (needed by pip-audit)
.venv/bin/python -m ensurepip 2>/dev/null || true
PIPAPI_PYTHON_LOCATION=$PWD/.venv/bin/python \
pip-audit --desc --skip-editable 2>&1 || true
- name: Workflow dry-run validation
run: |
. .venv/bin/activate 2>/dev/null || true
@@ -83,14 +110,30 @@ jobs:
--pr-title "$PR_TITLE" \
--repo "$REPOSITORY" \
--pr-number "$PR_NUMBER"
- name: Run automated PR review
- name: Validate spec file
if: github.event_name == 'pull_request'
env:
DEVX_TASK_PREFIX: GRM
PYTHONPATH: ${{ env.PYTHONPATH }}
HEAD_REF: ${{ github.head_ref }}
run: |
. .venv/bin/activate 2>/dev/null || true
set -euo pipefail
python3 -m devx.ci.pr_review \
"${{ github.event.number }}" \
"${{ github.repository }}"
python3 -m devx.ci.validate_spec \
--branch "$HEAD_REF" \
--github-output
- name: Check PR size
if: github.event_name == 'pull_request'
env:
PYTHONPATH: ${{ env.PYTHONPATH }}
CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
run: |
. .venv/bin/activate 2>/dev/null || true
python3 -m devx.ci.check_pr_size \
--base "origin/master" \
--head "${{ github.event.pull_request.head.sha || github.sha }}" \
--repo "${{ github.repository }}" \
--pr-number "${{ github.event.number }}" \
--github-output
# --- release-dry-run step (conditional) ---
- name: Release dry-run validation
if: steps.detect.outputs.user-facing-changed == 'true'
@@ -113,19 +156,24 @@ jobs:
--owner "${{ github.repository_owner }}" \
--repo "${{ github.event.repository.name }}" \
--github-output
- uses: ./.gitea/actions/notify-failure
with:
workflow: "ci/validate"
- name: Notify on failure
if: failure()
env:
CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
run: |
. .venv/bin/activate 2>/dev/null || true
export PATH="$HOME/.local/bin:$PATH"
python3 -m devx.ci.notify_failure --auto-login \
--repo "${{ github.repository }}" \
--run-id "${{ github.run_id }}" \
--workflow "ci/validate" \
--commit "${{ github.sha }}"
molecule-tests:
needs: [validate]
if: needs.validate.outputs.ansible-changed == 'true'
runs-on: docker
container:
image: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-full:latest
credentials:
username: ${{ vars.CI_GITEA_USERNAME }}
password: ${{ secrets.CI_GITEA_API_TOKEN }}
container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-full:latest
timeout-minutes: 15
strategy:
fail-fast: false
@@ -234,11 +282,7 @@ jobs:
github.event_name == 'pull_request' &&
needs.validate.result == 'success'
runs-on: docker
container:
image: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
credentials:
username: ${{ vars.CI_GITEA_USERNAME }}
password: ${{ secrets.CI_GITEA_API_TOKEN }}
container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
timeout-minutes: 10
defaults:
run:
@@ -248,23 +292,71 @@ jobs:
with:
fetch-depth: 0
token: ${{ secrets.CI_GITEA_API_TOKEN }}
- uses: ./.gitea/actions/setup-env
with:
extras: "ci"
- name: Set up environment
env:
CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
run: make setup-image EXTRAS=ci
- name: Post approval review
env:
REVIEWER_GITEA_API_TOKEN: ${{ secrets.REVIEWER_GITEA_API_TOKEN }}
DEVELOPER_GITEA_API_TOKEN: ${{ secrets.DEVELOPER_GITEA_API_TOKEN }}
PR_NUMBER: ${{ github.event.number }}
REPOSITORY: ${{ github.repository }}
GITHUB_SERVER_URL: ${{ github.server_url }}
GITHUB_REPOSITORY: ${{ github.repository }}
run: |
. .venv/bin/activate 2>/dev/null || true
python3 -m devx.ci.pr_review \
"$PR_NUMBER" \
"$REPOSITORY" \
--event APPROVE \
--checklist-confirmed \
--checklist-categories 1,2,3,4,5,6,7,8,9,10,11,12,13 \
--body "Auto-approved: all CI checks passed (validate, molecule-tests)."
# Post APPROVE review via Gitea API to satisfy branch protection
# Uses DEVELOPER_GITEA_API_TOKEN (kireto) — a different user than
# the PR creator — so Gitea counts the approval (no self-approvals).
curl -s -X POST \
"${GITHUB_SERVER_URL}/api/v1/repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/reviews" \
-H "Authorization: token ${DEVELOPER_GITEA_API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"event":"APPROVED","body":"Auto-approved: all CI checks passed (validate, molecule-tests)."}' \
|| echo "::warning::Failed to post approval review (best-effort)."
- name: Wait for molecule tests to complete
env:
CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
HEAD_SHA: ${{ github.event.pull_request.head.sha }}
run: |
. .venv/bin/activate 2>/dev/null || true
# Poll commit status until all required checks pass or fail
MAX_WAIT=600 # 10 minutes
ELAPSED=0
while [ $ELAPSED -lt $MAX_WAIT ]; do
STATUS=$(curl -s -H "Authorization: token $CI_GITEA_API_TOKEN" \
"https://git.oblachno.oblachno.fyi/api/v1/repos/${{ github.repository }}/commits/$HEAD_SHA/status" \
| python3 -c "
import sys,json
d=json.load(sys.stdin)
statuses={s['context']:s['status'] for s in d.get('statuses',[])}
# Check if all molecule-tests contexts are terminal (success/failure/skipped)
mol_contexts=[k for k in statuses if 'molecule-tests' in k]
if not mol_contexts:
print('skipped')
elif all(statuses[k] in ('success','failure','skipped') for k in mol_contexts):
if any(statuses[k]=='failure' for k in mol_contexts):
print('failure')
else:
print('success')
else:
print('pending')
")
echo "Molecule tests status: $STATUS (elapsed: ${ELAPSED}s)"
if [ "$STATUS" = "success" ] || [ "$STATUS" = "skipped" ]; then
echo "All molecule tests passed (or skipped — no ansible changes)."
break
elif [ "$STATUS" = "failure" ]; then
echo "ERROR: Molecule tests failed. Aborting auto-merge."
exit 1
fi
sleep 30
ELAPSED=$((ELAPSED + 30))
done
if [ $ELAPSED -ge $MAX_WAIT ]; then
echo "ERROR: Timed out waiting for molecule tests."
exit 1
fi
- name: Squash merge with task ID
env:
CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
+55 -25
View File
@@ -36,11 +36,7 @@ env:
jobs:
detect-and-configure:
runs-on: docker
container:
image: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
credentials:
username: ${{ vars.CI_GITEA_USERNAME }}
password: ${{ secrets.CI_GITEA_API_TOKEN }}
container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
timeout-minutes: 10
defaults:
run:
@@ -53,9 +49,11 @@ jobs:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: ./.gitea/actions/setup-env
with:
extras: "ci"
- name: Set up environment
env:
CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
run: make setup-image EXTRAS=ci
- name: Ensure branch protection and labels
env:
DEVX_REPO_NAME: grm
@@ -89,19 +87,24 @@ jobs:
--base "HEAD~1" \
--head "HEAD" \
--github-output
- uses: ./.gitea/actions/notify-failure
with:
workflow: "post-merge/detect-and-configure"
- name: Notify on failure
if: failure()
env:
CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
run: |
. .venv/bin/activate 2>/dev/null || true
export PATH="$HOME/.local/bin:$PATH"
python3 -m devx.ci.notify_failure --auto-login \
--repo "${{ github.repository }}" \
--run-id "${{ github.run_id }}" \
--workflow "post-merge/detect-and-configure" \
--commit "${{ github.sha }}"
release-and-maintain:
needs: [detect-and-configure]
if: always() && needs.detect-and-configure.result == 'success'
runs-on: docker
container:
image: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-full:latest
credentials:
username: ${{ vars.CI_GITEA_USERNAME }}
password: ${{ secrets.CI_GITEA_API_TOKEN }}
container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-full:latest
timeout-minutes: 15
outputs:
tag: ${{ steps.release-tag.outputs.tag }}
@@ -114,22 +117,20 @@ jobs:
fetch-depth: 0
ref: master
token: ${{ secrets.CI_GITEA_API_TOKEN }}
- uses: ./.gitea/actions/setup-env
with:
extras: "ci,lint"
- name: Configure git
- name: Set up environment
env:
CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
run: make setup-image EXTRAS=ci,lint
- name: Configure git
run: |
git config user.name "grm-ci-bot"
git config user.email "grm-ci-bot@oblachno.fyi"
git remote set-url origin "https://grm-ci-bot:${CI_GITEA_API_TOKEN}@git.oblachno.oblachno.fyi/oblachno-oss/grm.git"
# --- release + publish (only if not a release commit) ---
- name: Run release
id: release-tag
if: needs.detect-and-configure.outputs.is-release == 'false' && needs.detect-and-configure.outputs.user-facing-changed == 'true'
env:
CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
DEVX_VERSION_FILE: src/grm/__init__.py
DEVX_TASK_PREFIX: GRM
DEVX_VIKUNJA_PROJECT_ID: 6
@@ -147,6 +148,26 @@ jobs:
git fetch --tags
git checkout "${{ steps.release-tag.outputs.tag }}"
python3 -m devx.ci.publish "${{ steps.release-tag.outputs.tag }}" "${{ github.repository }}" --auto-login
- name: Create infra dependency PR
if: steps.release-tag.outputs.tag != ''
env:
CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
VIKUNJA_TOKEN: ${{ secrets.VIKUNJA_TOKEN }}
PYTHONPATH: ${{ env.PYTHONPATH }}
DEVX_TASK_PREFIX: GRM
DEVX_VIKUNJA_PROJECT_ID: 6
run: |
. .venv/bin/activate 2>/dev/null || true
# Extract version from the tag (strip leading 'v')
TAG="${{ steps.release-tag.outputs.tag }}"
VERSION="${TAG#v}"
python3 -m devx.ci.create_dependency_pr \
--repo oblachno/infra \
--package grm \
--new-version "$VERSION" \
--source-repo "${{ github.repository }}" \
--source-run-id "${{ github.run_id }}" || \
echo "::warning::Failed to create infra dependency PR (best-effort)."
# --- sync-wiki + vikunja (skip on automated/release commits) ---
- name: Sync documentation to wiki
if: needs.detect-and-configure.outputs.is-automated == 'false'
@@ -176,6 +197,15 @@ jobs:
git fetch origin master
git reset --hard origin/master
python3 -m devx.ci.push_badges
- uses: ./.gitea/actions/notify-failure
with:
workflow: "post-merge/release-and-maintain"
- name: Notify on failure
if: failure()
env:
CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
run: |
. .venv/bin/activate 2>/dev/null || true
export PATH="$HOME/.local/bin:$PATH"
python3 -m devx.ci.notify_failure --auto-login \
--repo "${{ github.repository }}" \
--run-id "${{ github.run_id }}" \
--workflow "post-merge/release-and-maintain" \
--commit "${{ github.sha }}"
+54 -60
View File
@@ -61,8 +61,37 @@ CI also runs a best-effort `make workflow-dryrun` step (skipped if act_runner is
- **devx package** (installed from git) — Reusable CI/CD tools: auto-merge, post-merge, release, publishing, molecule distribution, PR reviews, failure notifications
- **Versioning** (`cliff.toml`) — git-cliff configuration for automated semver versioning from conventional commits
## Spec-Driven Development
Every change starts with a spec. No spec, no code.
**Workflow:**
1. Create Vikunja task → get `<PREFIX>-N` task ID
2. Write spec at `docs/specs/<TASK-ID>.md` (see template in `.devin/skills/spec-driven-development/SKILL.md`)
3. Create branch, implement with `# Implements: REQ-N` comments
4. Tick all acceptance criteria checkboxes in spec
5. Push and create PR — CI validates spec before expensive jobs
**CI gates (pre-merge):**
- `devx.ci.validate_spec` — checks spec exists, has required sections, REQ-IDs, all ACs checked
- `devx.ci.check_pr_size` — max 500 lines / 10 files (excludes CHANGELOG, badges, locks)
- `devx.ci.fast_molecule` — converge+verify only for changed roles, single platform
**Nightly (infra only):**
- Full molecule suite (all scenarios, all platforms) + staging deploy + integration tests
- On failure: sets `NIGHTLY_STATUS=failed`, blocks staging deploys
- Post-merge auto-deploy to staging checks this gate before deploying
**Post-merge:**
- Infra: auto-deploys to staging (if nightly gate is green)
- GRM/sso-bridge: auto-publishes package, auto-creates infra dependency PR to bump pinned version
**Skill:** `.devin/skills/spec-driven-development/SKILL.md` — full template and workflow details.
## PR Workflow (Mandatory)
Every change to master goes through this workflow. No exceptions.
### Branch Protection (Required Gitea Settings)
@@ -118,67 +147,40 @@ docs: update README
### 6. Review the PR (Mandatory — Before Adding ready-to-merge Label)
**Review checklist:** Every PR is reviewed against 13 categories covering
architecture, code quality, security, i18n, testing, performance,
UX, documentation, workflow compliance, maintainability, resource
management, backwards compatibility, and logging.
**Review checklist:** Every PR is reviewed against 8 categories covering
functional correctness, completeness, architecture, reliability,
robustness, security, technical excellence, and test quality.
**Automated review (CI `validate` job):** Every PR triggers an automated
review via `python -m devx.ci.pr_review` as a step in the `validate` job.
This posts a review with
`COMMENT` (no issues) or `REQUEST_CHANGES` (issues found) based on
the **[auto]** items in the checklist:
**Deep review (agent-invoked `pr-review` skill):** The agent invokes
the `pr-review` skill to perform a deep, critical review of the PR.
The skill posts inline comments for each issue found via the Gitea MCP,
auto-fixes them, pushes fixes to the PR branch, resolves discussion
threads, and posts a brief summary. When no blocking issues remain,
the PR is marked `ready-to-merge`.
- Architecture compliance (no subprocess in CLI, no hardcoded URLs)
- Best practices (no `print()`, no bare `except`, no `TODO`/`FIXME`,
no functions > 50 lines)
- Security (no hardcoded secrets, no `shell=True`, no `eval`/`exec`)
- i18n (no raw strings in `click.echo()` without `_()` wrapper)
- Resource management (no `open()` without `with`, no `Popen()` without cleanup)
- Documentation (source changes must include doc updates)
- Test coverage (source changes must include test updates)
- Commit conventions (conventional commit format on PR commits)
The automated review posts inline comments on specific lines and
includes a summary of the checklist categories. The agent **must** address all
`REQUEST_CHANGES` issues before proceeding.
**Manual review (agent):** After the automated review passes, the agent
must go through **every category** listed above and verify
the **[manual]** items by reviewing the full diff
(`git diff master...HEAD`).
Post review comments using `devx.ci.pr_review` (run as `python -m devx.ci.pr_review`):
```bash
CI_GITEA_TOKEN=<token> python -m devx.ci.pr_review <pr_number> <owner/repo> \
--event REQUEST_CHANGES \
--body "Review summary"
```
See `.devin/skills/pr-review/SKILL.md` for the full review procedure,
categories, and MCP tool reference.
### 7. Address Review Comments
Fix each comment one by one, commit, and push. Re-review until satisfied.
### 8. Approve and Merge
Once all checklist items are verified and comments are addressed, post
an approval review with `--checklist-confirmed` and `--checklist-categories`:
### 8. Mark Ready to Merge
Once all issues are addressed, add the `ready-to-merge` label:
```bash
CI_GITEA_TOKEN=<token> python -m devx.ci.pr_review <pr_number> <owner/repo> \
--event APPROVE --checklist-confirmed \
--checklist-categories 1,2,3,4,5,6,7,8,9,10,11,12,13 \
--body "All 13 checklist categories verified. Architecture: <summary>. Security: <summary>. Tests: <summary>. Docs: <summary>."
make devx-pr-label
```
The auto-merge workflow posts an APPROVE review via the Gitea API
and squash-merges with title `GRM-N: <conventional commit message>`.
The `--checklist-confirmed` flag is **required** for APPROVE events —
it attests that the reviewer has gone through every checklist category.
The `--checklist-categories` flag is also **required** — it must list at
least 8 of the 13 category numbers, ensuring the reviewer actually
checked each category rather than rubber-stamping. The review body must
be substantive (> 50 characters) — perfunctory approvals like "LGTM" are
rejected.
> **IMPORTANT**: Never manually merge PRs via the API. Always use the auto-merge
> workflow by adding the `ready-to-merge` label. Manual merges bypass the
> `GRM-N: <conventional>` format enforcement, producing incorrectly named commits.
> The auto-merge script validates the PR title matches the Vikunja task ID
> and conventional commit format before merging.
Then add the `ready-to-merge` label. The auto-merge workflow will:
The auto-merge workflow will:
1. **Validate** PR title format (`GRM-N: <vikunja task title>`) and match against Vikunja task title
2. **Check** that at least one substantive APPROVE review exists (body > 20 chars or has inline comments)
2. **Post** an APPROVE review via the Gitea API (to satisfy branch protection)
3. Wait for all CI checks to pass (including the `validate` job)
4. Squash-merge with title: `GRM-N: <conventional commit message>`
5. The post-merge workflow marks the Vikunja task as done
@@ -190,12 +192,6 @@ a new CI run. The next auto-merge attempt will merge successfully.
No manual rebase needed. To rebase manually: `make rebase` (local) or
`make pr-rebase` (server-side via API).
> **IMPORTANT**: Never manually merge PRs via the API. Always use the auto-merge
> workflow by adding the `ready-to-merge` label. Manual merges bypass the
> `GRM-N: <conventional>` format enforcement, producing incorrectly named commits.
> The auto-merge script validates the PR title matches the Vikunja task ID
> and conventional commit format before merging.
### CI Path Filtering
The CI workflow's `validate` job includes a pre-merge validation step
@@ -278,7 +274,7 @@ via `[tool.devx.classify]` in `pyproject.toml`.
- Any new file type not in the allowlist
**devx module structure** (installed from git, not in this repo):
- `devx.ci.*` — CI/CD automation (run by workflows): release, publish, auto_merge, classify_changes, detect_release_commit, push_badges, doc_coverage, sync_wiki, distribute_molecule, discover_runners, notify_failure, post_merge, pr_review, validate_commit_msg
- `devx.ci.*` — CI/CD automation (run by workflows): release, publish, auto_merge, classify_changes, detect_release_commit, push_badges, doc_coverage, sync_wiki, distribute_molecule, discover_runners, notify_failure, post_merge, validate_commit_msg
- `devx.tools.*` — Dev tools (run locally): check_test_speed, configure_repo, install_checkmake, install_tools, setup, generate_badges, create_task, create_pr, pr_status, pr_logs, pr_label, rebase, pr_rebase
- `devx.molecule.*` — Molecule helpers: molecule_all, platforms, discover_runners, distribute_molecule
- `devx.gitea_cli` — Tea CLI wrapper
@@ -334,12 +330,10 @@ The `tea` Gitea CLI tool is used for Gitea API interactions in devx. It is insta
- `devx.tools.configure_repo` — Creates labels via `tea labels create` (falls back to `GiteaClient` if tea fails; branch protection still uses `GiteaClient` since tea only supports basic protect/unprotect)
**Operations still using `GiteaClient` (not supported by tea):**
- PR reviews (`devx.ci.pr_review`) — tea v0.14.1 only supports interactive reviews
- Wiki page management (`devx.ci.sync_wiki`)
- Commit status checks (`devx.ci.auto_merge`)
- Runner discovery (`devx.molecule.discover_runners`)
- Branch protection with detailed config (`devx.tools.configure_repo`)
- PR file/commit listing (`devx.ci.pr_review`)
### PYTHONPATH Configuration
@@ -347,7 +341,7 @@ Since devx is installed as a package (via `pip install` from git), it is importa
| PYTHONPATH | When to use | Example modules |
|------------|-------------|-----------------|
| `src` | Module imports from `grm` | `devx.ci.auto_merge`, `devx.ci.pr_review`, `devx.ci.pr_review`, `devx.ci.sync_wiki`, `devx.ci.post_merge`, `devx.ci.classify_changes`, `devx.molecule.discover_runners`, `devx.ci.doc_coverage` |
| `src` | Module imports from `grm` | `devx.ci.auto_merge`, `devx.ci.sync_wiki`, `devx.ci.post_merge`, `devx.ci.classify_changes`, `devx.molecule.discover_runners`, `devx.ci.doc_coverage` |
| (none) | Module has no GRM imports | `devx.ci.detect_release_commit`, `devx.molecule.distribute_molecule`, `devx.ci.push_badges`, `devx.ci.validate_commit_msg` |
**In workflows**, always use `env:` blocks (not inline `PYTHONPATH=value`):
+22 -16
View File
@@ -2,29 +2,35 @@
All notable changes to this project will be documented in this file.
## [Unreleased]
## [0.23.0] - 2026-08-28
### CI
### Features
- Convert `ci.yml` and `post-merge.yml` to use composite actions
(`setup-env`, `quality-checks`, `notify-failure`) copied from devx,
reducing workflow duplication
- Add pre-cache timer, force_pull, and Docker socket options to runner config
## [0.22.1] - 2026-08-26
### Bug Fixes
- Fix `register.yml` premature service start: removed step that ran
`systemctl --user start gitea-runner` before the systemd unit file was
created by `service.yml` (included after `register.yml`). First-time
installs were failing with "Unit gitea-runner.service not found".
- Fix `ci.yml` auto-merge IndentationError: replaced broken inline Python
polling script with `devx.ci.wait_for_checks` (the inline Python had
YAML run-block indentation leaking into `python3 -c` string).
- Use kireto token for auto-merge approval review
### Dependencies
## [0.22.0] - 2026-08-25
- Bump devx from v0.50.0 to v0.50.5 (adds `wait_for_checks` tool,
consolidated Ansible checks, tenacity retry in `install_tools`,
increased download retry attempts/backoff)
### Features
- Adopt spec-driven CI gates, create_dependency_pr, and pr-review skill
## [0.21.1] - 2026-08-24
### Bug Fixes
- Use runuser for systemctl --user tasks in gitea_runner role
## [0.21.0] - 2026-08-09
### Features
- *(healthcheck)* Add two-tier disk prune with critical threshold
## [0.20.0] - 2026-08-09
+6 -6
View File
@@ -8,12 +8,12 @@ Each runner runs in an isolated **rootless Docker** environment under a dedicate
[![CI](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions/workflows/ci.yml/badge.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
[![License: GPL-3.0](https://img.shields.io/badge/license-GPL--3.0-blue)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/src/branch/master/LICENSE)
[![Coverage](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/e96a599d8e0a5186cd72bebaddbd24b2df2e2058/coverage.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
[![Tests](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/e96a599d8e0a5186cd72bebaddbd24b2df2e2058/tests.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
[![Docs](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/e96a599d8e0a5186cd72bebaddbd24b2df2e2058/docs.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki)
[![Code Quality](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/e96a599d8e0a5186cd72bebaddbd24b2df2e2058/quality.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
[![Version](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/e96a599d8e0a5186cd72bebaddbd24b2df2e2058/version.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/releases)
[![Python](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/e96a599d8e0a5186cd72bebaddbd24b2df2e2058/python.svg)](https://www.python.org/downloads/)
[![Coverage](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/9ae4b38a319a6a0122111cebdbaa65c108222483/coverage.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
[![Tests](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/9ae4b38a319a6a0122111cebdbaa65c108222483/tests.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
[![Docs](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/9ae4b38a319a6a0122111cebdbaa65c108222483/docs.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki)
[![Code Quality](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/9ae4b38a319a6a0122111cebdbaa65c108222483/quality.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
[![Version](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/9ae4b38a319a6a0122111cebdbaa65c108222483/version.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/releases)
[![Python](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/9ae4b38a319a6a0122111cebdbaa65c108222483/python.svg)](https://www.python.org/downloads/)
## Why GRM?
+27 -12
View File
@@ -36,10 +36,9 @@ gitea_runner_prune_label: "gitea-runner=true"
gitea_runner_service_restart_sec: "5"
# Health check configuration
# 2min interval — catches hung daemons before multiple CI jobs fail between
# checks. The 1min interval caused excessive pruning which removed cached
# images, forcing all 6 parallel slots to re-pull simultaneously and
# actually increasing disk pressure.
# 2min interval — catches hung daemons before multiple CI jobs fail between checks.
# The previous 5min interval was too coarse: a stuck daemon could fail 3+ molecule
# jobs in the window between healthcheck runs.
gitea_runner_healthcheck_interval: "2min"
gitea_runner_healthcheck_boot_delay: "2min"
gitea_runner_healthcheck_disk_threshold: 70
@@ -48,10 +47,6 @@ gitea_runner_healthcheck_disk_threshold: 70
# This removes all stopped containers and unused images regardless of age.
# At 75%+, molecule containers fail with "container is not running" because
# overlay2 runs out of space under parallel DinD load.
# IMPORTANT: keep at 75 (not lower) — the host disk normally sits at ~74%.
# Lowering to 70 triggers full prune every cycle, wiping cached images and
# forcing all parallel slots to re-pull simultaneously, which increases
# disk pressure rather than reducing it.
gitea_runner_healthcheck_disk_critical: 75
gitea_runner_healthcheck_script_path: "{{ gitea_runner_config_dir }}/healthcheck.sh"
@@ -81,10 +76,6 @@ gitea_runner_docker_shutdown_timeout: 30
gitea_runner_docker_max_concurrent_downloads: 3
gitea_runner_docker_max_concurrent_uploads: 3
gitea_runner_docker_default_nofile: 65536
# Log file size limits — under parallel DinD load, container logs can fill
# disk and cause the daemon to become unresponsive. Limit log size per container.
gitea_runner_docker_max_log_size: "10m"
gitea_runner_docker_max_log_files: 3
# Admin token for runner deregistration via Gitea API.
# If not set, falls back to registration_token (which likely lacks admin scope).
@@ -99,6 +90,22 @@ gitea_runner_remove_user: true
gitea_runner_log_level: "info"
gitea_runner_container_label: "gitea-runner=true"
gitea_runner_file: ".runner"
# force_pull: when false (default), the runner reuses locally cached images
# instead of pulling on every job. Pre-cached images (via the pre-cache timer
# or pre_pull_images task) eliminate registry thundering-herd when all runners
# start jobs simultaneously.
gitea_runner_force_pull: false
# Container options passed to `docker run` for CI job containers.
# Mounts the host rootless Docker socket as /run/host-docker.sock so
# start_docker.py inside the container can detect and use the host daemon
# (full disk, no nested DinD) instead of starting an inner dockerd.
gitea_runner_container_options: "-v /run/user/{{ gitea_runner_uid }}/docker.sock:/run/host-docker.sock"
# Volumes allowed in CI job containers (validated by the runner against
# container.options and job-level volumes). Must include the host Docker
# socket mount target.
gitea_runner_valid_volumes:
- "/run/host-docker.sock"
- "/run/user/{{ gitea_runner_uid }}/docker.sock"
# Containerd version pinning — Docker 28.x vendors containerd v2.1.x internally.
# containerd.io >= 2.3 ships a shim that returns a protobuf BootstrapResult which
@@ -144,3 +151,11 @@ gitea_runner_docker_ipv6_cidr: "fd00:dead:beef::/48"
# disk-space prune only removes dangling images, so pre-pulled tagged images persist.
# Set to [] to skip pre-pulling. Images are pulled as the runner user via rootless Docker.
gitea_runner_pre_pull_images: []
# Pre-cache timer: periodically pulls the runner container image so it stays
# fresh in the local Docker cache. This prevents thundering-herd registry
# timeouts when all runners start CI jobs simultaneously with empty caches.
# Runs every 6 hours (aligned with prune schedule). Set to empty string to
# disable the timer.
gitea_runner_pre_cache_schedule: "*-*-* 00/6:30:00"
gitea_runner_pre_cache_images: "{{ gitea_runner_pre_pull_images }}"
@@ -10,7 +10,3 @@
- ansible_facts is defined
- ansible_facts['service_mgr'] | default('') == 'systemd'
- gitea_runner_docker_rootless_setup
- name: Reload systemd user daemon
ansible.builtin.systemd:
daemon_reload: true
@@ -112,4 +112,5 @@
- "'status=removing' in healthcheck_script.content | b64decode"
- "'status=stopping' in healthcheck_script.content | b64decode"
- "gitea_runner_healthcheck_disk_threshold | string in healthcheck_script.content | b64decode"
- "gitea_runner_healthcheck_disk_critical | string in healthcheck_script.content | b64decode"
fail_msg: "Healthcheck script template is missing expected content"
@@ -20,6 +20,9 @@
- name: Include pre-pull images
ansible.builtin.include_tasks: pre_pull_images.yml
- name: Include pre-cache timer
ansible.builtin.include_tasks: pre_cache.yml
- name: Include integration test
ansible.builtin.include_tasks: integration_test.yml
when: not gitea_runner_skip_registration
@@ -0,0 +1,67 @@
---
# Periodic timer that pre-pulls CI runner images into the local Docker cache.
# Prevents thundering-herd registry timeouts when all runners start jobs
# simultaneously with empty/stale caches. Runs every 6 hours (configurable).
# The prune timer removes dangling images but NOT tagged ones, so pre-pulled
# images persist between runs.
- name: Create docker-pull-images user service file
ansible.builtin.template:
src: docker-pull-images.service.j2
dest: "{{ gitea_runner_home }}/.config/systemd/user/docker-pull-images.service"
owner: "{{ gitea_runner_service_user }}"
group: "{{ gitea_runner_service_user }}"
mode: "0644"
register: gitea_runner_pre_cache_service
- name: Create docker-pull-images user timer file
ansible.builtin.template:
src: docker-pull-images.timer.j2
dest: "{{ gitea_runner_home }}/.config/systemd/user/docker-pull-images.timer"
owner: "{{ gitea_runner_service_user }}"
group: "{{ gitea_runner_service_user }}"
mode: "0644"
register: gitea_runner_pre_cache_timer
- name: Reload systemd user daemon for pre-cache timer
ansible.builtin.command: systemctl --user daemon-reload
become: true
become_user: "{{ gitea_runner_service_user }}"
environment:
XDG_RUNTIME_DIR: "/run/user/{{ gitea_runner_uid }}"
DBUS_SESSION_BUS_ADDRESS: "unix:path=/run/user/{{ gitea_runner_uid | default(0) }}/bus"
changed_when: true
when:
- gitea_runner_systemd_available.stat.exists
- gitea_runner_docker_rootless_setup
- gitea_runner_pre_cache_service is changed or gitea_runner_pre_cache_timer is changed
- gitea_runner_pre_cache_schedule | length > 0
- gitea_runner_pre_cache_images | length > 0
- name: Enable and start docker-pull-images user timer
ansible.builtin.command: systemctl --user enable --now docker-pull-images.timer
become: true
become_user: "{{ gitea_runner_service_user }}"
environment:
XDG_RUNTIME_DIR: "/run/user/{{ gitea_runner_uid }}"
DBUS_SESSION_BUS_ADDRESS: "unix:path=/run/user/{{ gitea_runner_uid | default(0) }}/bus"
changed_when: true
when:
- gitea_runner_systemd_available.stat.exists
- gitea_runner_docker_rootless_setup
- gitea_runner_pre_cache_schedule | length > 0
- gitea_runner_pre_cache_images | length > 0
- name: Disable and stop docker-pull-images timer (no images or schedule)
ansible.builtin.command: systemctl --user disable --now docker-pull-images.timer
become: true
become_user: "{{ gitea_runner_service_user }}"
environment:
XDG_RUNTIME_DIR: "/run/user/{{ gitea_runner_uid }}"
DBUS_SESSION_BUS_ADDRESS: "unix:path=/run/user/{{ gitea_runner_uid | default(0) }}/bus"
changed_when: true
failed_when: false
when:
- gitea_runner_systemd_available.stat.exists
- gitea_runner_docker_rootless_setup
- gitea_runner_pre_cache_schedule | length == 0 or gitea_runner_pre_cache_images | length == 0
@@ -8,6 +8,15 @@
#
# Set gitea_runner_pre_pull_images to a list of image refs to pull, or
# empty list to skip pre-pulling.
#
# IMPORTANT: Do NOT use this mechanism for:
# - CI runner container images (e.g. ci-full) — these are already
# cached by the runner setup task and pulling them here is redundant.
# - Images that molecule tests pull themselves — molecule prepare/converge
# steps handle their own image pulls; pre-pulling them here wastes time
# and disk space.
# This mechanism is intended only for images that are needed by the runner
# itself but not pulled by any molecule scenario or runner setup step.
- name: Pre-pull Docker images for CI runner
ansible.builtin.command: "docker pull {{ item }}"
@@ -44,6 +44,10 @@
('already exists' not in gitea_runner_register_output.stdout | default(''))
timeout: 60
# Note: service start is handled by service.yml (included after register.yml
# in install_runner.yml). Starting here fails because the systemd unit file
# has not been created yet.
- name: Restart runner service after (re-)registration
ansible.builtin.command: >
runuser -u {{ gitea_runner_service_user }} --
@@ -184,10 +184,6 @@
"features": {
"containerd-snapshotter": false
},
"log-opts": {
"max-size": "{{ gitea_runner_docker_max_log_size }}",
"max-file": "{{ gitea_runner_docker_max_log_files }}"
},
{% if gitea_runner_docker_rootless_net_driver == 'pasta' %}
"ipv6": true,
"ip6tables": true,
@@ -292,10 +288,6 @@
"features": {
"containerd-snapshotter": false
},
"log-opts": {
"max-size": "{{ gitea_runner_docker_max_log_size }}",
"max-file": "{{ gitea_runner_docker_max_log_files }}"
},
{% if gitea_runner_docker_rootless_net_driver == 'pasta' %}
"ipv6": true,
"ip6tables": true,
@@ -69,31 +69,3 @@
owner: "{{ gitea_runner_service_user }}"
group: "{{ gitea_runner_service_user }}"
mode: "0755"
- name: Disable systemd-oomd memory pressure kill for runner user
when: gitea_runner_systemd_available.stat.exists
block:
- name: Ensure user service override directory exists
ansible.builtin.file:
path: "/etc/systemd/system/user@{{ gitea_runner_uid }}.service.d"
state: directory
owner: root
group: root
mode: "0755"
- name: Disable ManagedOOMMemoryPressure for runner user
ansible.builtin.copy:
content: |
[Service]
ManagedOOMMemoryPressure=auto
ManagedOOMMemoryPressureLimit=100%
OOMScoreAdjust=-500
dest: "/etc/systemd/system/user@{{ gitea_runner_uid }}.service.d/oomd-override.conf"
owner: root
group: root
mode: "0644"
notify: Reload systemd user daemon
- name: Reload systemd daemon for oomd override
ansible.builtin.systemd:
daemon_reload: true
@@ -11,7 +11,13 @@ Environment=XDG_RUNTIME_DIR=/run/user/{{ gitea_runner_uid }}
# consuming disk and memory. We stop+rm everything first, then prune the rest.
# Exclude CI job containers (name starts with GITEA-ACTIONS-TASK) — removing
# them kills the active CI job and causes "RWLayer is unexpectedly nil" errors.
ExecStart=/bin/sh -c 'docker ps -a --format "{% raw %}{{.ID}} {{.Names}}{% endraw %}" 2>/dev/null | grep -v "GITEA-ACTIONS-TASK" | awk "{print $1}" | xargs -r docker rm -f 2>/dev/null || true'
# Only remove containers older than 1 hour (grep for "hour/day/week/month/year
# ago" in RunningFor) to avoid killing molecule test containers that CI jobs
# are actively using.
ExecStart=/bin/sh -c 'docker ps -a --format "{% raw %}{{.ID}} {{.Names}} {{.RunningFor}}{% endraw %}" 2>/dev/null | grep -v "GITEA-ACTIONS-TASK" | grep -E "(hour|day|week|month|year)s? ago" | awk "{print $1}" | xargs -r docker rm -f 2>/dev/null || true'
ExecStart=/usr/bin/docker system prune -af --filter "until={{ gitea_runner_prune_until }}" --volumes
ExecStart=/usr/bin/docker network prune -f
# Prune networks older than the prune-until threshold to avoid removing
# networks that molecule tests are actively creating (e.g. 'traefik' network
# created during molecule create phase before containers are attached).
ExecStart=/usr/bin/docker network prune -f --filter "until={{ gitea_runner_prune_until }}"
ExecStart=/usr/bin/docker builder prune -f
@@ -0,0 +1,14 @@
[Unit]
Description=Pre-pull Docker images for CI runner cache
After=docker.service
Wants=docker.service
[Service]
Type=oneshot
Environment=DOCKER_HOST=unix:///run/user/{{ gitea_runner_uid }}/docker.sock
Environment=XDG_RUNTIME_DIR=/run/user/{{ gitea_runner_uid }}
# Pull each image quietly. docker pull exits 0 if image is already up-to-date,
# so this is idempotent. Errors are non-fatal (image may already be cached).
{% for image in gitea_runner_pre_cache_images %}
ExecStart=/usr/bin/docker pull -q {{ image }}
{% endfor %}
@@ -0,0 +1,10 @@
[Unit]
Description=Periodic Docker image pre-cache for CI runner
[Timer]
OnCalendar={{ gitea_runner_pre_cache_schedule }}
Persistent=true
RandomizedDelaySec=300
[Install]
WantedBy=timers.target
@@ -9,3 +9,13 @@ runner:
container:
label: "{{ gitea_runner_container_label }}"
docker_host: "unix:///run/user/{{ gitea_runner_uid }}/docker.sock"
force_pull: {{ gitea_runner_force_pull | lower }}
{% if gitea_runner_container_options | length > 0 %}
options: "{{ gitea_runner_container_options }}"
{% endif %}
{% if gitea_runner_valid_volumes | length > 0 %}
valid_volumes:
{% for volume in gitea_runner_valid_volumes %}
- "{{ volume }}"
{% endfor %}
{% endif %}
@@ -48,6 +48,14 @@ fi
# runner (e.g., server restore, runner record deleted, Gitea restart with
# token salt change), the runner logs "unregistered runner" every few seconds.
# A service restart will not fix this; re-registration is required.
#
# Detection method: query the Gitea API to verify the runner's UUID still
# exists. This is more reliable than parsing journal logs (which requires
# journal access permissions that runner users may not have — see the
# 2026-08-08 incident where journalctl --user returned "No journal files
# were opened due to insufficient permissions" for all runner users,
# causing the healthcheck to always report "OK: runner healthy" even
# though all runners were unregistered).
{% if gitea_runner_auto_recover_api_token %}
# Auto-recovery is enabled: fetch a new registration token from the Gitea API
# and re-register the runner automatically. A cooldown prevents infinite loops.
@@ -58,10 +66,50 @@ GITEA_URL="{{ gitea_url }}"
RUNNER_NAME="{{ gitea_runner_name }}"
RUNNER_LABELS="{{ gitea_runner_labels }}"
BINARY="{{ gitea_runner_binary_path }}"
RUNNER_FILE="{{ gitea_runner_data_dir }}/.runner"
{% endif %}
recent_errors=$(journalctl --user -u gitea-runner.service --since "5 minutes ago" --no-pager -q 2>/dev/null | grep -c "unregistered runner" || true)
if [[ "$recent_errors" -ge 3 ]]; then
echo "CRITICAL: runner is unregistered in Gitea (re-login failed $recent_errors times in 5 minutes)."
runner_unregistered=0
# Primary detection: query the Gitea API to check if the runner's ID
# still exists in Gitea's runner list. This works regardless of journal
# permissions.
{% if gitea_runner_auto_recover_api_token %}
if [[ -f "$GITEA_API_TOKEN_FILE" && -f "$RUNNER_FILE" ]]; then
API_TOKEN=$(cat "$GITEA_API_TOKEN_FILE" 2>/dev/null || true)
RUNNER_ID=$(python3 -c "import json; print(json.load(open('$RUNNER_FILE')).get('id',''))" 2>/dev/null || true)
if [[ -n "$API_TOKEN" && -n "$RUNNER_ID" ]]; then
# List all runners and check if our ID is present
runner_found=$(curl -sf --connect-timeout 5 --max-time 10 \
-H "Authorization: token $API_TOKEN" \
"${GITEA_URL}/api/v1/admin/actions/runners" 2>/dev/null \
| python3 -c "
import sys, json
try:
data = json.load(sys.stdin)
runners = data if isinstance(data, list) else data.get('runners', [])
ids = [str(r.get('id', '')) for r in runners]
print('1' if '$RUNNER_ID' in ids else '0')
except Exception:
print('0')
" 2>/dev/null || echo "0")
if [[ "$runner_found" != "1" ]]; then
runner_unregistered=1
echo "CRITICAL: runner ID $RUNNER_ID not found in Gitea (unregistered)."
fi
fi
fi
{% endif %}
# Fallback detection: check journal logs (if accessible)
if [[ "$runner_unregistered" -eq 0 ]]; then
recent_errors=$(journalctl --user -u gitea-runner.service --since "5 minutes ago" --no-pager -q 2>/dev/null | grep -c "unregistered runner" || true)
if [[ "$recent_errors" -ge 3 ]]; then
runner_unregistered=1
echo "CRITICAL: runner is unregistered in Gitea (re-login failed $recent_errors times in 5 minutes)."
fi
fi
if [[ "$runner_unregistered" -ge 1 ]]; then
{% if gitea_runner_auto_recover_api_token %}
# Check cooldown — skip if we recently attempted recovery
if [[ -f "$COOLDOWN_FILE" ]]; then
@@ -135,14 +183,32 @@ if [[ "$recent_errors" -ge 3 ]]; then
systemctl --user start gitea-runner.service
sleep 3
# Verify recovery — check if unregistered errors stopped
new_errors=$(journalctl --user -u gitea-runner.service --since "10 seconds ago" --no-pager -q 2>/dev/null | grep -c "unregistered runner" || true)
if [[ "$new_errors" -eq 0 ]]; then
echo "OK: runner recovered and no longer reporting unregistered errors"
# Clear cooldown on success
rm -f "$COOLDOWN_FILE" 2>/dev/null || true
# Verify recovery — query the Gitea API to confirm the new ID is registered
NEW_ID=$(python3 -c "import json; print(json.load(open('$RUNNER_FILE')).get('id',''))" 2>/dev/null || true)
if [[ -n "$NEW_ID" ]]; then
new_found=$(curl -sf --connect-timeout 5 --max-time 10 \
-H "Authorization: token $API_TOKEN" \
"${GITEA_URL}/api/v1/admin/actions/runners" 2>/dev/null \
| python3 -c "
import sys, json
try:
data = json.load(sys.stdin)
runners = data if isinstance(data, list) else data.get('runners', [])
ids = [str(r.get('id', '')) for r in runners]
print('1' if '$NEW_ID' in ids else '0')
except Exception:
print('0')
" 2>/dev/null || echo "0")
if [[ "$new_found" == "1" ]]; then
echo "OK: runner recovered and registered with new ID $NEW_ID"
# Clear cooldown on success
rm -f "$COOLDOWN_FILE" 2>/dev/null || true
else
echo "WARN: runner re-registered but ID not found in Gitea API. Will retry after cooldown."
exit 3
fi
else
echo "WARN: runner still showing unregistered errors after re-registration. Will retry after cooldown."
echo "WARN: could not read new .runner file after re-registration. Will retry after cooldown."
exit 3
fi
{% else %}
@@ -157,18 +223,43 @@ fi
# 3. Check disk space — prune aggressively if below threshold
disk_pct=$(df -P / | awk 'NR==2 {gsub(/%/, "", $5); print $5}')
if [[ "$disk_pct" -ge {{ gitea_runner_healthcheck_disk_threshold }} ]]; then
echo "WARN: Disk usage at ${disk_pct}%, pruning all runner resources"
# Force-remove stale containers (including running ones from failed molecule tests).
# "docker container prune -f" only removes stopped containers, so running
# containers from crashed CI jobs accumulate and consume disk/memory.
# Exclude CI job containers (name starts with GITEA-ACTIONS-TASK).
if [[ "$disk_pct" -ge {{ gitea_runner_healthcheck_disk_critical }} ]]; then
echo "CRITICAL: Disk usage at ${disk_pct}% (>= {{ gitea_runner_healthcheck_disk_critical }}%), full prune"
# Critical level: remove ALL stopped containers (no age filter) and ALL
# unused images/volumes. The until=1h gentle prune is insufficient here.
# Stop+rm stale non-CI containers regardless of age (failed molecule tests
# from the last 59 minutes also consume disk).
docker ps -a --format '{% raw %}{{.ID}} {{.Names}}{% endraw %}' 2>/dev/null \
| grep -v 'GITEA-ACTIONS-TASK' \
| awk '{print $1}' \
| xargs -r docker rm -f 2>/dev/null || true
docker system prune -af --filter "until=1h" --volumes || true
docker system prune -af --volumes || true
docker network prune -f || true
docker builder prune -af || true
disk_pct=$(df -P / | awk 'NR==2 {gsub(/%/, "", $5); print $5}')
echo "INFO: Disk usage after full prune: ${disk_pct}%"
elif [[ "$disk_pct" -ge {{ gitea_runner_healthcheck_disk_threshold }} ]]; then
echo "WARN: Disk usage at ${disk_pct}%, pruning runner resources (until=1h)"
# Force-remove stale containers (including running ones from failed molecule tests)
# that are older than 1 hour. "docker container prune -f" only removes stopped
# containers, so running containers from crashed CI jobs accumulate and consume
# disk/memory. Exclude CI job containers (name starts with GITEA-ACTIONS-TASK).
# Only remove containers older than 1 hour to avoid killing molecule test
# containers that CI jobs are actively using.
docker ps -a --format '{% raw %}{{.ID}} {{.Names}} {{.RunningFor}}{% endraw %}' 2>/dev/null \
| grep -v 'GITEA-ACTIONS-TASK' \
| grep -E '(hour|day|week|month|year)s? ago' \
| awk '{print $1}' \
| xargs -r docker rm -f 2>/dev/null || true
# Prune images and containers older than 1h (until filter is NOT
# supported with --volumes, so prune volumes separately without a filter).
docker image prune -af --filter "until=1h" 2>/dev/null || true
docker container prune -f --filter "until=1h" 2>/dev/null || true
docker volume prune -f 2>/dev/null || true
# Prune networks older than 1 hour to avoid removing networks that
# molecule tests are actively creating (e.g. 'traefik' network created
# during molecule create phase before containers are attached).
docker network prune -f --filter "until=1h" || true
disk_pct=$(df -P / | awk 'NR==2 {gsub(/%/, "", $5); print $5}')
echo "INFO: Disk usage after prune: ${disk_pct}%"
fi
+6 -6
View File
@@ -8,12 +8,12 @@ Each runner runs in an isolated **rootless Docker** environment under a dedicate
[![CI](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions/workflows/ci.yml/badge.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
[![License: GPL-3.0](https://img.shields.io/badge/license-GPL--3.0-blue)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/src/branch/master/LICENSE)
[![Coverage](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/e96a599d8e0a5186cd72bebaddbd24b2df2e2058/coverage.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
[![Tests](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/e96a599d8e0a5186cd72bebaddbd24b2df2e2058/tests.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
[![Docs](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/e96a599d8e0a5186cd72bebaddbd24b2df2e2058/docs.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki)
[![Code Quality](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/e96a599d8e0a5186cd72bebaddbd24b2df2e2058/quality.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
[![Version](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/e96a599d8e0a5186cd72bebaddbd24b2df2e2058/version.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/releases)
[![Python](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/e96a599d8e0a5186cd72bebaddbd24b2df2e2058/python.svg)](https://www.python.org/downloads/)
[![Coverage](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/9ae4b38a319a6a0122111cebdbaa65c108222483/coverage.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
[![Tests](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/9ae4b38a319a6a0122111cebdbaa65c108222483/tests.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
[![Docs](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/9ae4b38a319a6a0122111cebdbaa65c108222483/docs.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki)
[![Code Quality](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/9ae4b38a319a6a0122111cebdbaa65c108222483/quality.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
[![Version](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/9ae4b38a319a6a0122111cebdbaa65c108222483/version.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/releases)
[![Python](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/9ae4b38a319a6a0122111cebdbaa65c108222483/python.svg)](https://www.python.org/downloads/)
## Overview
+47
View File
@@ -0,0 +1,47 @@
# GRM-162: Add pre-cache timer, force_pull, and Docker socket options to runner config
## Problem
CI containers were not using the host's rootless Docker daemon, leading to
"no space left on device" errors. The runner config template was missing
`force_pull`, `options` (host Docker socket mount), and `valid_volumes`
fields. Additionally, no pre-cache timer existed to prevent thundering-herd
registry timeouts when all runners pull images simultaneously.
## Approach
REQ-1: Add `force_pull: false` to runner config template (explicit default
so the runner reuses locally cached images instead of pulling on every job)
REQ-2: Add `options` field to mount host rootless Docker socket as
`/run/host-docker.sock` so `start_docker.py` inside CI containers can detect
and use the host daemon (full disk, no nested DinD)
REQ-3: Add `valid_volumes` list for the socket mount targets (validated by
the runner against `container.options` and job-level volumes)
REQ-4: Add `pre_cache.yml` task with a systemd user timer that pre-pulls CI
images every 6 hours (configurable via `gitea_runner_pre_cache_schedule`)
REQ-5: Add `docker-pull-images.service.j2` and `docker-pull-images.timer.j2`
templates for the pre-cache timer
REQ-6: Timer is disabled when `gitea_runner_pre_cache_schedule` is empty or
`gitea_runner_pre_cache_images` is empty (graceful degradation)
## Test Plan
- `make lint-ci` passes (ansible-lint on new task/template files)
- `make molecule` converges successfully with the new pre-cache tasks
- Verify the runner config template renders correctly with and without
container options/valid_volumes
## Deploy Plan
- Merge to master → post-merge auto-publishes package
- Infra dependency PR auto-created to bump pinned grm version
- Runners pick up the new config on next `make setup` or ansible apply
## Rollback Plan
- Revert the merge commit
- Set `gitea_runner_pre_cache_schedule: ""` to disable the timer without
reverting
## Acceptance Criteria
- [x] REQ-1: `force_pull: false` in runner config template
- [x] REQ-2: `options` field mounts host Docker socket as `/run/host-docker.sock`
- [x] REQ-3: `valid_volumes` list includes both socket mount targets
- [x] REQ-4: `pre_cache.yml` task creates and manages systemd user timer
- [x] REQ-5: Service and timer templates created
- [x] REQ-6: Timer disabled gracefully when schedule or images empty
+34
View File
@@ -0,0 +1,34 @@
# GRM-165: Adopt spec-driven CI gates and pr-review skill
## Problem
grm uses the old `devx.ci.pr_review` CI step and lacks the new spec-driven
CI gates (validate_spec, check_pr_size). It also needs a create_dependency_pr
step in post-merge to auto-create infra PRs when grm publishes a new version.
## Approach
Replace pr_review CI steps with validate_spec + check_pr_size + curl-based
APPROVE. Add create_dependency_pr step to post-merge. Add the spec-driven-
development and pr-review skills. Update AGENTS.md.
REQ-1: Replace pr_review CI steps with validate_spec + check_pr_size + curl-based APPROVE
REQ-2: Add create_dependency_pr step to post-merge for auto-creating infra PR to bump grm version
REQ-3: Add spec-driven-development and pr-review skills under `.devin/skills/`
REQ-4: Update AGENTS.md to document spec-driven development workflow and pr-review skill
## Test Plan
- Verify CI workflow YAML passes actionlint
- Verify post-merge.yml includes create_dependency_pr step with correct DEVX_TASK_PREFIX (GRM)
- Verify validate_spec and check_pr_size steps reference correct DEVX_TASK_PREFIX (GRM)
## Deploy Plan
- Merge to master via auto-merge workflow
- Post-merge workflow handles release + publish + dependency PR automatically
## Rollback Plan
- Revert the merge commit; CI reverts to pr_review-based workflow
## Acceptance Criteria
- [x] REQ-1: CI workflow uses validate_spec + check_pr_size + curl APPROVE instead of pr_review
- [x] REQ-2: post-merge.yml includes create_dependency_pr step targeting oblachno/infra with package grm
- [x] REQ-3: `.devin/skills/spec-driven-development/SKILL.md` and `.devin/skills/pr-review/SKILL.md` exist
- [x] REQ-4: AGENTS.md documents spec-driven development workflow and pr-review skill
+21
View File
@@ -0,0 +1,21 @@
# GRM-167: Bump devx to v0.51.0
## Problem
devx v0.51.0 released with role defaults path support for create_dependency_pr. grm pins v0.50.2.
## Approach
Bump devx pin in pyproject.toml.
REQ-1: Bump devx from v0.50.2 to v0.51.0 in pyproject.toml
## Test Plan
- Verify CI passes with new devx version
## Deploy Plan
- Merge to master, auto-release
## Rollback Plan
- Revert the merge commit
## Acceptance Criteria
- [x] REQ-1: devx pinned to v0.51.0 in pyproject.toml
+21
View File
@@ -0,0 +1,21 @@
# GRM-168: Bump devx to v0.51.9
## Problem
grm pins devx@v0.51.0 which rejects `deps:` as a conventional commit type,
causing post-merge CI failures on dependency bump commits.
## Approach
REQ-1: Bump devx from v0.51.0 to v0.51.9 in pyproject.toml
## Test Plan
- `make lint-all` passes
- `make pytest-cov` passes
## Deploy Plan
- Merge to master
## Rollback Plan
- Revert the merge commit
## Acceptance Criteria
- [x] REQ-1: Bump devx from v0.51.0 to v0.51.9 in pyproject.toml
+28
View File
@@ -0,0 +1,28 @@
# GRM-171: Use kireto token for auto-merge approval review
## Problem
The auto-merge workflow posts approval reviews with
`REVIEWER_GITEA_API_TOKEN` (emil), but emil is also the PR creator.
Gitea ignores self-approvals, so the merge fails with HTTP 405
`Does not have enough approvals`.
## Approach
REQ-1: Change the approval review step in `.gitea/workflows/ci.yml` to use
`DEVELOPER_GITEA_API_TOKEN` (kireto) instead of
`REVIEWER_GITEA_API_TOKEN` (emil), since kireto is a different user
than the PR creator.
## Test Plan
- `make lint-all` passes (workflow-lint validates the YAML)
- Next auto-merge PR succeeds (approval posted by kireto, merge completes)
## Deploy Plan
- Merge to master
## Rollback Plan
- Revert the merge commit
## Acceptance Criteria
- [x] REQ-1: Change the approval review step in `.gitea/workflows/ci.yml`
to use `DEVELOPER_GITEA_API_TOKEN` (kireto) instead of
`REVIEWER_GITEA_API_TOKEN` (emil)
+38
View File
@@ -0,0 +1,38 @@
# GRM-172: Audit and document pre-pull image usage guidelines
## Problem
The grm repo contains a runner-level `pre_pull_images.yml` task file that
pre-pulls Docker images to avoid repeated pulls on every CI run. However,
there was no audit confirming that molecule `prepare.yml` files are not
also redundantly pre-pulling images that the runner setup already caches.
Wasteful pre-pulling wastes CI time and disk space.
## Approach
Audit all molecule `prepare.yml` files in the grm repo for pre-pull tasks.
The audit found NO molecule prepare.yml files contain pre-pull tasks, so no
code removal is needed. Document the audit findings in a spec and add a
comment to the runner-level `pre_pull_images.yml` task file clarifying that
it should not be used for images that molecule tests pull themselves (to
avoid redundant pulls).
REQ-1: Audit all molecule prepare.yml files for pre-pull tasks and confirm none exist
REQ-2: Add documentation comment to pre_pull_images.yml stating it should not be used for CI runner container images (already cached by runner setup) or images molecule tests pull themselves
REQ-3: Confirm gitea_runner_pre_pull_images default remains empty ([]) which is correct
## Test Plan
- Grep all molecule prepare.yml files for pre-pull patterns confirms zero matches
- Verify pre_pull_images.yml comment is present and accurate
- Verify gitea_runner_pre_pull_images default is [] in defaults/main.yml
- Run make lint-ci to confirm no lint regressions
## Deploy Plan
- Merge to master via auto-merge workflow
- No runtime changes; documentation-only
## Rollback Plan
- Revert the merge commit; comments are removed, no functional impact
## Acceptance Criteria
- [x] REQ-1: No molecule prepare.yml files in the grm repo contain pre-pull tasks (audit confirmed via grep)
- [x] REQ-2: pre_pull_images.yml contains a comment documenting it should not be used for CI runner container images or images molecule tests pull themselves
- [x] REQ-3: gitea_runner_pre_pull_images default remains empty ([]) in defaults/main.yml
+2 -2
View File
@@ -36,7 +36,7 @@ ci = [
"build==1.5.1",
"twine==6.2.0",
# Reusable CI/CD and dev tools (auto-merge, pr-review, pre-push checks, etc.)
"devx @ git+https://git.oblachno.oblachno.fyi/oblachno-oss/devx.git@v0.50.1",
"devx @ git+https://git.oblachno.oblachno.fyi/oblachno-oss/devx.git@v0.51.9",
]
# Lint and type-checking tools (validate job)
lint = [
@@ -56,7 +56,7 @@ molecule = [
dev = [
"grm[ci,lint,molecule]",
# Reusable CI/CD and dev tools (pre-push hooks, create-task, create-pr)
"devx @ git+https://git.oblachno.oblachno.fyi/oblachno-oss/devx.git@v0.50.1",
"devx @ git+https://git.oblachno.oblachno.fyi/oblachno-oss/devx.git@v0.51.9",
# Non-Python dev dependency: checkmake (Makefile linter)
# Install via: go install github.com/checkmake/checkmake/cmd/checkmake@latest
]
+1 -1
View File
@@ -1,3 +1,3 @@
"""Gitea Runner Manager — lean CLI for managing Gitea Actions runners."""
__version__ = "0.20.0"
__version__ = "0.23.0"