1
Project Tracking
Sam Catlow edited this page 2026-10-11 14:40:58 +11:00

Project tracking in Gitea

Guide home · Previous: migration · Next: staging and QA

Gitea will become the authoritative tracker. The change is complete only when the development instructions and agents use it too.

Review the backlog before importing it

Export and retain the existing Beads data, dependencies, and any durable project memories. Retain old forge issues for reference. The export is a historical backup, not a second live tracker.

Review open work against the current tree. Create a Gitea issue only if the problem still exists or the feature is still intended. Record old IDs where useful for tracing context. Bring across real blockers and acceptance criteria. Avoid importing completed work as open tasks or preserving speculative plans as commitments.

There may be useful project conventions in Beads memories. Move the ones still applicable into the appropriate repository instructions or wiki page before retiring hooks that load them.

Use one project board

Column Meaning
Planned Still intended; not being implemented
Implementing Someone is actively changing it
Ready for QA Implementation and standard gate are complete
Verified in staging The packaged candidate demonstrated the required behaviour
Released Production verification recorded for the release carrying the change

A closed implementation issue can be associated with a release whose deployment is still pending. Keep implementation completion and release completion distinct; record the version and release issue rather than forcing every issue through identical deployment work.

Start with a small label set: bug, feature, release, infrastructure, and blocked. A milestone describes a bounded outcome. Use separate milestones for completing the private release pipeline, releasing 0.1.0, and reaching the supported product boundary for 1.0.0.

Keep each issue concrete

Every implementation issue needs:

  • The observed problem or wanted behaviour.
  • The smallest complete scope.
  • Any dependency that actually blocks it.
  • Acceptance criteria stated as observable behaviour.
  • Completion evidence and the commit or release carrying it.

Avoid putting credentials or private operational details in reusable issue templates. Link restricted operational records where needed.

Create a release issue for each candidate

The release issue is the place to assemble scope, evidence, approval, deployment outcome, and recovery outcome. Use the template in the release process.

Sam owns the decision to promote. The pipeline owns the execution and attaches its evidence. An agent can prepare notes and investigate failures, but it must not substitute an unsupported assertion for QA evidence.

Complete the tracker cutover

Once the reviewed backlog is in Gitea, update repository instructions and agent workflows so they create, claim, and close Gitea issues. Remove obsolete Beads hooks and synchronization jobs from the active workflow. Preserve the historical data.

Complete when: a real piece of work can be planned, implemented, reviewed, and closed entirely through Gitea, and no required instruction still routes it through Beads.