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](https://docs.gitea.com/usage/)

---

## 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**:
```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**:
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**:
```yaml
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**:
```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`
```

### 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**:
```yaml
# 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