---
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.