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:

   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):

   # 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:

   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:

   # 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:

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

Environment Variables

Add environment-specific variables:

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

Custom Gitea Instance Configuration

If your Gitea instance is not at the default URL:

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