REI HARNESS / PRODUCT DOSSIER

SHEET 06 / 06

v0.3.0 · EN

Product · GitHub Issues

GitHub Issues

Optional GitHub Issues integration: issue and branch for Features, PR and merge on order, GitHub as a projection.

Optional GitHub Issues integration · projection of the work

P.01Projection

Featured sheet

An optional integration

GitHub Issues is a projection of the work, not its source of truth. The integration is optional: if the integrations.github key does not exist or enabled is false, the flow is identical and the Leader does not mention GitHub Issues.

Projection, not source

.rei/specs/<id>/

source of truth

Planning, progress and history live in the repository, not in the issue.

  • Issue

    It exists, is assigned and is closed as a reflection of the Work Item.

  • Branch

    It holds the work the Reviewer verifies.

  • PR

    It proposes the change; .rei still rules the state.

Optional integration: enabled with rei github enable and the flow works without it.

  • The CLI never calls GitHub: the real actions are run by gh and git under the Leader's explicit order.
  • .rei rules the execution of the Work Item; the issue rules the problem, the scope and the discussion.
  • The configuration lives in .rei/config.json, under integrations.github.

P.02Commands

Enable, disable and check

rei github resolves the configuration with this precedence: explicit flag, previous value, detection from git, and default value. status is offline and read-only: it does not call gh or the GitHub API.

  1. rei github <enable|disable|status>

    Enables, disables or checks the optional GitHub Issues integration. The CLI never calls GitHub.

Configuration
rei github enable --repo owner/name --base main --strategy squash
rei github disable
rei github status

An unknown, repeated, valueless or invalid flag is incorrect use and does not write the configuration. disable keeps repo, base, mergeStrategy and links.json.

P.03Gate

Issue and branch for Features only

The issue + branch gate runs only when meta.json is in ready, the user approves, the integration is active and the Work Item is a Feature. A Task is worked on the base branch, with no issue or branch, and there is no opt-in for Tasks.

P.04PR and merge

PR and merge on order

There is never a commit, push, PR or merge without an explicit order from the user. The merge strategy comes from the configuration (squash by default) and the merge is not automatic: there is no auto-merge and no --admin.

P.05Epics

Epics, backlog and labels

The integration includes epics, a backlog of child issues, adoption, publishing the spec, assignment and closing the epic. links.json is a recoverable local index, not the source of truth.

Markers identify; labels only help a person. If a marker appears duplicated or more than one issue has the same marker, the action stops and the anomaly is reported.

github.com · issues/3

Header of GitHub Issue #3 "[prueba v2] Épica: módulo de prueba" with state Closed and labels rei, rei:epic. The capture is in Spanish.
Header of epic #3, closed and with its labels published (the capture is in Spanish) · captured 2026-10-27

P.06Out of scope

Out of scope

  • Projects, milestones and native sub-issues.
  • PRs from a fork to upstream.
  • Two-way synchronization.
  • Local pending Work Items as a substitute for the backlog.
  • Self-assignment by workload and time tracking.
  • Providers other than GitHub.
  • Automatic commits, push or merge, --admin and auto-merge.
  • Flags for GitHub actions in rei.