70 lines
3.9 KiB
Markdown
70 lines
3.9 KiB
Markdown
# Gitea Repository Operations
|
|
|
|
_Last verified: 2026-08-14 13:20 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 former `gitea-docusaurus-projects` specialist skill was merged into `documentation-docusaurus` on 2026-08-14 and retired from the active runtime. For Docusaurus structure, pnpm, Gitea Actions, LEGO Cloud Pages, and documentation acceptance verification, use the Gitea-managed `documentation-docusaurus` skill from `vssa-v1-skills-code-agent/documentation-docusaurus`; use `gitea-repository-operations` for general repository operations.
|
|
|
|
## 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
|
|
- `vssa-v1-skills-code-agent/vssa-clients` — authoritative VSSA client/system/contractor investigation skill
|
|
- `vssa-v1-skills-code-agent/documentation-docusaurus` — authoritative merged VSSA documentation and Gitea Pages skill
|
|
|
|
Add future repository-specific details to their project documentation; keep this page focused on reusable operations.
|