# Gitea Actions Setup - Server Configuration Checklist

This document outlines the changes needed on your Gitea server to make the CI/CD pipeline work.

## What You Need to Do

### 1. Add GITEA_TOKEN Secret to Repository

1. **Log into Gitea** with your user account
2. **Navigate to** your nerd-monitor repository
3. **Go to Settings → Secrets**
4. **Create a new secret**:
   - Name: `GITEA_TOKEN`
   - Value: [Your Gitea API token - see below for how to create]
5. **Save the secret**

### 2. Create an API Token (if you haven't already)

1. **Log into Gitea** with your user account
2. **Go to Settings → Applications**
3. **Click "Generate New Token"**
4. **Fill in the form**:
   - Token Name: `release-automation`
   - Scopes: Select at least `repo` (full repository access)
5. **Click "Generate"**
6. **Copy the token immediately** (you won't see it again)
7. **Use this token** for the secret in step 1

### 3. Verify Gitea Actions is Enabled (Server Admin)

These steps require SSH access to your Gitea server:

```bash
# SSH into your Gitea server
ssh user@your-gitea-server

# Edit the Gitea configuration
sudo vi /etc/gitea/app.ini

# Verify or add this section:
[actions]
ENABLED = true

# Save and exit (Esc, :wq, Enter)

# Restart Gitea for changes to take effect
sudo systemctl restart gitea
```

### 4. Verify Your Runner is Online (Server Admin)

1. **Log into Gitea** as admin
2. **Go to Administration → Actions → Runners**
3. **Verify** at least one runner is listed and shows as "Online" or "Idle"
4. If no runners:
   - You need to set up a Gitea Actions runner on a machine with Docker and Go
   - See "Setting Up a Runner" below

## Setting Up a Runner (if needed)

If you don't have any runners yet, you need to set one up. This can be on the Gitea server itself or any machine with Docker/Go.

### Quick Runner Setup

1. **On your Gitea server or runner machine**:

```bash
# Download the Gitea Actions runner
wget https://github.com/gitea/act_runner/releases/download/v0.6.10/act_runner-0.6.10-linux-amd64
chmod +x act_runner-0.6.10-linux-amd64

# Register the runner with your Gitea instance
./act_runner-0.6.10-linux-amd64 register \
  --instance https://git.nerdnest.dev \
  --token <your-runner-token>

# Run the runner in the background
./act_runner-0.6.10-linux-amd64 daemon &
```

To get a runner token:
1. Log into Gitea as **admin**
2. Go to **Administration → Actions → Runners**
3. Click **Create new runner**
4. Follow the registration steps

## Testing the Setup

Once everything is configured:

1. **Push a test tag**:
```bash
git tag -a v0.0.1-test -m "Test release"
git push origin v0.0.1-test
```

2. **Monitor the build**:
   - Go to Actions tab
   - You should see the workflow running
   - Check logs for any errors

3. **Verify the release**:
   - Go to Releases tab
   - You should see a new release with binaries and checksums

## Troubleshooting

### "Action not found" error
- Make sure Gitea Actions is enabled
- Restart Gitea if you just enabled it: `sudo systemctl restart gitea`

### No runners available
- Runner must be registered: Administration → Actions → Runners
- Runner machine must have Docker and Go installed
- Check if runner is online in the UI

### "GITEA_TOKEN" not found
- Make sure the secret is named exactly `GITEA_TOKEN` (case-sensitive)
- Go to Settings → Secrets and verify it's there
- If it's there, try re-running the workflow

### Build fails with permission denied
- Make sure the runner has permission to run Docker commands
- On the runner machine: `sudo usermod -aG docker $USER`
- Logout and log back in for the group change to take effect

## What Happens Next

Once you've set everything up:

1. **Every push to main/master** triggers the build job:
   - Compiles all platform binaries
   - Builds Docker images
   - Uploads artifacts as build artifacts

2. **Every git tag push** (e.g., `v1.0.0`) triggers the full release:
   - Does all of the above
   - Creates a Gitea Release
   - Uploads all binaries and Docker images to the release
   - Generates SHA256 checksums

3. **Releases are available in**:
   - Repository Releases tab in Gitea
   - Binaries ready for download
   - Docker images ready for import

## Support

- Gitea Actions Docs: https://docs.gitea.io/en-us/actions/
- Act Runner Docs: https://gitea.com/gitea/act_runner
- For issues with the workflow itself, check the Actions tab logs