68 lines
4.4 KiB
Markdown
68 lines
4.4 KiB
Markdown
# Repository Update Workflow
|
|
|
|
Read this reference for every Gitea repository update.
|
|
|
|
## 1. Resolve Inputs
|
|
|
|
Identify the clean Gitea HTTPS URL, prepared source paths, repository target paths, target branch, commit intent, and the operating system where Git actually runs. If a Windows machine only displays or controls a remote Linux desktop, use the Linux flow. If a source-to-target mapping is ambiguous, stop and ask before writing.
|
|
|
|
## 2. Inspect Before Editing
|
|
|
|
Read applicable `AGENTS.md` and `CONTRIBUTING*`. Inspect the repository root, current branch, `git status`, staged diff, remotes, recent history, and remote refs. Do not print a remote URL that may contain credentials; reject URLs with embedded user information.
|
|
|
|
Verify GCM using the active platform reference. A successful version command means reuse the existing installation without installing or upgrading it. Configure GCM only when its helper is absent or conflicting.
|
|
|
|
Web login and Git HTTPS authentication are separate concerns. For example, an organization may use DingTalk or another OIDC provider to sign in to the Gitea web interface, while Git HTTPS still expects a Gitea username and PAT. Do not assume that a browser login authorizes the command line unless the instance explicitly documents that behavior.
|
|
|
|
The user signs in to the Gitea web interface, creates a PAT with `write:repository`, and enters the Gitea login plus PAT only in the local GCM prompt. The account must already have repository write access. Never ask the user to paste a PAT into chat.
|
|
|
|
## 3. Choose the Repository Path
|
|
|
|
- Existing clone: `git fetch --prune` first; do not merge automatically.
|
|
- Existing remote without a clone: clone the target branch before copying prepared files.
|
|
- Empty remote: only after `git ls-remote` succeeds with no refs, initialize the confirmed default branch, normally `main`, and add the clean HTTPS remote.
|
|
- Dirty clone: preserve unrelated changes. If they overlap task paths or prevent a safe update, use a fresh clone or isolated worktree based on the latest remote branch.
|
|
|
|
Do not use force, reset, clean, stash, or destructive checkout as a shortcut.
|
|
|
|
## 4. Prepare and Validate the Commit
|
|
|
|
Set the user-confirmed Eapil identity only in the target repository:
|
|
|
|
```bash
|
|
git config --local user.name "<confirmed-name>"
|
|
git config --local user.email "<confirmed-id>@eapil.com"
|
|
```
|
|
|
|
Copy or edit only the intended paths. Stage with an explicit pathspec:
|
|
|
|
```bash
|
|
git add -- <path-1> <path-2>
|
|
git diff --cached --name-status
|
|
git diff --cached --stat
|
|
git diff --cached --check
|
|
git diff --cached
|
|
```
|
|
|
|
Confirm every staged path is in scope, deletions are intentional, no secret or transient file is present, and repository-required tests pass. If there is no staged change, report that the remote already contains the prepared content instead of creating an empty commit, unless the user explicitly requested an empty commit.
|
|
|
|
## 5. Commit, Push, and Verify
|
|
|
|
Commit with an intent-based message. Re-fetch before pushing when the remote may have advanced. Push normally to the target branch. If the default branch is protected, push a task branch and report that review or merge is required. Do not use `--force`, `--force-with-lease`, `--no-verify`, or TLS bypasses.
|
|
|
|
When an interactive prompt is required but the agent cannot share it safely, give the user the exact working directory and `git push` command. The user enters the username and PAT in their own terminal. Do not replace this handoff with credentials in a command, URL, environment variable, or file. After the user reports that the push finished, continue with the remote verification below.
|
|
|
|
After a successful push, fetch the pushed branch and compare:
|
|
|
|
```bash
|
|
git rev-parse HEAD
|
|
git rev-parse "origin/<pushed-branch>"
|
|
git ls-remote origin "refs/heads/<pushed-branch>"
|
|
```
|
|
|
|
Report completion only when the local and remote SHAs match. Include the repository, branch, commit SHA and subject, exact changed paths, validation performed, and remaining user action.
|
|
|
|
## Stop Conditions
|
|
|
|
Stop on ambiguous paths, missing Git identity, authentication or TLS failure, insufficient account/PAT permissions, unexpected staged files, validation failure, overlapping user changes, non-fast-forward history requiring judgment, protected-branch rejection, server-hook rejection, or a request to overwrite remote history. A required local credential prompt is a user handoff, not permission to weaken authentication or store the PAT insecurely.
|