feat: publish safe Gitea repository update skill

2026-09-02 12:08:58 +08:00
commit 72c856975e
6 changed files with 257 additions and 0 deletions
@@ -0,0 +1,55 @@
+---
+name: updating-gitea-repositories
+description: Use when publishing or updating prepared files in a Gitea repository over HTTPS on macOS or Windows, especially when Git Credential Manager, Personal Access Token authentication, empty repositories, existing clones, or push verification are involved.
+---
+
+# 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).
+
+## 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.
+- 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 |
+| 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.
+- Staging the whole worktree for a narrow update.
+- Treating push rejection as permission to force-push.
+- Reporting the local commit without remote SHA verification.