tendril/kb/02_systems/2025-11-11--gitea-llm-guidelines--howto.md

---
title: "LLM Guidelines for Working with Gitea"
date: "2025-11-11"
captured_at: "2025-11-11"
author: ["datawarrior"]
source: { kind: doc, ref: "docs/GITEA/LLM-Gitea-Guidelines.md" }
source_type: personal_note
project: ["tendril"]
related_projects: ["tendril"]
topics: ["gitea", "llm", "guidelines", "documentation", "terminology"]
tags: ["gitea", "llm", "guidelines", "documentation", "terminology", "best-practices"]
type: howto
status: active
phase_relevance: []
routing_hint: "LLM guidelines for Gitea - infrastructure/tooling documentation"
proposed_path: "kb/02_systems/"
routing_confidence: 0.95
related: ["docs/GITEA/LLM-Gitea-Guidelines.md", ".cursorrules"]
summary: "Specific guidelines for AI assistants (LLMs) when working with Gitea-based projects. Covers terminology, documentation standards, workflow file creation, and common scenarios."
key_takeaways: []
action_candidates: []
---

# LLM Guidelines for Working with Gitea

## Core Principles

1. **Always refer to "Gitea"** (not "GitHub") when the platform is Gitea
2. **Note compatibility** when discussing Gitea Actions (compatible with GitHub Actions)
3. **Use Gitea terminology** consistently
4. **Link to Gitea documentation** when referencing features

## Terminology Guidelines

### Correct Usage

✅ **Use These Terms**:
- "Gitea" - The platform
- "Gitea Actions" - CI/CD system
- "Gitea Runners" - CI/CD execution environment
- "Gitea instance" - Self-hosted Gitea server
- "Pull Request" or "PR" - Code review (same as GitHub)
- "Issues" - Bug/feature tracking (same as GitHub)
- "Repository" or "Repo" - Code storage (same as GitHub)

❌ **Avoid These Terms** (when referring to Gitea):
- "GitHub" - Wrong platform
- "GitHub Actions" - Should be "Gitea Actions" (but note compatibility)
- "GitHub Runners" - Should be "Gitea Runners"
- "GitHub repository" - Should be "Gitea repository"

### Compatibility Notes

When discussing workflows or Actions:
- ✅ "Gitea Actions workflows (compatible with GitHub Actions format)"
- ✅ "Gitea Actions uses the same YAML format as GitHub Actions"
- ✅ "Workflows use `.github/workflows/` directory (same as GitHub)"

## Documentation Standards

### When Creating Documentation

1. **Platform Reference**:
   ```markdown
   This repository uses **Gitea** for version control and collaboration.
   ```

2. **Actions Reference**:
   ```markdown
   This project uses **Gitea Actions** for CI/CD. Gitea Actions is compatible 
   with GitHub Actions, so workflows use the same YAML format and 
   `.github/workflows/` directory structure.
   ```

3. **Repository Links**:
   ```markdown
   Repository: https://git.parkingmeter.info/Mycelium/tendril
   ```

### When Creating Workflow Files

1. **File Location**: `.github/workflows/` (same as GitHub)
2. **YAML Format**: Identical to GitHub Actions
3. **Documentation**: Reference as "Gitea Actions workflows"
4. **Comments**: Note compatibility if relevant

**Example**:
```yaml
# Gitea Actions workflow
# Compatible with GitHub Actions format
name: KB Lint

on:
  push:
    paths:
      - 'kb/**/*.md'
```

### When Updating Cursor Rules

1. **Use "Gitea Actions"** in rules
2. **Note compatibility** where relevant

## Common Scenarios

### Scenario 1: Creating a New Workflow

**What to do**:
1. Create workflow in `.github/workflows/`
2. Use standard GitHub Actions YAML format
3. Document as "Gitea Actions workflow"
4. Note compatibility in documentation
5. Update `.github/CHANGELOG.md`
6. Update `.github/README.md`

### Scenario 2: Referencing Repository

**What to do**:
1. Use Gitea repository URL
2. Reference as "Gitea repository"
3. Link to Gitea instance

### Scenario 3: Discussing Features

**What to do**:
1. Reference Gitea features
2. Note similarities to GitHub when helpful
3. Link to Gitea documentation

## Checklist for LLMs

When working with Gitea-based projects:

- [ ] Use "Gitea" (not "GitHub") when referring to the platform
- [ ] Use "Gitea Actions" (not "GitHub Actions") but note compatibility
- [ ] Reference Gitea repository URLs correctly
- [ ] Link to Gitea documentation: `https://docs.gitea.com/`
- [ ] Note compatibility when discussing workflows
- [ ] Use `.github/workflows/` directory (same as GitHub)
- [ ] Use standard GitHub Actions YAML format for workflows
- [ ] Update `.github/CHANGELOG.md` when modifying workflows
- [ ] Update `.github/README.md` when adding workflows
- [ ] Use Gitea terminology consistently

## Quick Reference

### Repository Information

- **Platform**: Gitea (self-hosted)
- **Instance**: git.parkingmeter.info
- **Repository**: https://git.parkingmeter.info/Mycelium/tendril

### Documentation Links

- **Gitea Docs**: https://docs.gitea.com/
- **Gitea Actions**: https://docs.gitea.com/usage/actions/
- **Gitea API**: https://docs.gitea.com/api/

### Key Points

1. Gitea is self-hosted (not GitHub)
2. Gitea Actions is compatible with GitHub Actions
3. Workflows use same format and directory structure
4. Terminology should reference "Gitea" consistently

---

**Original Location**: `docs/GITEA/LLM-Gitea-Guidelines.md`  
**Last Updated**: 2025-01-27  
**Related**: 
- `docs/AGENT-GUIDELINES.md`
- `.cursorrules`
- `docs/GITEA/Gitea-Basics.md`