PlayHours/scripts/setup-gitea-actions.md

# Setting up Gitea Actions for PlayHours

This guide will help you configure Gitea Actions for automated releases on your self-hosted Gitea instance.

## Prerequisites

- Self-hosted Gitea instance with Actions enabled
- Repository with proper permissions
- Git repository with the PlayHours project

## Step 1: Enable Actions in Gitea

1. **Check Gitea version**: Ensure you're running Gitea 1.19+ (Actions support)
2. **Enable Actions globally** (if you're the admin):
   - Go to Site Administration → Actions
   - Enable "Enable Actions"
3. **Enable Actions for your repository**:
   - Go to your repository settings
   - Under "Features", enable "Actions"

## Step 2: Configure Repository Secrets

1. **Go to repository settings** → **Secrets**
2. **Add the following secrets** (if needed):

### Required Secrets
- `GITEA_TOKEN`: Your Gitea API token (for Gitea API access)
- `GITEA_API_URL`: Your Gitea instance URL (optional, defaults to current instance)

### Creating API Tokens

#### For Gitea Token:
1. Go to your Gitea profile → Settings → Applications
2. Generate new token with `repo` scope
3. Copy the token and add it as `GITEA_TOKEN` secret

#### For Custom Gitea Instance (optional):
1. Go to repository settings → Secrets
2. Add `GITEA_API_URL` with your instance URL (e.g., `https://your-gitea.com`)

## Step 3: Verify Workflow Files

Ensure these files exist in your repository:
- `.gitea/workflows/ci.yml`
- `.gitea/workflows/release.yml`

## Step 4: Test the Setup

### Test CI Workflow
1. **Make a small change** to your code
2. **Commit and push** to main branch
3. **Check Actions tab** - you should see a CI workflow running

### Test Release Workflow
1. **Create a test tag**:
   ```bash
   git tag -a v1.0.0-test -m "Test release"
   git push origin v1.0.0-test
   ```
2. **Check Actions tab** - you should see a release workflow running
3. **Check Releases** - a new release should be created

## Step 5: Configure Runner (if needed)

If you don't have runners available, you may need to set up self-hosted runners:

### Using Docker Runner
1. **Install act** (local Actions runner):
   ```bash
   # On Linux/macOS
   curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
   
   # On Windows (with Chocolatey)
   choco install act-cli
   ```

2. **Test locally**:
   ```bash
   act -l  # List available workflows
   act push  # Run push workflow
   ```

### Using Self-Hosted Runner
1. **Download runner** from your Gitea instance
2. **Configure and register** the runner
3. **Start the runner service**

## Troubleshooting

### Common Issues

1. **Actions not showing up**:
   - Check if Actions are enabled in repository settings
   - Verify Gitea version supports Actions

2. **Workflow fails to run**:
   - Check runner availability
   - Verify workflow syntax
   - Check secrets configuration

3. **Build fails**:
   - Verify Java 17 is available
   - Check Gradle wrapper permissions
   - Review build logs for specific errors

4. **Release creation fails**:
   - Verify API tokens have correct permissions
   - Check if release already exists
   - Review Gitea API rate limits

### Debug Steps

1. **Check Actions logs**:
   - Go to Actions tab in your repository
   - Click on failed workflow
   - Review step-by-step logs

2. **Test locally**:
   ```bash
   # Test build
   ./gradlew clean build
   
   # Test with act
   act push -v
   ```

3. **Verify secrets**:
   - Check secret names match exactly
   - Verify token permissions
   - Test API access manually

## Advanced Configuration

### Custom Runner Labels
If using self-hosted runners, you can specify runner labels in workflows:

```yaml
jobs:
  build:
    runs-on: [self-hosted, linux, java17]
```

### Environment Variables
Add environment-specific variables:

```yaml
env:
  JAVA_VERSION: '17'
  GRADLE_OPTS: '-Xmx2g'
```

### Custom Gitea Instance Configuration
If your Gitea instance is not at the default URL:

```yaml
env:
  GITEA_API_URL: ${{ secrets.GITEA_API_URL }}
  GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
```

## Security Considerations

1. **Token Permissions**: Use minimal required permissions for API tokens
2. **Secret Management**: Never commit secrets to repository
3. **Runner Security**: Secure self-hosted runners properly
4. **Access Control**: Limit who can trigger releases

## Monitoring and Maintenance

1. **Regular Updates**: Keep Gitea and Actions up to date
2. **Log Monitoring**: Check Actions logs for issues
3. **Token Rotation**: Regularly rotate API tokens
4. **Runner Health**: Monitor runner performance and availability