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

title, date, captured_at, author, source, source_type, project, related_projects, topics, tags, type, status, phase_relevance, routing_hint, proposed_path, routing_confidence, related, summary, key_takeaways, action_candidates

title	date	captured_at	author	source	source_type	project	related_projects	topics	tags	type	status	phase_relevance	routing_hint	proposed_path	routing_confidence	related	summary	key_takeaways	action_candidates
Gitea Workflows Guide	2025-11-11	2025-11-11	datawarrior	kind ref doc docs/GITEA/Gitea-Workflows.md	personal_note	tendril	tendril	gitea workflows best-practices git collaboration	gitea workflows best-practices git pull-requests issues branches	howto	active		Gitea workflows and best practices guide - infrastructure/tooling documentation	kb/02_systems/	0.95	docs/GITEA/Gitea-Workflows.md	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.

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:

git clone https://git.parkingmeter.info/owner/repo.git
cd repo

2. Branch Management

Creating a branch:

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:

## 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:

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