diff --git a/GITEA_SETUP.md b/GITEA_SETUP.md index 60b4ac9..85b4560 100644 --- a/GITEA_SETUP.md +++ b/GITEA_SETUP.md @@ -58,7 +58,7 @@ sudo systemctl restart gitea ## 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. +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 and Go. ### Quick Runner Setup @@ -84,45 +84,25 @@ To get a runner token: 3. Click **Create new runner** 4. Follow the registration steps -## Testing the Setup +### Installing Docker on the Runner (Optional) -Once everything is configured: +If you want to build Docker images as part of your releases, install Docker on the runner: -1. **Push a test tag**: ```bash -git tag -a v0.0.1-test -m "Test release" -git push origin v0.0.1-test +# Install Docker +curl -fsSL https://get.docker.com -o get-docker.sh +sudo sh get-docker.sh + +# Add permissions for the runner user to use Docker +sudo usermod -aG docker $USER + +# Verify Docker is working +docker --version + +# Note: You may need to logout and login for group permissions to take effect ``` -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 +**Without Docker**: The binary builds will still work. Only Docker image generation will be skipped (the workflow will show a warning but still succeed). ## What Happens Next @@ -130,22 +110,51 @@ Once you've set everything up: 1. **Every push to main/master** triggers the build job: - Compiles all platform binaries - - Builds Docker images + - Attempts to build Docker images (skips if Docker unavailable) - 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 + - Uploads all binaries and checksums to the release + - Uploads Docker images if available 3. **Releases are available in**: - Repository Releases tab in Gitea - Binaries ready for download - - Docker images ready for import + - Docker images (if Docker is available on runner) + +## Troubleshooting + +### "docker: command not found" in workflow +- Docker is not installed on your runner +- This is **optional** - binaries will still build +- If you want Docker images, install Docker on the runner (see above) +- The workflow will gracefully skip Docker builds and show a warning + +### "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 Go installed (1.24.4 or later) +- Docker is optional (for building Docker images) +- 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 (Docker) +- Make sure the runner user 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 ## Support - Gitea Actions Docs: https://docs.gitea.io/en-us/actions/ - Act Runner Docs: https://gitea.com/gitea/act_runner +- Docker Installation: https://docs.docker.com/install/ - For issues with the workflow itself, check the Actions tab logs