nerd-monitor/GITEA_SETUP.md

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:

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

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

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