# Gitea → GitHub Release Distribution

Pattern for projects where **development lives privately in Gitea** and **public
releases ship to a separate GitHub repo**. GitHub only ever sees curated,
redacted release snapshots — a clean tagged history, **no Gitea history carried
over**. Repo/owner/package names below are placeholders; substitute per project.

## Placeholders

| Placeholder    | Meaning                                              |
| -------------- | ---------------------------------------------------- |
| `$DEV_REMOTE`  | Gitea dev repo (`https://gitea.example/o/p.git`)     |
| `$REL_REPO`    | Local release git folder (publish staging repo)      |
| `$REL_REMOTE`  | Optional GitHub remote on `$REL_REPO`, added later   |
| `$RELEASE_REF` | Gitea commit/branch/tag to cut from (e.g. `main`)    |
| `$VERSION`     | Version string from package metadata                 |

The release destination is a **local git folder** (`$REL_REPO`). Cutting a
release needs no remote, username, or password. Wiring `$REL_REMOTE` (GitHub)
and pushing is an optional later step, done once the public repo exists.

## Principles

1. **Two repos, two histories.** Never wired as upstream/downstream. Gitea is
   the source of truth; GitHub sees only release snapshots.
2. **Allow-list, never deny-list.** Build the release tree from an explicit list
   of paths to *include*. A blanket worktree copy (minus excludes) is how
   secrets leak — forbidden. Anything not listed does not ship.
3. **Runtime-only minimal payload.** Ship what's needed to install and run:
   source package (incl. bundled `locale/`, templates, assets), packaging
   manifest (`pyproject.toml`/equiv), `README.md`, `LICENSE`, and *sanitized*
   `*.example.*` config/service files. No tests, no CI by default.
4. **Redact real deployment data.** Real configs (hosts, channels, accounts,
   credentials, customer data) must never reach a public repo. Treat any
   non-example config as private until proven otherwise.
5. **Clean history.** One tagged commit (`v$VERSION`) per release; release diffs
   visible on GitHub, Gitea dev history not.
6. **Deliberate and manual.** Cut from a known-good `$RELEASE_REF` by running a
   checked-in script by hand. No push-on-commit.

Do not ship: internal docs, planning/spec material, agent/tooling instructions
(`AGENTS.md`, `CLAUDE.md`, copilot/agent dirs), ai-context notes, Gitea/runner
ops docs. (A Gitea self-hosted-runner workflow is meaningless on GitHub Actions —
if you want CI public, rewrite it GitHub-native, don't copy.)

## SSH auth (when the push is wired up)

Use a per-project SSH host alias backed by a dedicated deploy key in
`~/.ssh/config`:

```sshconfig
Host github-<project>-public
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_<project>-public
  IdentitiesOnly yes
```

Remote becomes `github-<project>-public:OWNER/REPO.git` — no URL/user/password at
release time, key scoped to one repo, `IdentitiesOnly yes` stops SSH offering
unrelated keys. `IdentityFile` may point at the `.pub` when the private key is in
`ssh-agent` (agent signs); otherwise point at the private key. The release script
should check the alias exists before pushing, failing early with guidance.

Once the alias and deploy key are in place for the project, remove this note's
entry from `docs/active-context.md` — the setup is one-time and shouldn't keep
occupying agent context.

## Release procedure

Keep `$REL_REPO` as a separate local folder from the dev clone. Each release:

1. Pick + verify `$RELEASE_REF` in Gitea (tests/CI green).
2. Read `$VERSION` from package metadata.
3. Rebuild `$REL_REPO`'s tracked content from the allow-list at `$RELEASE_REF`
   via `git archive` (committed files only).
4. Commit as a single `Release $VERSION`, tag `v$VERSION` — all local.
5. Optionally push to GitHub once `$REL_REMOTE` exists, and optionally create a
   GitHub Release. PyPI publishing, if any, is a separate explicit step.

### Allow-list export (sketch)

Keep the allow-list in the script, reviewed like code:

```bash
#!/usr/bin/env bash
set -euo pipefail
DEV_REF="${1:-main}"
STAGE="$(mktemp -d)"

PATHS=(                       # Anything not listed does NOT ship.
  src pyproject.toml README.md LICENSE
  examples/app.service examples/config.example.yaml examples/content.example.yaml
)

git archive "$DEV_REF" -- "${PATHS[@]}" | tar -x -C "$STAGE"   # committed only

# Guard: refuse if a non-example file slipped into examples/
if find "$STAGE/examples" -type f ! -name '*.example.*' ! -name '*.service' | grep -q .; then
  echo "Refusing: non-example file in examples/ — possible private data" >&2
  exit 1
fi

# Sync into $REL_REPO, preserving its .git, then commit/tag (push later):
#   rsync -a --delete --exclude='.git' "$STAGE"/ "$REL_REPO"/
#   git -C "$REL_REPO" add -A
#   git -C "$REL_REPO" commit -m "Release $VERSION"
#   git -C "$REL_REPO" tag "v$VERSION"
#   git -C "$REL_REPO" push -u --follow-tags origin main   # once a remote exists
```