tendril/kb/02_systems/2025-11-11--gitea-workflows-guide--howto.md

---
title: "Gitea Workflows Guide"
date: "2025-11-11"
captured_at: "2025-11-11"
author: ["datawarrior"]
source: { kind: doc, ref: "docs/GITEA/Gitea-Workflows.md" }
source_type: personal_note
project: ["tendril"]
related_projects: ["tendril"]
topics: ["gitea", "workflows", "best-practices", "git", "collaboration"]
tags: ["gitea", "workflows", "best-practices", "git", "pull-requests", "issues", "branches"]
type: howto
status: active
phase_relevance: []
routing_hint: "Gitea workflows and best practices guide - infrastructure/tooling documentation"
proposed_path: "kb/02_systems/"
routing_confidence: 0.95
related: ["docs/GITEA/Gitea-Workflows.md"]
summary: "Common workflows and best practices for working with Gitea repositories. Covers repository setup, branch management, pull requests, issues, Gitea Actions, and integration with documentation systems."
key_takeaways: []
action_candidates: []
---

# Gitea Workflows Guide

## Common Workflows

### 1. Repository Setup

**Creating a new repository**:
1. Log in to Gitea instance
2. Click "New Repository" or "+" → "New Repository"
3. Configure repository settings (name, description, visibility, README, .gitignore, license)
4. Click "Create Repository"

**Cloning a repository**:
```bash
git clone https://git.parkingmeter.info/owner/repo.git
cd repo
```

### 2. Branch Management

**Creating a branch**:
```bash
git checkout -b feature/new-feature
git push -u origin feature/new-feature
```

**In Gitea UI**: Use branch dropdown to create new branch

### 3. Pull Requests

**Creating a Pull Request**:
1. Push branch to Gitea
2. Click "New Pull Request" button
3. Select base branch (usually `main` or `master`)
4. Fill in PR title and description
5. Add reviewers, labels, milestones if needed
6. Click "Create Pull Request"

**PR Workflow** (same as GitHub):
- Review code
- Add comments
- Request changes
- Approve
- Merge (merge, squash, or rebase)

### 4. Issues

**Creating an Issue**:
1. Go to repository
2. Click "Issues" tab
3. Click "New Issue"
4. Fill in title and description
5. Add labels, assignees, milestones
6. Click "Submit new issue"

**Issue Features**:
- Assign to team members
- Link to milestones
- Add labels
- Set due dates
- Track dependencies
- Reference commits and PRs

### 5. Gitea Actions (CI/CD)

**Setting up workflows**:
1. Create `.github/workflows/` directory
2. Create workflow YAML file
3. Push to repository
4. Gitea Actions will execute workflows

**Workflow triggers**:
- `push` - On push to repository
- `pull_request` - On PR events
- `workflow_dispatch` - Manual trigger
- `schedule` - Scheduled runs

## Best Practices

### 1. Branch Naming

**Conventions**:
- `feature/description` - New features
- `fix/description` - Bug fixes
- `docs/description` - Documentation
- `refactor/description` - Code refactoring
- `test/description` - Test improvements

### 2. Commit Messages

**Format**: `type(scope): description`

**Types**:
- `feat` - New feature
- `fix` - Bug fix
- `docs` - Documentation
- `chore` - Maintenance
- `ci` - CI/CD changes

**Examples**:
```
feat(phase-01): Add Zapier integration
fix(phase-02): Resolve web link capture
docs(kb): add api-auth-decision and update index/changelog
```

### 3. Pull Request Process

1. Create feature branch
2. Make changes and commit
3. Push branch to Gitea
4. Create Pull Request
5. Request review
6. Address feedback
7. Merge when approved

### 4. Issue Management

- Use labels for categorization
- Link issues to milestones
- Reference issues in commits: `Fixes #123`
- Close issues via PR: `Closes #123`

## For LLMs: Workflow Documentation

### When Documenting Workflows

**Use Gitea terminology**:
```markdown
## Development Workflow

1. Create a feature branch: `git checkout -b feature/name`
2. Make changes and commit
3. Push to Gitea: `git push origin feature/name`
4. Create Pull Request in Gitea
5. Request review and address feedback
6. Merge when approved
```

**Reference Gitea Actions**:
```markdown
## CI/CD Workflow

This repository uses **Gitea Actions** for continuous integration.

**Note**: Gitea Actions is compatible with GitHub Actions, so workflows 
use the same YAML format and `.github/workflows/` directory structure.

Workflows run automatically on:
- Push to main branch
- Pull requests
- Manual trigger via `workflow_dispatch`
```

## Integration with Documentation System

### Phase Documentation
- Reference Gitea repository URLs
- Use Gitea terminology in tasks.md
- Link to Gitea issues in tasks
- Reference Gitea Actions workflows

### KB System
- Reference Gitea features when relevant
- Link to Gitea documentation
- Use Gitea terminology consistently

### Cursor Rules
- Use "Gitea Actions" (not "GitHub Actions")
- Reference Gitea repository
- Note compatibility where relevant

## Troubleshooting

### Common Issues

**Workflow not running**:
- Check runner registration
- Verify workflow syntax
- Check trigger conditions
- Review runner logs

**PR not showing**:
- Verify branch was pushed
- Check branch visibility
- Verify base branch is correct

**Issues not linking**:
- Use correct issue number format: `#123`
- Verify issue exists
- Check repository permissions

## References

- **Gitea Usage**: https://docs.gitea.com/usage/
- **Gitea Actions**: https://docs.gitea.com/usage/actions/
- **Pull Requests**: https://docs.gitea.com/usage/pull-request/
- **Issues**: https://docs.gitea.com/usage/issues/

---

**Original Location**: `docs/GITEA/Gitea-Workflows.md`  
**Last Updated**: 2025-01-27  
**Related**: 
- `docs/GITEA/Gitea-Basics.md`
- `docs/GITEA/Gitea-Actions-Guide.md`