tendril/docs/GITEA/Gitea-Workflows.md

Gitea Workflows for LLMs

Purpose: Common workflows and best practices for working with Gitea repositories.

Reference: Gitea Usage Documentation

---

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 (public/private)
   • Initialize with README (optional)
   • Add .gitignore (optional)
   • Choose license (optional)
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:

1. Go to repository
2. Click branch dropdown
3. Type new branch name
4. Click "Create Branch"

3. Pull Requests

Creating a Pull Request:

1. Push branch to Gitea
2. Click "New Pull Request" button (appears after push)
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

Example workflow:

name: CI

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: cargo test

---

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`

When Creating Workflow Files

Location and format:

• Use .github/workflows/ directory
• Use standard GitHub Actions YAML format
• Reference as "Gitea Actions workflows" in documentation

Example:

# Gitea Actions workflow
# Compatible with GitHub Actions format
name: Test

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: cargo test

---

Integration with Documentation System

Phase Documentation

When working with phase documentation:

• Reference Gitea repository URLs
• Use Gitea terminology in tasks.md
• Link to Gitea issues in tasks
• Reference Gitea Actions workflows

KB System

When creating KB entries:

• Reference Gitea features when relevant
• Link to Gitea documentation
• Use Gitea terminology consistently

Cursor Rules

When updating 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/

---

Location: docs/GITEA/Gitea-Workflows.md
Last Updated: 2025-01-27