2
Migration to Gitea
Sam Catlow edited this page 2026-10-11 14:43:36 +11:00

Finish the Gitea migration

Guide home · Next: project tracking

The code and history are available in sam/archie. The remaining migration is the development workflow, distribution, and tooling around the repository.

1. Establish the development home

Use sam/archie and /work/apps/archie-sha1 for new work. The checkout's origin already points to Gitea.

Keep an independent repository backup. Review the preserved branches and retain the ones that still contain intended work. Decide branch cleanup explicitly after that review.

Treat the old GitHub and Gitea repositories as historical references. Disable superseded automatic publishing and unintended mirroring. Verify their visibility separately before treating them as private archives. Confirm repository and backup restoration works before deleting any historical data.

A repository rename does not require an immediate rename of Go import paths or service binaries. Keep those changes separate unless a consumer actually requires them.

Complete when: a fresh clone is the routine development checkout, active branches are understood, backups are independently recoverable, and superseded publication is disabled.

2. Reconnect runners and establish one quality gate

Identify whether the existing runners serve Gitea Actions or another CI system such as Woodpecker. Use the system already operating reliably. Inspect its version, labels, checkout implementation, Docker access, and credentials before porting workflows.

The migrated tree currently contains GitHub workflows, with no Gitea or Woodpecker workflow files. Their comments about an existing Gitea mirror are not evidence of a working pipeline.

Keep the check definitions in the Taskfile. The standard gate is task check; release validation must additionally run the existing task test:full and the release QA described in this guide. Maintain one definition for each check and invoke it from CI. The current deploy workflow maintains a different inline gate, which must be consolidated during the port.

First prove that a runner can clone the recreated repository, check out the selected commit, build, and run the standard gate. Then exercise Archie's actual Git paths: clone/fetch, worktree creation, changes, daemon-owned commit, push, and forge integration. A clone check alone does not cover these operations.

Use caches to shorten repeated work, but retain an uncached release test. Install pinned tool versions and use lockfiles. Record stage durations before optimising further. Give release builds and promotions appropriate concurrency limits so they do not exhaust the runners or race each other.

Complete when: a fresh runner can execute the authoritative gate and the application can perform its required Git operations against the recreated Gitea repository.

3. Make distribution private and usable

Inventory every publishing destination: release attachments, container images, CI artifacts, generated documentation, and source mirrors. In particular, check the visibility of the existing GHCR packages independently of GitHub repository visibility. Download counts alone do not identify who downloaded an image.

Choose Gitea release storage and a private container registry accessible to staging and production. Establish separate CI publishing credentials and read-only deployment credentials. Verify authenticated downloads and pulls from the actual deployment environment, and confirm unauthenticated access is denied.

Update image destinations, release metadata, installer downloads, update discovery, release-note links, and deployment documentation together. The current updater discovers releases from a hard-coded GitHub API URL without authentication. The installer exposes ARCHIE_SOURCE_URL and ARCHIE_RELEASE_BASE_URL, but changing URLs alone does not establish authenticated private downloads.

Keep task-scoped agent credentials separate from host deployment and registry credentials. Never solve private artifact access by placing the daemon's credentials in agent containers.

Complete when: CI can publish privately, deployment can read privately, update discovery finds the intended Gitea release, and no required path depends on unauthenticated access to the old private GitHub repository.

4. Establish the new release baseline

Start the new series at 0.1.0. Keep historical 1.x release tags and assets out of the new release feed. The updater currently chooses the highest semantic version, so mixing the two series would select historical 1.x releases.

Retain historical changelog material as reference and make the new series clear in the changelog and generated release pages. Give the release-note generator an explicit baseline for the new series: with no preceding release tag, the existing script would consider the entire history. Test the first-release path before tagging anything.

Switch the existing installation explicitly to the new release source and candidate version. Verify preservation of data, configuration, accepted work, and image policy. Product version numbering must not reset database migration history.

Complete when: previewing 0.1.0 produces intentional notes, update discovery selects the new series, and a rehearsal can transition the existing installation without data loss.

5. Update the operating instructions

Replace Beads-specific workflow instructions only after the tracker transition. Update AGENTS.md, relevant skills or hooks, CI instructions, installation documentation, and RELEASING.md to match the implemented Gitea process. Identify local hooks tied to the old checkout; avoid copying absolute paths blindly.

Migration acceptance: clean clone → authoritative gate → private candidate artifacts → authenticated staging installation → representative workflow completed. Track each remaining section as a Gitea issue with its completion evidence.