# Gitea Repository Operations

_Last verified: 2026-08-02 18:06 UTC_

## Status

✅ Hermes has a reusable local skill for general Gitea repository work:

- Skill: `gitea-repository-operations`
- Path: `/opt/data/skills/software-development/gitea-repository-operations/SKILL.md`
- Scope: any organization or repository on `gitea.lego-cloud.eu`, not only Docusaurus projects

The existing `gitea-docusaurus-projects` skill remains the specialist extension for Docusaurus, pnpm, sharp-corner UI conventions, and documentation CI/CD.

## Instance baseline

| Capability | Configuration | Status |
|---|---|---|
| Web UI | `https://gitea.lego-cloud.eu` | ✅ |
| REST API | `https://gitea.lego-cloud.eu/api/v1` | ✅ |
| API credential | Bitwarden Secrets Manager → `HL_V1_GITEA_ACCESS_TOKEN` | ✅; gateway restart required after key changes |
| SSH endpoint | `ssh://git@gitea.lego-cloud.eu:30009/ORG/REPO.git` | ✅ |
| SSH identity | `/opt/data/home/.ssh/id_ed25519` | ✅ |
| Git identity | `Jarvis Jr Hermes <jarvis.at.skic@gmail.com>` | ✅ |

Never use `GITHUB_TOKEN` for `gitea.lego-cloud.eu`. Obtain `HL_V1_GITEA_ACCESS_TOKEN` from Bitwarden Secrets Manager; do not copy it into `/opt/data/.env`. Never publish the API token, embed it in a Git remote, or commit it to a repository. Hermes exports Bitwarden keys exactly as named, and a gateway restart is required to import changed keys into the process environment.

## Standard workflow

1. Authenticate with `GET /api/v1/user` and confirm the account is active.
2. Discover organization/repository metadata before mutation.
3. Clone via SSH with the explicit identity and `BatchMode=yes`.
4. Fetch and inspect branch divergence before editing an existing clone.
5. Preserve remote work; no force-push or history rewrite without explicit direction.
6. Run repository-specific validation and `git diff --cached --check`.
7. Commit only intended files and push through SSH.
8. Verify local/remote branch SHAs.
9. Read back a distinctive file through the authenticated Gitea API.
10. Report repository URL, branch, commit SHA, validation, and caveats.

## Skill coverage

- Organization and repository discovery/creation
- Safe clone, fetch, branch, commit, and push workflow
- Pagination and authenticated API usage
- Collaborators with `read`, `write`, or `admin` permission
- Issues, pull requests, releases, and tags
- Gitea Actions under `.gitea/workflows/`
- Automated no-op Git synchronization
- Private-repository raw-file verification
- Troubleshooting disabled accounts, SSH keys, API authorization, divergence, and CI runners

## Known operational lessons

- API and SSH access must be tested independently.
- A successful push is not complete verification; read back the requested artifact.
- Repository-level `admin` is not the same as organization ownership.
- Private raw web links may return `404`; use the authenticated API endpoint.
- Gitea account disablement can break both previously valid tokens and SSH keys without requiring key/token replacement after re-enablement.
- Scheduled syncs must not silently accumulate unpushed commits.

## Current Gitea repositories referenced by the wiki

- `skic-v1-playground/knowledge-wiki` — automated wiki mirror
- `world-v1/network-v1` — global network address book and investigation repository

Add future repository-specific details to their project documentation; keep this page focused on reusable operations.