tendril/docs/GITEA/Gitea-Actions-Guide.md

# Gitea Actions Guide for LLMs

**Purpose**: Guide for LLMs working with Gitea Actions (CI/CD system compatible with GitHub Actions).

**Reference**: [Gitea Actions Documentation](https://docs.gitea.com/usage/actions/)

---

## Overview

**Gitea Actions** is Gitea's CI/CD system that is **compatible with GitHub Actions**. This means:

- Same YAML workflow format
- Same `.github/workflows/` directory structure
- Same triggers and syntax
- Existing GitHub Actions workflows work with minimal or no modifications
- Actions plugins can be downloaded from any Git website

---

## Key Compatibility Points

### 1. Directory Structure

**Same as GitHub**:
```
.github/
└── workflows/
    ├── workflow1.yml
    ├── workflow2.yml
    └── ...
```

### 2. YAML Format

**Identical to GitHub Actions**:
```yaml
name: Workflow Name

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run command
        run: echo "Hello, Gitea Actions!"
```

### 3. Triggers

**Same triggers as GitHub Actions**:
- `push` - On push to repository
- `pull_request` - On pull request events
- `workflow_dispatch` - Manual trigger
- `schedule` - Scheduled runs (cron syntax)
- `repository_dispatch` - External events

### 4. Runners

Gitea Actions uses **Gitea Runners** (similar to GitHub Runners):
- Self-hosted runners
- Can run on various platforms
- Register runners with Gitea instance
- Similar to GitHub Actions runners

---

## Differences from GitHub Actions

### 1. Actions Marketplace

- **GitHub**: Centralized marketplace at github.com/marketplace
- **Gitea**: Actions can be downloaded from any Git website
- **Impact**: Actions plugins can come from GitHub, Gitea, or any Git repository

### 2. Runner Registration

- **GitHub**: Runners managed by GitHub (or self-hosted)
- **Gitea**: All runners are self-hosted
- **Impact**: Must register and manage your own runners

### 3. Some GitHub-Specific Features

- Some GitHub Actions features may not be available
- Check Gitea Actions documentation for specific limitations
- Most common workflows work identically

---

## Creating Workflows

### Basic Workflow Template

```yaml
name: Workflow Name

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

jobs:
  job-name:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Run command
        run: |
          echo "Running in Gitea Actions"
          # Your commands here
```

### Using Actions from Different Sources

**From GitHub**:
```yaml
- uses: actions/checkout@v4
```

**From Gitea**:
```yaml
- uses: gitea.com/owner/action@v1
```

**From Any Git Repository**:
```yaml
- uses: https://git.example.com/owner/action@v1
```

---

## For LLMs: Documentation Guidelines

### When Creating Workflow Documentation

1. **Reference as "Gitea Actions"**:
   - "This workflow runs in Gitea Actions"
   - "Gitea Actions will execute this workflow on push"

2. **Note Compatibility**:
   - "Gitea Actions is compatible with GitHub Actions"
   - "This workflow uses the same YAML format as GitHub Actions"

3. **Use Correct Terminology**:
   - "Gitea Actions workflows" (not "GitHub Actions workflows")
   - "Gitea Runners" (not "GitHub Runners")
   - But note: "Same format as GitHub Actions"

### When Creating Workflow Files

1. **Use `.github/workflows/` directory** (same as GitHub)
2. **YAML format is identical** to GitHub Actions
3. **Reference in documentation** as "Gitea Actions workflows"
4. **Note compatibility** when relevant

### Example Documentation

```markdown
## CI/CD Workflows

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

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

### Workflows

- **`kb-lint.yml`** - Validates KB file naming and frontmatter
- **`kb-index-update.yml`** - Auto-updates KB index on push

All workflows are located in `.github/workflows/` and use standard GitHub Actions YAML format.
```

---

## Common Workflow Patterns

### Linting Workflow

```yaml
name: Lint

on:
  push:
    paths:
      - 'src/**/*.rs'
  pull_request:
    paths:
      - 'src/**/*.rs'

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run linter
        run: cargo clippy
```

### Testing Workflow

```yaml
name: Test

on: [push, pull_request]

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

### Index Update Workflow

```yaml
name: Update Index

on:
  push:
    branches: [ main ]
    paths:
      - 'kb/**/*.md'

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Generate index
        run: ./kb/scripts/generate-index.sh
      - name: Commit changes
        run: |
          git config user.name "Gitea Actions"
          git config user.email "actions@gitea.io"
          git add kb/_index.md
          git commit -m "chore: update KB index" || exit 0
          git push
```

---

## Troubleshooting

### Workflow Not Running

1. **Check runner registration**: Ensure runners are registered with Gitea instance
2. **Check workflow syntax**: Validate YAML syntax
3. **Check triggers**: Verify `on:` conditions match events
4. **Check permissions**: Ensure workflow has necessary permissions

### Actions Not Found

1. **Check action source**: Verify action URL is correct
2. **Check network access**: Ensure runner can access action repository
3. **Use full URL**: For custom actions, use full Git URL

### Runner Issues

1. **Check runner status**: Verify runner is online and connected
2. **Check runner labels**: Ensure `runs-on` matches runner labels
3. **Check runner logs**: Review runner logs for errors

---

## References

- **Gitea Actions Docs**: https://docs.gitea.com/usage/actions/
- **Gitea Runner**: https://docs.gitea.com/usage/actions/runner/
- **Workflow Syntax**: https://docs.gitea.com/usage/actions/usage/

---

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