new-api/ops/remote/GIT_GITEA.AGENT.md

Git and Gitea Management AGENT

Purpose

This document defines the canonical workflow for managing:

• local Git repositories
• GitHub upstream repositories
• writable Gitea repositories
• read-only Gitea mirror repositories

This file exists to prevent remote confusion, mirror misuse, and branch history corruption.

1. Core Principles

1.1 One repo, one role

Do not let a single remote repository play multiple conflicting roles.

A repository should be clearly one of:

• upstream source
• writable development remote
• read-only mirror

If a repository is a mirror, treat it as a mirror. If a repository is writable, treat it as writable. Do not mix the two.

1.2 Never confuse source of truth

The source of truth for official upstream code is the upstream repository, not the writable Gitea dev repo, and not the mirror.

1.3 Keep main clean

main is for syncing upstream only. Do not pile local feature work directly into main.

1.4 Local changes belong on dev branches

Local work belongs on branches like:

• home
• feature/*
• fix/*

Do not treat the mirror repo as a development target.

2. Remote Roles

2.1 Canonical remote names

Use these exact names:

• upstream — official upstream source repository
• gitea — writable development repository on Gitea

Do not rename them casually.

2.2 Role definitions

upstream

Used only for:

• fetching latest official code
• comparing branch divergence
• updating local main

Example:

• upstream -> https://github.com/QuantumNous/new-api.git

gitea

Used only for:

• pushing local branches
• opening PRs on writable Gitea repos
• storing development work

Example:

• gitea -> ssh://git@100.64.0.8:2222/admin/new-api-dev.git

Read-only mirror repo

If a Gitea repo is configured as a pull mirror, it is read-only for development purposes.

Example:

• admin/new-api is a pull mirror of GitHub
• it is for sync / reference / backup
• it is not the target for normal pushes

Do not point gitea to a mirror repo.

3. Required Repository Topology

For projects that track an open-source upstream and also need private or self-hosted development:

• one upstream repo
• one writable Gitea dev repo
• optional one Gitea mirror repo

Recommended shape:

• upstream -> official GitHub repo
• gitea -> writable Gitea repo
• optional mirror repo exists separately but is not the main local push target

4. Branch Responsibilities

main

Responsibilities:

• track upstream
• remain linear and clean
• only accept upstream sync commits or fast-forward updates

Rules:

• do not do feature development directly on main
• do not use main as a scratch branch
• prefer merge --ff-only when updating from upstream

home

Responsibilities:

• personal development branch
• local operational or infrastructure work
• custom changes that do not belong on clean upstream main

Rules:

• rebase or merge onto updated main
• push to writable Gitea repo
• do not track upstream directly

feature/*

Responsibilities:

• isolated work branches
• short-lived development branches
• branch off from current main or from home when appropriate

5. Standard Workflow

5.1 Inspect repository state

Always inspect first:

git remote -v
git branch -vv
git status --short

If remotes or tracking look wrong, fix them before pushing.

5.2 Sync local main with upstream

Preferred flow:

git fetch upstream
git switch main
git merge --ff-only upstream/main
git push gitea main

This keeps:

• local main
• writable Gitea main

aligned with upstream.

5.3 Update development branch after upstream sync

If using rebase:

git switch home
git rebase main
git push --force-with-lease gitea home

If using merge:

git switch home
git merge main
git push gitea home

Use rebase when clean linear history matters. Use merge when you do not want history rewriting.

5.4 Create a new working branch

From updated main:

git switch main
git switch -c feature/<name>

Push it:

git push -u gitea feature/<name>

5.5 Push local changes

Always push to writable Gitea repo:

git push gitea <branch>

Do not push to mirror repos.

6. Fallback Workflow When GitHub Is Unreachable

If local machine cannot access GitHub, but the Gitea mirror is confirmed fresh, the mirror may be used as a temporary fetch source.

Example:

git fetch ssh://git@100.64.0.8:2222/admin/new-api.git refs/heads/main:refs/remotes/upstream/main
git switch main
git merge --ff-only upstream/main
git push gitea main

Important restriction

Do this only after verifying that the mirror really matches upstream.

Check both sides:

• GitHub main commit
• Gitea mirror main commit

If they differ, do not use the mirror as a substitute for upstream.

7. Gitea Mirror Rules

If a Gitea repository is a pull mirror:

• it is a sync target, not a dev target
• pushes may fail or be meaningless
• it should be treated as read-only for development

Use mirror repos for:

• backup
• browsing
• clone acceleration
• temporary upstream fallback when verified fresh

Do not use mirror repos for:

• long-term feature branch work
• main development push target
• authoritative branch ownership

8. SSH Rules for Gitea

Use Gitea built-in SSH, not random container SSH assumptions.

Example working clone form:

git clone ssh://git@100.64.0.8:2222/admin/new-api-dev.git

If SSH suddenly breaks after a server-side SSH mapping change:

• verify host port mapping
• verify Gitea built-in SSH port
• refresh local known_hosts if host key changed

Example:

ssh-keygen -R '[100.64.0.8]:2222'
ssh -T -p 2222 git@100.64.0.8

9. Required Remote Configuration for This Project

Current expected shape:

• upstream -> official GitHub repository
• gitea -> writable Gitea development repository

Expected result style:

gitea    ssh://git@100.64.0.8:2222/admin/new-api-dev.git (fetch)
gitea    ssh://git@100.64.0.8:2222/admin/new-api-dev.git (push)
upstream https://github.com/QuantumNous/new-api.git (fetch)
upstream https://github.com/QuantumNous/new-api.git (push)

Expected tracking style:

• main -> upstream/main
• home -> gitea/home

10. Forbidden Operations

Do not do the following unless you explicitly know why:

• push local feature work into a pull mirror repo
• remove upstream and pretend Gitea mirror is always equal to GitHub
• develop directly on main
• rewrite shared branch history without understanding the impact
• force-push main
• use mirror repos as the only source of upstream truth
• change remote roles casually

11. Minimal Recovery Rules

If repository roles become confused:

1. inspect remotes
2. identify which repo is writable and which is mirrored
3. restore:
   • upstream -> official source
   • gitea -> writable dev repo
4. restore tracking:
   • main -> upstream/main
   • dev branch -> gitea/<branch>

Useful commands:

git remote -v
git branch -vv
git config --get branch.main.remote
git config --get branch.main.merge
git config --get remote.pushDefault

12. Recommended Defaults

Set default push target to writable Gitea:

git config remote.pushDefault gitea

Set main tracking to upstream:

git branch --set-upstream-to=upstream/main main

Set dev branch tracking to Gitea:

git branch --set-upstream-to=gitea/home home

13. Human Rule

If you cannot explain, in one sentence, which remote is:

• official upstream
• writable dev remote
• mirror

then stop and fix the repository configuration before doing more Git work.