Skip to content

What

Řehoř is an autonomous developer tool. A selected workflow discovers work, implements code changes in target repos, opens PRs/MRs, and maintains them through CI and review cycles. It runs as a polling loop using the Claude Agent SDK, with optional integrations for Jira Cloud, GitHub, GitLab, and persistent memory backed by PostgreSQL.

The bot operates in workflow-defined cycles. Lightweight Python preflight scripts check each workflow's external systems for actionable work. An AI session only starts when there's something to do, so the common "nothing changed" case costs zero tokens.

Why

  • Hands-free work execution — workflow work items get picked up, implemented, and PRed without human intervention
  • Consistent quality — every PR follows the same patterns: persona-specific coding standards, test verification, visual checks for UI changes
  • Scales across repos — one bot instance handles multiple repos via label-based routing and fork-based PRs
  • Learns from past work — completed work is stored as RAG memories, so the bot improves over time
  • Cost-efficient — preflight scripts filter out "nothing to do" cycles before any AI tokens are spent

How

  1. Configure your instance — select a workflow and env presets using the Presets Overview
  2. Configure the workflow's source — for jira-sprint, add the bot label and a repo:<name> label to groomed Jira tickets; custom workflows define their own source
  3. Preflight scripts gather data — each cycle, workflow-specific Python scripts check configured external systems for actionable changes
  4. AI session runs only when needed — if any preflight script returns "start", Claude receives all gathered data and acts on it
  5. PR lifecycle is automatic — the bot handles CI failures, review feedback, merge conflicts, and post-merge cleanup

For the full cycle diagram and state machine, see Bot Workflow Loop.

Workflow source reports actionable work
    → Workflow claims or tracks work item
        → Agent implements on branch bot/KEY
            → PR or equivalent artifact opened
                → CI fix / review feedback loop
                    → Work completed, learnings stored

Example

A real ticket: RHCLOUD-37254 ("RBAC allowing roles with same name as System Roles").

  1. A human groomed the ticket and added labels hcc-ai-platform-accessmanagement and repo:insights-rbac
  2. The bot found it via JQL, assigned itself, transitioned to "In Progress", added it to the active sprint
  3. It cloned insights-rbac, created branch bot/RHCLOUD-37254, loaded the rbac persona, read the repo's CLAUDE.md, and implemented the fix
  4. It pushed the branch, opened a PR via gh pr create, transitioned the ticket to "Code Review", and commented on Jira with the PR link
  5. A human reviewed the PR. Each cycle, the bot checked for new feedback and addressed comments
  6. Once merged, the bot transitioned the ticket to "Done" and stored learnings in RAG memory

For more examples (cross-repo features, CVE triage, UI changes with screenshots), see the Operations Guide.

Common Mistakes

Wrong NetworkPolicy proxy label. The proxy pod's label is app.kubernetes.io/name: devbot-proxy, not proxy. Using the wrong label silently blocks all bot egress. The bot will start but hang forever waiting for the executor connection. See Onboarding for details.

DNS port is 5353, not 53. OpenShift uses a custom DNS server on port 5353 in the openshift-dns namespace. Standard port 53 or kube-dns selectors cause pods to hang on name resolution.

Missing ScaledObject.keda.sh in managedResourceTypes. Without this, app-interface prunes the KEDA cron scaler on every sync, and your bot won't auto-scale. See Scheduling.

Unused env presets waste build time. The node and go presets install version managers and compilers. Skip them if your repos don't need them. See Env Presets.

Troubleshooting

Jira sprint workflow isn't picking up tickets:

  • Check that tickets have the correct primary label matching your BOT_LABEL
  • Tickets must be unassigned — the bot skips assigned tickets
  • Verify repo:<name> labels match keys in project-repos.json
  • Check if the bot is at the 10-task capacity limit via the dashboard

Bot pod starts but hangs:

  • Check NetworkPolicy labels (must be devbot-proxy, not proxy)
  • Check DNS egress (port 5353, not 53, targeting openshift-dns namespace)
  • Verify executor connectivity in logs: "Connected to executor at devbot-proxy:9090"

Bot runs but never starts AI sessions:

  • Check preflight logs — all scripts returning "skip" means no actionable work was found
  • Verify there are open PRs with CI failures, review feedback, or unassigned sprint tickets
  • Look for "error" results in preflight output, which indicate API connectivity issues

Custom workflows have their own source and preflight checks. Use their workflow documentation instead of applying Jira-specific checks.

For the full operations guide, see OPERATIONS.md.

Documentation

Section What you'll find
Onboarding a New Instance Step-by-step guide: runner repo, deploy template, Konflux, app-interface, Jira setup
Instance Configuration instance.yaml, env-preset selection, and configuration precedence
Scheduling KEDA cron scaler configuration for business-hours-only operation
Bot Workflow Loop Cycle architecture, preflight system, task state machine with diagrams
Debugging Cycles and Improving Agents Find cycle transcripts, diagnose decisions, and improve agent behavior safely
Git Auth Proxy Credential isolation design for the proxy sidecar
Preset System Design Architecture decisions behind the preset composition model
Presets Overview How workflow and env presets work together
Workflow Presets Built-in workflow reference (jira-sprint)
Env Presets Available env presets: node, go, browser, container-scan, slack, etc.
Custom Workflows Building your own workflow for specialized automation
Custom Preflight Scripts Writing pre-session data-gathering scripts
Preset Migration Guide Migrating existing instances to the preset system
OpenCode Migration Design Migrating from Claude Code and Vertex auth to OpenCode and direct OpenAI keys
Roadmap Planned improvements and new capabilities
Operations Overview Daily operations and verification runbooks

Contributing to these docs

Preview changes locally:

pip install -r docs/requirements.txt
mkdocs serve

Open http://127.0.0.1:8000 to preview. Run mkdocs build --strict before pushing to catch broken links.