get gitea ready
This commit is contained in:
KingKDot
@@ -0,0 +1,183 @@
|
||||
# Make Gitea the primary repository
|
||||
|
||||
The primary repository is
|
||||
<https://overlord.kyun.li/vxaboveground/overlord>. These instructions preserve
|
||||
all Git branches, tags, and commits reachable from them, make Gitea the default
|
||||
remote for development, and configure Gitea to push-mirror to GitLab.
|
||||
|
||||
This runbook targets Gitea 1.27.2. It intentionally does not use
|
||||
`git push --mirror` from a working clone. A working clone contains local and
|
||||
remote-tracking refs that are not part of the public branch/tag contract, and a
|
||||
mirror push can also delete destination refs.
|
||||
|
||||
## Canonical remotes
|
||||
|
||||
The prepared working clone has these exact remotes:
|
||||
|
||||
| Name | Role | Fetch and push URL |
|
||||
| --- | --- | --- |
|
||||
| `origin` | Primary Gitea repository and default push target | `ssh://git@overlord.kyun.li:222/vxaboveground/overlord.git` |
|
||||
| `gitlab` | Former primary; retained for comparison while the Gitea push mirror is verified | `ssh://git@altssh.gitlab.com:443/vxaboveground/overlord.git` |
|
||||
| `forgejo` | Legacy internal Forgejo remote | `ssh://git@10.0.22.220:22/KDOT/Overlord-Public.git` |
|
||||
|
||||
`main` tracks `origin/main`, and `remote.pushDefault` is `origin`. Confirm the
|
||||
local setup before the cutover:
|
||||
|
||||
```bash
|
||||
git remote -v
|
||||
git config --get branch.main.remote
|
||||
git config --get branch.main.merge
|
||||
git config --get remote.pushDefault
|
||||
```
|
||||
|
||||
The expected last three values are `origin`, `refs/heads/main`, and `origin`.
|
||||
Do not push directly to `gitlab` after the server-side push mirror is enabled;
|
||||
Gitea must be the sole write authority.
|
||||
|
||||
## Copy Git history safely
|
||||
|
||||
1. Announce a short write freeze on GitLab. Merge or close outstanding work and
|
||||
wait for running pushes to finish. Commit the migration-preparation files in
|
||||
this checkout and push that commit to `gitlab/main` before taking the final
|
||||
bare clone, so the new Gitea workflows and canonical links are included in
|
||||
the copied history.
|
||||
2. Back up the GitLab project. Create the Gitea repository at the primary URL
|
||||
as an **empty** repository: do not initialize a README, license, or
|
||||
`.gitignore` in Gitea.
|
||||
3. From a temporary directory outside this working clone, make a bare clone of
|
||||
GitLab and inspect it:
|
||||
|
||||
```bash
|
||||
migration_dir="$(mktemp -d)"
|
||||
git clone --bare \
|
||||
ssh://git@altssh.gitlab.com:443/vxaboveground/overlord.git \
|
||||
"$migration_dir/overlord.git"
|
||||
git -C "$migration_dir/overlord.git" fsck --full
|
||||
git -C "$migration_dir/overlord.git" for-each-ref \
|
||||
--format='%(objectname) %(refname)' refs/heads refs/tags
|
||||
```
|
||||
|
||||
4. Add Gitea only to that bare migration clone, then push explicit branch and
|
||||
tag namespaces. These refspecs do not include remote-tracking, CI, merge
|
||||
request, or other implementation-specific refs, and they do not request
|
||||
deletion of destination refs:
|
||||
|
||||
```bash
|
||||
git -C "$migration_dir/overlord.git" remote add gitea \
|
||||
ssh://git@overlord.kyun.li:222/vxaboveground/overlord.git
|
||||
git -C "$migration_dir/overlord.git" push --atomic gitea \
|
||||
'refs/heads/*:refs/heads/*' \
|
||||
'refs/tags/*:refs/tags/*'
|
||||
```
|
||||
|
||||
A non-fast-forward rejection means Gitea already contains divergent work.
|
||||
Stop and reconcile that work; do not add `--force` just to make the command
|
||||
pass.
|
||||
|
||||
5. Compare the source and destination refs exactly:
|
||||
|
||||
```bash
|
||||
git ls-remote --heads \
|
||||
ssh://git@altssh.gitlab.com:443/vxaboveground/overlord.git \
|
||||
| sort > "$migration_dir/gitlab-heads"
|
||||
git ls-remote --heads \
|
||||
ssh://git@overlord.kyun.li:222/vxaboveground/overlord.git \
|
||||
| sort > "$migration_dir/gitea-heads"
|
||||
git ls-remote --tags \
|
||||
ssh://git@altssh.gitlab.com:443/vxaboveground/overlord.git \
|
||||
| sort > "$migration_dir/gitlab-tags"
|
||||
git ls-remote --tags \
|
||||
ssh://git@overlord.kyun.li:222/vxaboveground/overlord.git \
|
||||
| sort > "$migration_dir/gitea-tags"
|
||||
diff -u "$migration_dir/gitlab-heads" "$migration_dir/gitea-heads"
|
||||
diff -u "$migration_dir/gitlab-tags" "$migration_dir/gitea-tags"
|
||||
```
|
||||
|
||||
Both `diff` commands should produce no output. In Gitea, set `main` as the
|
||||
default branch and recreate branch/tag protection, collaborators, deploy
|
||||
keys, webhooks, Actions secrets, and other host-level settings.
|
||||
|
||||
The explicit Git copy does not migrate GitLab issues, merge requests, comments,
|
||||
release records, CI variables, job artifacts, package/container registries, or
|
||||
other GitLab database content. Export/import those separately if they must be
|
||||
retained. If Git LFS is enabled later, its objects also require an explicit LFS
|
||||
fetch/push; ordinary ref pushes do not transfer LFS object content.
|
||||
|
||||
## Make Gitea the default in other clones
|
||||
|
||||
For an existing clone that still calls GitLab `origin`, preserve that remote
|
||||
under the `gitlab` name and add Gitea as the new `origin`:
|
||||
|
||||
```bash
|
||||
git remote rename origin gitlab
|
||||
git remote add origin \
|
||||
ssh://git@overlord.kyun.li:222/vxaboveground/overlord.git
|
||||
git fetch origin --prune --tags
|
||||
git branch --set-upstream-to=origin/main main
|
||||
git config remote.pushDefault origin
|
||||
```
|
||||
|
||||
If that clone already has a remote called `gitlab`, update URLs instead of
|
||||
renaming over it:
|
||||
|
||||
```bash
|
||||
git remote set-url origin \
|
||||
ssh://git@overlord.kyun.li:222/vxaboveground/overlord.git
|
||||
git remote set-url gitlab \
|
||||
ssh://git@altssh.gitlab.com:443/vxaboveground/overlord.git
|
||||
git fetch origin --prune --tags
|
||||
git branch --set-upstream-to=origin/main main
|
||||
git config remote.pushDefault origin
|
||||
```
|
||||
|
||||
Test the cutover with a normal branch push to `origin`. Avoid configuring a
|
||||
client-side push URL that writes to both hosts: the Gitea server-side mirror is
|
||||
the single replication mechanism and exposes failures in its UI.
|
||||
|
||||
## Configure the Gitea-to-GitLab push mirror
|
||||
|
||||
Gitea's push mirror force-updates the destination. Once enabled, changes made
|
||||
directly on GitLab may be overwritten or deleted on the next sync. Keep the
|
||||
GitLab project read-only for normal development and treat it as a replica.
|
||||
|
||||
1. In GitLab, create a project access token or personal access token with the
|
||||
`write_repository` scope. Use an account permitted to update the repository's
|
||||
protected branches and tags.
|
||||
2. In Gitea, open **Settings > Repository > Mirror Settings** for
|
||||
`vxaboveground/overlord` and choose **Add Push Mirror**.
|
||||
3. Enter these values:
|
||||
|
||||
- Remote repository URL: `https://gitlab.com/vxaboveground/overlord.git`
|
||||
- Authorization username: `oauth2`
|
||||
- Authorization password: the GitLab token
|
||||
|
||||
4. Enable **Sync when new commits are pushed**, add the mirror, and select
|
||||
**Synchronize Now** for the initial replication.
|
||||
5. Confirm that Gitea reports a successful sync, then compare heads and tags
|
||||
again with the verification commands above. Make a small test branch in
|
||||
Gitea, confirm it arrives in GitLab, and delete it from Gitea so the deletion
|
||||
behavior is also understood before ending the write freeze.
|
||||
|
||||
If a sync fails, inspect the error in Gitea's Mirror Settings. The usual causes
|
||||
are an expired token, missing `write_repository` permission, or GitLab protected
|
||||
branch/tag rules that reject the mirror account. Rotate the GitLab credential in
|
||||
Gitea rather than embedding it in a Git remote URL or this repository.
|
||||
|
||||
GitLab CI may run when mirrored commits arrive because this repository retains
|
||||
`.gitlab-ci.yml`. Keep that behavior if GitLab remains a CI replica; otherwise
|
||||
disable GitLab pipelines in the GitLab project settings after confirming Gitea
|
||||
Actions covers the required jobs.
|
||||
|
||||
## Final checks
|
||||
|
||||
- `origin` fetches and pushes to Gitea over SSH port 222.
|
||||
- `main` tracks `origin/main`, and `remote.pushDefault` is `origin`.
|
||||
- All GitLab heads and tags match Gitea at the end of the write freeze.
|
||||
- The Gitea push mirror reports a successful GitLab sync.
|
||||
- Branch/tag protections, access controls, secrets, and webhooks exist in Gitea.
|
||||
- The repository-scoped runner is online and a Gitea Actions workflow passes.
|
||||
- Developers know Gitea is authoritative and GitLab is read-only.
|
||||
|
||||
After an agreed observation period, remove the legacy `forgejo` remote from
|
||||
developer clones if it is no longer needed. Keep backups according to the
|
||||
project's retention policy.
|
||||
Reference in New Issue
Block a user