e6bced5dc2
- Rebase dev/1.0.0 on latest upstream main (drop Muse relay code) - Preserve: troubleshooting records, remote layout, Docker deploy workflow - Simplify docker-compose.yml to app-only (external PG/Redis) - Add ops/remote/ host documentation - Update .env.example with host/docker connection profiles
364 lines
7.5 KiB
Markdown
364 lines
7.5 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
git switch home
|
|
git rebase main
|
|
git push --force-with-lease gitea home
|
|
```
|
|
|
|
If using merge:
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```bash
|
|
git switch main
|
|
git switch -c feature/<name>
|
|
```
|
|
|
|
Push it:
|
|
|
|
```bash
|
|
git push -u gitea feature/<name>
|
|
```
|
|
|
|
### 5.5 Push local changes
|
|
Always push to writable Gitea repo:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
git config remote.pushDefault gitea
|
|
```
|
|
|
|
Set `main` tracking to upstream:
|
|
|
|
```bash
|
|
git branch --set-upstream-to=upstream/main main
|
|
```
|
|
|
|
Set dev branch tracking to Gitea:
|
|
|
|
```bash
|
|
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.
|