picpeak/docs/GITEA_ACTIONS_SETUP.md

# Gitea Actions Setup Guide

## Prerequisites

1. **Gitea Version**: Ensure you're running Gitea 1.19.0 or later
2. **Gitea Actions Enabled**: Check your Gitea configuration

## Step 1: Enable Gitea Actions in app.ini

Add or modify these settings in your Gitea `app.ini`:

```ini
[actions]
ENABLED = true
DEFAULT_ACTIONS_URL = https://gitea.com
```

## Step 2: Install Gitea Act Runner

### Option A: Using Docker

```bash
docker run -d \
  --name gitea-runner \
  --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v gitea-runner-data:/data \
  -e GITEA_INSTANCE_URL=https://gitea.nothaft.cloud \
  -e GITEA_RUNNER_REGISTRATION_TOKEN=<your-registration-token> \
  -e GITEA_RUNNER_NAME=docker-runner \
  gitea/act_runner:latest
```

### Option B: Using Binary

1. Download the act_runner:
```bash
wget https://gitea.com/gitea/act_runner/releases/download/v0.2.5/act_runner-0.2.5-linux-amd64
chmod +x act_runner-0.2.5-linux-amd64
sudo mv act_runner-0.2.5-linux-amd64 /usr/local/bin/act_runner
```

2. Register the runner:
```bash
act_runner register \
  --instance https://gitea.nothaft.cloud \
  --token <your-registration-token> \
  --name "my-runner" \
  --labels "ubuntu-latest:docker://node:16-bullseye,ubuntu-22.04:docker://node:16-bullseye"
```

3. Start the runner:
```bash
act_runner daemon
```

## Step 3: Get Registration Token

1. Go to your Gitea instance admin panel
2. Navigate to Site Administration → Actions → Runners
3. Click "Create new Runner"
4. Copy the registration token

## Step 4: Repository Settings

1. Go to your repository settings in Gitea
2. Navigate to Settings → Actions → General
3. Ensure Actions are enabled for the repository

## Step 5: Convert GitHub Actions to Gitea Actions

While Gitea Actions is mostly compatible with GitHub Actions, there are some differences:

### Workflow Location
- GitHub Actions: `.github/workflows/`
- Gitea Actions: `.gitea/workflows/` (preferred) or `.github/workflows/`

### Supported Features
✅ Supported:
- Basic workflow syntax
- Common actions like `actions/checkout`
- Environment variables
- Secrets
- Artifacts
- Matrix builds

❌ Not Supported:
- Some GitHub-specific actions
- GitHub Packages
- Some advanced features

## Step 6: Debug Workflow Issues

If workflows are stuck in "waiting":

1. **Check Runner Status**:
   ```bash
   # If using Docker
   docker logs gitea-runner
   
   # If using binary
   journalctl -u act_runner -f
   ```

2. **Check Gitea Logs**:
   ```bash
   # Check Gitea logs for action-related errors
   tail -f /path/to/gitea/log/gitea.log | grep -i action
   ```

3. **Verify Runner Labels**:
   - Ensure your runner has the labels that match your workflow's `runs-on`
   - Common labels: `ubuntu-latest`, `ubuntu-22.04`, `ubuntu-20.04`

4. **Check Repository Permissions**:
   - Ensure the repository has Actions enabled
   - Check if there are any branch protection rules blocking Actions

## Step 7: Alternative - Use Drone CI

Since you already have Drone CI configured (`.drone.yml`), you might want to use that instead:

```yaml
# Your existing .drone.yml is already set up for CI/CD
kind: pipeline
type: docker
name: default
# ... rest of your Drone configuration
```

## Common Issues and Solutions

### Issue: Workflows stuck in "waiting"
**Solution**: No runners available. Register and start a runner.

### Issue: Runner can't connect
**Solution**: Check firewall rules and ensure runner can reach Gitea instance.

### Issue: Docker-in-Docker errors
**Solution**: Mount Docker socket or use privileged mode for runner.

### Issue: Actions not showing in UI
**Solution**: Enable Actions in both Gitea config and repository settings.

## Next Steps

1. Check your Gitea version and configuration
2. Install and register a runner
3. Enable Actions for your repository
4. Test with the simple workflow created in `.gitea/workflows/test.yml`
5. Once working, migrate your GitHub Actions workflows if needed