63 lines
3.8 KiB
Markdown
63 lines
3.8 KiB
Markdown
---
|
|
name: updating-gitea-repositories
|
|
description: Use when publishing or updating prepared files in a Gitea repository over HTTPS on macOS, Windows, WSL, or Linux, including remote Linux desktops, Git Credential Manager, Personal Access Token authentication, SSO/OIDC web login, empty repositories, existing clones, and push verification.
|
|
---
|
|
|
|
# Updating Gitea Repositories
|
|
|
|
## Purpose
|
|
|
|
Publish only the intended changes to a Gitea repository through HTTPS, Git Credential Manager (GCM), and a least-privilege Personal Access Token (PAT). Preserve existing work, keep secrets out of commands and logs, and verify the remote commit after every push.
|
|
|
|
## Required Reading
|
|
|
|
1. Always read [repository workflow](references/repository-workflow.md).
|
|
2. On macOS, also read [macOS GCM setup](references/macos.md).
|
|
3. On native Windows or WSL, also read [Windows GCM setup](references/windows.md).
|
|
4. On native Linux, including Linux controlled through a Windows remote desktop, also read [Linux GCM setup](references/linux.md).
|
|
|
|
## Core Contract
|
|
|
|
- Require a clean Gitea HTTPS URL, exact prepared source paths, intended repository paths, target branch, and commit intent. Infer only what the active task makes unambiguous.
|
|
- Verify GCM by executing its version command. When it succeeds, reuse that installation without install, reinstall, or upgrade actions. Install only when no working GCM exists; repair only when installation records exist but the executable does not.
|
|
- Select setup instructions from the operating system where the Git process runs. A Windows computer used only to control a remote Linux desktop does not make that Git session Windows or WSL.
|
|
- Treat web SSO/OIDC login and Git HTTPS authentication as separate unless the Gitea instance explicitly documents an integrated Git flow. The web login can be used to create a PAT; it does not by itself authorize a command-line push.
|
|
- The user creates a Gitea PAT with `write:repository`. The user enters the Gitea login and PAT only in a local GCM prompt. Never request or expose a PAT in chat, URLs, environment variables, command arguments, logs, or files.
|
|
- Preserve unrelated work. Stage only exact task paths; never use unscoped `git add .` or `git add -A`.
|
|
- Before committing, set the user-confirmed identity only in the target repository:
|
|
|
|
```bash
|
|
git config --local user.name "<confirmed-name>"
|
|
git config --local user.email "<confirmed-id>@eapil.com"
|
|
```
|
|
|
|
- Never bypass TLS, branch protection, hooks, validation, or non-fast-forward safety. Never force-push as recovery.
|
|
- Report success only after fetching the pushed branch and matching its remote SHA to local `HEAD`.
|
|
|
|
## Quick Decisions
|
|
|
|
| State | Action |
|
|
|---|---|
|
|
| GCM version works | Reuse it unchanged |
|
|
| Installer record exists but command fails | Repair or reinstall GCM |
|
|
| Git runs on a remotely controlled Linux host | Use the Linux instructions |
|
|
| Linux Secret Service has no graphical session | Use a repository-local GCM memory cache |
|
|
| HTTPS remote has no refs | Initialize the confirmed default branch |
|
|
| Remote has history | Clone or fetch before writing |
|
|
| Dirty changes overlap task paths | Stop or use a clean clone/worktree |
|
|
| Default branch rejects normal push | Push a task branch for review |
|
|
|
|
## Example Invocation
|
|
|
|
> Use `$updating-gitea-repositories` to publish the prepared skill to `https://gitea.example.com/team/skill-repo.git`, targeting `skills/updating-gitea-repositories` on `main`.
|
|
|
|
## Common Mistakes
|
|
|
|
- Trusting package-manager state instead of running the GCM version command.
|
|
- Treating a PAT as ordinary text.
|
|
- Assuming a successful browser SSO/OIDC login also authenticates Git HTTPS.
|
|
- Applying Windows or WSL setup to Git that actually runs on a remote Linux host.
|
|
- Staging the whole worktree for a narrow update.
|
|
- Treating push rejection as permission to force-push.
|
|
- Reporting the local commit without remote SHA verification.
|