3.3 KiB
Repository Update Workflow
Read this reference and credential persistence for every Gitea update.
1. Resolve and inspect
Identify the clean HTTPS site and repository, account, prepared source paths, destination paths, target branch, commit intent, and the host running Git. Reuse details already established by the task. Ask only when a required mapping or identity remains ambiguous.
Read applicable AGENTS.md and CONTRIBUTING*. Inspect repository status, staged changes, branch, history, and remote configuration without exposing credentials embedded in URLs or helper commands. Preserve unrelated changes. Determine the effective helper chain, username, useHttpPath, namespace, and secure store, including site- and repository-specific overrides. Reuse a working installation and valid credential; do not require a new PAT for every repository.
Before diagnosing a questionable PAT, use the read-only probe in the credential reference. Do not let a failing Git authentication erase the original credential. Diagnose account, configuration, network, TLS, server authentication, and repository permissions before requesting local reauthorization. A 401 does not identify an expired or revoked token.
2. Select the repository state
- Existing clone: fetch the relevant branch after the safe credential preflight; do not merge automatically.
- Existing remote without a clone: clone the target branch before copying prepared files.
- Empty remote: initialize the confirmed default branch only after an authenticated remote check confirms no refs.
- Dirty clone: preserve unrelated changes. If task paths overlap or safe updates are blocked, use a suitable isolated worktree or clone.
Do not use force, reset, clean, stash, or destructive checkout as a shortcut.
3. Prepare and validate
Reuse an identity already explicitly authorized for this repository. If an identity must be set, configure the confirmed name and email only in the target repository. Ask only when the intended identity is missing or ambiguous.
Copy or edit only the intended paths. Stage with explicit pathspecs and inspect staged names, statistics, whitespace checks, and the actual diff. Confirm that deletions are intentional, no secret or transient file is present, and required tests pass. Do not create an empty commit unless the user requested it.
4. Commit, push, verify
Commit with an intent-based message. Recheck the remote when it may have advanced. Push normally to the intended branch. If the default branch is protected, follow the user's review workflow; do not use force, hook bypasses, or TLS bypasses.
If local authentication is required, use a supported browser OAuth flow or have the user enter the username and an existing suitable PAT in a trusted local prompt; a new PAT is needed only if no valid authorized credential is available. Preserve rejected old records through a separate namespace. Never ask for a secret in chat or put it in a command, URL, environment variable, or repository file.
After the push, fetch the pushed branch and compare its remote SHA with local HEAD. Report the repository, branch, commit, scope, validation, and any remaining action. A read-only credential probe does not prove write permission. A source-repository push does not by itself prove that a separate plugin marketplace or installed cache has synchronized.