skill-git-push/skills/updating-gitea-repositories/SKILL.md

name, description

name	description
updating-gitea-repositories	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.
2. On macOS, also read macOS GCM setup.
3. On native Windows or WSL, also read Windows GCM setup.
4. On native Linux, including Linux controlled through a Windows remote desktop, also read Linux GCM setup.

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:

  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.