forgeo-cli 0.8.0__tar.gz → 0.9.0__tar.gz

{forgeo_cli-0.8.0 → forgeo_cli-0.9.0}/CHANGELOG.md

@@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-08-23
+
+### Added
+
+- GitHub Issues and GitLab Issues task providers. Set `backlog_provider: github`
+  or `gitlab` and point `backlog:` at the API base URL
+  (`https://api.github.com` or `https://github.example.com/api/v3` for
+  Enterprise; `https://gitlab.com` or a self-hosted root for GitLab). Issue
+  numbers/`iid`s become Forgeo task ids, `open`/`opened` vs `closed` maps to
+  `OPEN`/`COMPLETED`, and `forgeo-running`/`forgeo-blocked`/`forgeo-failed`
+  labels (configurable via `label_prefix`) represent the remaining states.
+  Engine state — blocker and failure reasons, retry counters, claim time,
+  dependencies, and bounded agent output — is stored in a hidden
+  `<!-- forgeo: {...} -->` block inside the issue body/description, so the
+  visible text stays human-readable and no custom fields or issue properties
+  are required.
+- `github` and `gitlab` config blocks: `repo` (`owner/repo` or project path/id),
+  `token_env` (PAT from an environment variable, never stored in the file),
+  `label_prefix`/`property_key`, pagination, timeouts, stale-claim recovery
+  via `claim_timeout_seconds`, and optional workflow/field mappings mirroring
+  the Jira provider.
+- Shared issue-provider helpers extracted to `backlog_issue_base` and a new
+  `DocumentBacklogStore` / `IssueBacklogBase` split in `backlog.py`,
+  unifying claim, label, and engine-state handling across Jira, GitHub, and
+  GitLab. `forgeo validate` now checks any remote backlog with a
+  provider-specific message, and `config/forgeo.yaml`, the README, and the
+  backlog/configuration docs list and document all five providers
+  (`file`, `http`, `jira`, `github`, `gitlab`).
+
 ## [0.8.0] - 2026-08-21
 
 ### Added
@@ -360,7 +389,8 @@ Initial release of the scheduled, agent-driven software forgeo.
   overlapping-run skipping.
 - Dogfooding docs removed; local configs kept out of the repository.
 
-[Unreleased]: https://github.com/lucaGazzola/forgeo/compare/v0.8.0...HEAD
+[Unreleased]: https://github.com/lucaGazzola/forgeo/compare/v0.9.0...HEAD
+[0.9.0]: https://github.com/lucaGazzola/forgeo/compare/v0.8.0...v0.9.0
 [0.8.0]: https://github.com/lucaGazzola/forgeo/compare/v0.7.3...v0.8.0
 [0.7.3]: https://github.com/lucaGazzola/forgeo/compare/v0.7.2...v0.7.3
 [0.7.2]: https://github.com/lucaGazzola/forgeo/compare/v0.7.1...v0.7.2

{forgeo_cli-0.8.0 → forgeo_cli-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: forgeo-cli
-Version: 0.8.0
+Version: 0.9.0
 Summary: A scheduled software forgeo: executes backlog tasks on main, refactors when idle, and writes BLOCKER.md when it needs human input.
 Project-URL: Homepage, https://forgeo.org
 Project-URL: Documentation, https://forgeo.org
@@ -121,8 +121,8 @@ configuration, start the daemon.
 # Backlog format), created on first use:
 #   .forgeo/backlog.json
 
-# Or: configure `backlog_provider: jira` and set `backlog` to a Jira base URL
-# (see the Jira backlog documentation).
+# Or: configure `backlog_provider: jira` / `github` / `gitlab` and set `backlog` to the provider base URL
+# (see the backlog documentation for Jira/GitHub/GitLab).
 
 # Or: add tasks from the web console once your forgeo is registered
 # (first `forgeo start` registers it automatically):
@@ -211,11 +211,17 @@ and get one aggregate overview with the central dashboard, `forgeo web`.
 | Web dashboard & HTTP API | [Web console & HTTP API](docs/web-console-api.md) |
 
 Everything is stored in plain files: the local backlog, `forgeo.log`, and
-`BLOCKER.md` whenever a decision is pending. The backlog can also live in
-another application behind an `http(s)` URL, or in Jira. HTTP backlogs
-exchange the complete task document; Jira issues are read and transitioned
-individually with workflow state and engine metadata stored on the issue (see
-[Backlog format](docs/backlog.md)). A *file* backlog is snapshotted (rotating
+`BLOCKER.md` whenever a decision is pending. Backlog providers (see
+[Backlog format](docs/backlog.md)):
+
+- [JSON file](docs/backlog.md#a-json-file-backlog)
+- [HTTP endpoint](docs/backlog.md#a-backlog-over-http)
+- [Jira](docs/backlog.md#a-jira-backlog)
+- [GitHub](docs/backlog.md#a-github-backlog)
+- [GitLab](docs/backlog.md#a-gitlab-backlog)
+
+File and HTTP backlogs exchange the complete task document; Jira/GitHub/GitLab issues are read and transitioned
+individually with workflow state and engine metadata stored on the issue. A *file* backlog is snapshotted (rotating
 `backlog.json.bak` files) before every agent run and on daemon startup, and
 restored automatically if it is ever found corrupt — a bad write never loses
 your tasks.

{forgeo_cli-0.8.0 → forgeo_cli-0.9.0}/README.md

@@ -67,8 +67,8 @@ configuration, start the daemon.
 # Backlog format), created on first use:
 #   .forgeo/backlog.json
 
-# Or: configure `backlog_provider: jira` and set `backlog` to a Jira base URL
-# (see the Jira backlog documentation).
+# Or: configure `backlog_provider: jira` / `github` / `gitlab` and set `backlog` to the provider base URL
+# (see the backlog documentation for Jira/GitHub/GitLab).
 
 # Or: add tasks from the web console once your forgeo is registered
 # (first `forgeo start` registers it automatically):
@@ -157,11 +157,17 @@ and get one aggregate overview with the central dashboard, `forgeo web`.
 | Web dashboard & HTTP API | [Web console & HTTP API](docs/web-console-api.md) |
 
 Everything is stored in plain files: the local backlog, `forgeo.log`, and
-`BLOCKER.md` whenever a decision is pending. The backlog can also live in
-another application behind an `http(s)` URL, or in Jira. HTTP backlogs
-exchange the complete task document; Jira issues are read and transitioned
-individually with workflow state and engine metadata stored on the issue (see
-[Backlog format](docs/backlog.md)). A *file* backlog is snapshotted (rotating
+`BLOCKER.md` whenever a decision is pending. Backlog providers (see
+[Backlog format](docs/backlog.md)):
+
+- [JSON file](docs/backlog.md#a-json-file-backlog)
+- [HTTP endpoint](docs/backlog.md#a-backlog-over-http)
+- [Jira](docs/backlog.md#a-jira-backlog)
+- [GitHub](docs/backlog.md#a-github-backlog)
+- [GitLab](docs/backlog.md#a-gitlab-backlog)
+
+File and HTTP backlogs exchange the complete task document; Jira/GitHub/GitLab issues are read and transitioned
+individually with workflow state and engine metadata stored on the issue. A *file* backlog is snapshotted (rotating
 `backlog.json.bak` files) before every agent run and on daemon startup, and
 restored automatically if it is ever found corrupt — a bad write never loses
 your tasks.

{forgeo_cli-0.8.0 → forgeo_cli-0.9.0}/docs/backlog.md

@@ -1,12 +1,24 @@
 # Backlog format
 
-The backlog is a **plain JSON document**. By default it is a file you edit by
-hand, living wherever `backlog:` points in [forgeo.yaml](configuration.md) —
-`backlog.json` at the project root, or `.forgeo/backlog.json` when generated by
-`forgeo init`. Keep it outside the repository if you can so the agent never
-touches it. It can also be [served over HTTP](#a-backlog-over-http) by another
-application, in which case the document below is exactly what that endpoint
-exchanges with Forgeo, or it can be sourced directly from [Jira](#a-jira-backlog).
+- [JSON file](#a-json-file-backlog)
+- [HTTP endpoint](#a-backlog-over-http)
+- [Jira](#a-jira-backlog)
+- [GitHub](#a-github-backlog)
+- [GitLab](#a-gitlab-backlog)
+
+The backlog is a **plain JSON document** — a list of tasks Forgeo works through
+one by one.
+
+## A JSON file backlog
+
+By default the backlog is a file you edit by hand, living wherever `backlog:`
+points in [forgeo.yaml](configuration.md) — `backlog.json` at the project root,
+or `.forgeo/backlog.json` when generated by `forgeo init`. Keep it outside the
+repository if you can so the agent never touches it. It can also be
+[served over HTTP](#a-backlog-over-http) by another application, in which case
+the document below is exactly what that endpoint exchanges with Forgeo, or it
+can be sourced directly from [Jira](#a-jira-backlog),
+[GitHub](#a-github-backlog) or [GitLab](#a-gitlab-backlog).
 
 ```json
 {
@@ -424,3 +436,75 @@ If a process dies while holding a claim, a later cycle releases claims older
 than `claim_timeout_seconds` and returns them to the configured open status.
 An unavailable Jira endpoint fails the cycle; it is never treated as an empty
 backlog.
+
+## A GitHub backlog
+
+Set `backlog_provider: github` and point `backlog:` at the GitHub API base URL:
+
+```yaml
+backlog_provider: github
+backlog: https://api.github.com
+
+github:
+  repo: owner/repo
+  token_env: GITHUB_TOKEN
+  label_prefix: forgeo
+```
+
+Use `https://api.github.com` for github.com or `https://github.example.com/api/v3` for Enterprise.
+
+### Mapping and lifecycle
+
+- GitHub issue numbers are Forgeo task ids.
+- `title`, `body` (visible part), `created_at` and `updated_at` map to task fields.
+- `state` `open` maps to `OPEN`; `closed` maps to `COMPLETED`.
+- Labels `forgeo-running`, `forgeo-blocked`, `forgeo-failed` (prefix configurable via `label_prefix`) represent running, blocked, and failed tasks. An open issue carrying `forgeo-running` is considered claimed and filtered from picking.
+- Closing an issue completes its task; reopening it moves the task back to `OPEN`.
+
+Forgeo stores blocker reasons, failure reasons, retry counters, claim time, dependencies, and bounded agent output in a hidden JSON block inside the issue body: `<!-- forgeo: {...} -->`. The visible body remains human-readable; the hidden block is stripped on read and merged on write. No GitHub issue property or custom field is required. Set `github.property_key` only for symmetry; the marker key is `forgeo` by default.
+
+Dependencies are persisted via the hidden block's `dependencies` list; no GitHub issue links are required.
+
+### Authentication
+
+GitHub credentials are never stored in `forgeo.yaml`:
+
+- `token_env` names the environment variable holding a personal-access token (classic or fine-grained). The token is sent as `Authorization: Bearer <token>`.
+
+### Runtime behavior
+
+The daemon lists GitHub issues with paginated `GET /repos/{owner}/{repo}/issues?state=all`. A task is claimed by adding the `forgeo-running` label and persisting `claimed_at` in the hidden block. If a process dies while holding a claim, a later cycle releases claims older than `claim_timeout_seconds` and removes the running label. An unavailable GitHub endpoint fails the cycle.
+
+## A GitLab backlog
+
+Set `backlog_provider: gitlab` and point `backlog:` at the GitLab base URL:
+
+```yaml
+backlog_provider: gitlab
+backlog: https://gitlab.example.com
+
+gitlab:
+  repo: group/project   # or numeric project id
+  token_env: GITLAB_TOKEN
+  label_prefix: forgeo
+```
+
+GitLab base URL is the instance root (e.g. `https://gitlab.com`); the client appends `/api/v4`.
+
+### Mapping and lifecycle
+
+- GitLab issue `iid`s are Forgeo task ids.
+- `title`, `description` (visible part), `created_at` and `updated_at` map to task fields.
+- `state` `opened` maps to `OPEN`; `closed` maps to `COMPLETED`.
+- Labels `forgeo-running`, `forgeo-blocked`, `forgeo-failed` represent running, blocked, and failed tasks, like GitHub. An `opened` issue with `forgeo-running` is filtered as claimed.
+- Closing/reopening via `state_event` transitions the task to `COMPLETED`/`OPEN`.
+
+Forgeo stores engine state the same way as GitHub: a hidden `<!-- forgeo: {...} -->` block inside `description`. Dependencies and other task attributes are kept there; no GitLab custom fields are required.
+
+### Authentication
+
+- `token_env` names the environment variable holding a personal-access token. Sent as `PRIVATE-TOKEN` and `Authorization: Bearer`.
+
+### Runtime behavior
+
+Paginated `GET /api/v4/projects/:id/issues?state=all`. Claiming adds `forgeo-running` and `claimed_at`; stale claims older than `claim_timeout_seconds` are released. An unavailable GitLab endpoint fails the cycle.

{forgeo_cli-0.8.0 → forgeo_cli-0.9.0}/docs/configuration.md

@@ -22,11 +22,13 @@ paths), so `forgeo restart` is still used for those.
 | <span style="white-space: nowrap">`interval_minutes`</span> | `60` | How often Forgeo runs (≥ 1). |
 | <span style="white-space: nowrap">`branch`</span> | `main` | The single branch everything is committed to. |
 | <span style="white-space: nowrap">`remote`</span> | — | Remote to push to (e.g. `origin`); omit to only commit locally. |
-| <span style="white-space: nowrap">`backlog`</span> | `backlog.json` | The task backlog: the path of a JSON file, an HTTP endpoint serving the same document, or a Jira base URL when `backlog_provider: jira`. |
-| <span style="white-space: nowrap">`backlog_provider`</span> | `auto` | `auto` infers file/HTTP from `backlog`, or Jira when a `jira` block is present; explicitly choose `file`, `http`, or `jira` when preferred. |
+| <span style="white-space: nowrap">`backlog`</span> | `backlog.json` | The task backlog: the path of a JSON file, an HTTP endpoint serving the same document, or a base URL for `jira`/`github`/`gitlab` providers. |
+| <span style="white-space: nowrap">`backlog_provider`</span> | `auto` | `auto` infers file/HTTP from `backlog`, or `jira`/`github`/`gitlab` when the corresponding block is present; explicitly choose `file`, `http`, `jira`, `github`, or `gitlab`. |
 | <span style="white-space: nowrap">`state_dir`</span> | — | Directory for Forgeo's runtime files (locks, run history, daemon state). Remote backlogs default this to the directory of `forgeo.yaml`. |
-| <span style="white-space: nowrap">`backlog_auth`</span> | — | OAuth2 client credentials for a backlog URL that requires them (see [below](#backlog_auth)). |
+| <span style="white-space: nowrap">`backlog_auth`</span> | — | OAuth2 client credentials for a backlog URL that requires them (see [below](#backlog_auth)). Only for `http` provider. |
 | <span style="white-space: nowrap">`jira`</span> | — | Jira REST, workflow, authentication, and custom-field settings. Required when `backlog_provider: jira`. |
+| <span style="white-space: nowrap">`github`</span> | — | GitHub REST settings. Required when `backlog_provider: github`. |
+| <span style="white-space: nowrap">`gitlab`</span> | — | GitLab REST settings. Required when `backlog_provider: gitlab`. |
 | <span style="white-space: nowrap">`blocker_file`</span> | `BLOCKER.md` | Where `BLOCKER.md` is written. Keep it outside the repo so it is never committed. |
 | <span style="white-space: nowrap">`agent_command`</span> | — | The coding agent: any shell command (string) or argv list. **Required.** |
 | <span style="white-space: nowrap">`agent_timeout_seconds`</span> | — | Optional: kill the agent after this many seconds (`null` = never). |
@@ -140,6 +142,55 @@ truth for human changes.
 | `jira.workflow` | defaults | Status ids or names for open, running, blocked, completed, and failed transitions. |
 | `jira.fields` | — | Optional custom-field ids for task attributes such as acceptance criteria and dependencies. |
 
+### GitHub backlog
+
+Forgeo can read and update GitHub issues directly. Set `backlog_provider: github` and make `backlog` the GitHub API base URL. Issue numbers become task ids. Labels and a hidden JSON block in the issue body hold Forgeo's engine state.
+
+```yaml
+backlog_provider: github
+backlog: https://api.github.com
+github:
+  repo: owner/repo
+  token_env: GITHUB_TOKEN
+  label_prefix: forgeo
+```
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `github.repo` | — | Required owner/repo. |
+| `github.auth` | — | Required PAT env var `token_env`. |
+| `github.label_prefix` | `forgeo` | Prefix for running/blocked/failed labels. |
+| `github.property_key` | `forgeo` | Marker key for hidden body block (symmetry). |
+| `github.page_size` | `30` | Issues per page. |
+| `github.max_issues` | `1000` | Max issues read. |
+| `github.timeout_seconds` | `30` | HTTP timeout. |
+| `github.claim_timeout_seconds` | `86400` | Stale claim timeout. |
+| `github.workflow` | defaults | State/label mapping. |
+| `github.fields` | — | Optional field mappings. |
+
+### GitLab backlog
+
+```yaml
+backlog_provider: gitlab
+backlog: https://gitlab.example.com
+gitlab:
+  repo: group/project
+  token_env: GITLAB_TOKEN
+```
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `gitlab.repo` | — | Required project path or numeric id. |
+| `gitlab.auth` | — | Required PAT env var `token_env`. |
+| `gitlab.label_prefix` | `forgeo` | Prefix for labels. |
+| `gitlab.property_key` | `forgeo` | Marker key. |
+| `gitlab.page_size` | `30` | Issues per page. |
+| `gitlab.max_issues` | `1000` | Max issues. |
+| `gitlab.timeout_seconds` | `30` | HTTP timeout. |
+| `gitlab.claim_timeout_seconds` | `86400` | Stale claim timeout. |
+| `gitlab.workflow` | defaults | State mapping. |
+| `gitlab.fields` | — | Optional field mappings. |
+
 ## Key details
 
 ### `backlog_auth`

{forgeo_cli-0.8.0 → forgeo_cli-0.9.0}/install.sh

@@ -14,7 +14,7 @@ set -eu
 
 REPO_OWNER="lucaGazzola"
 REPO_NAME="forgeo"
-DEFAULT_VERSION="0.8.0"
+DEFAULT_VERSION="0.9.0"
 MIN_PYTHON="3.11"
 PYPI_PACKAGE="forgeo-cli"
 PREFIX="${FORGEO_PREFIX:-${HOME:-}/.local}"

{forgeo_cli-0.8.0 → forgeo_cli-0.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "forgeo-cli"
-version = "0.8.0"
+version = "0.9.0"
 description = "A scheduled software forgeo: executes backlog tasks on main, refactors when idle, and writes BLOCKER.md when it needs human input."
 readme = "README.md"
 requires-python = ">=3.11"

{forgeo_cli-0.8.0 → forgeo_cli-0.9.0}/src/forgeo/__init__.py

@@ -7,4 +7,4 @@ try:
 
     __version__ = _pkg_version("forgeo-cli")
 except PackageNotFoundError:  # standalone binary: no installed package metadata
-    __version__ = "0.8.0"
+    __version__ = "0.9.0"