From 43b7440030c9a3b18cecff41cff9e4bd621018e6 Mon Sep 17 00:00:00 2001 From: Cal Corum Date: Wed, 18 Feb 2026 14:09:08 -0600 Subject: [PATCH] Update Gitea docs for shared actions and runner config - Document DEFAULT_ACTIONS_URL=self and REQUIRE_SIGNIN_VIEW=false - Correct runner setup: internal URL, config.yaml mount, no .netrc - Add shared composite actions table (calver, gitea-tag, discord-notify) - Document action reference rules (short form local, full URL GitHub) - Add auth troubleshooting entry - Update reference implementations with all 5 projects - Replace semver references with CalVer Co-Authored-By: Claude Opus 4.6 --- server-configs/gitea/INDEX.md | 71 +++++++++++++------------- server-configs/gitea/README.md | 91 ++++++++++++++++++++++++---------- 2 files changed, 102 insertions(+), 60 deletions(-) diff --git a/server-configs/gitea/INDEX.md b/server-configs/gitea/INDEX.md index ce02385..972fbfd 100644 --- a/server-configs/gitea/INDEX.md +++ b/server-configs/gitea/INDEX.md @@ -32,11 +32,12 @@ Quick reference for all Gitea-related documentation and templates. **File:** `workflow-templates/docker-build-template.yml` **Features:** -- ✅ Semantic version validation +- ✅ CalVer versioning (YYYY.MM.BUILD) via shared `cal/gitea-actions/calver` action - ✅ Docker build + push to Docker Hub -- ✅ Discord notifications -- ✅ Build caching -- ✅ Multi-tag strategy +- ✅ Discord notifications via shared `cal/gitea-actions/discord-notify` action +- ✅ Git tagging via shared `cal/gitea-actions/gitea-tag` action +- ✅ Build caching (registry-based) +- ✅ Multi-tag strategy (latest, version, version+sha, dev) **Use for:** - Discord bots @@ -105,28 +106,23 @@ Quick reference for all Gitea-related documentation and templates. ## 📝 Reference Implementations -### Paper Dynasty Discord Bot -**Status:** ✅ Production -**Date:** 2026-02-04 +### Projects Using Shared Actions +All use `cal/gitea-actions` composite actions (CalVer, git tagging, Discord notify): -**Setup:** -- Gitea Actions on LXC 225 -- Docker build + push to Docker Hub -- Discord notifications working -- Manual deployment to sba-bots (10.10.0.88) +| Project | Workflow | Type | +|---------|----------|------| +| major-domo-database | `docker-build.yml` | Docker build + push | +| paper-dynasty-discord | `docker-build.yml` | Docker build + push | +| paper-dynasty-database | `build.yml` | Docker build + push | +| major-domo-v2 | `docker-build.yml` | Docker build + push | +| vagabond-rpg-foundryvtt | `deploy.yml` | Build + rsync deploy | -**Workflow:** Based on `docker-build-template.yml` - -**What worked:** -- Semantic version validation -- Multi-tag strategy (latest, version, version+commit) -- Discord webhooks with ISO 8601 timestamps -- GitHub Actions cache for faster builds - -**Lessons learned:** -- Timestamp format critical for Discord (ISO 8601) -- Health checks needed before auto-deploy -- Manual deploy preferred for production Discord bots +### Lessons Learned +- Runner `GITEA_INSTANCE_URL` must use internal IP, not public domain (host mismatch breaks auth) +- `DEFAULT_ACTIONS_URL=self` + short-form refs for local actions, full URLs for GitHub actions +- `REQUIRE_SIGNIN_VIEW=false` is safe — only public repos are exposed, private repos stay locked +- Registry-based Docker build cache (`type=registry`) requires Docker Hub login on every build +- Manual deploy preferred for production Discord bots (health checks needed before auto-deploy) ## 🔧 Common Tasks @@ -134,14 +130,19 @@ Quick reference for all Gitea-related documentation and templates. ```bash cd /path/to/your/repo mkdir -p .gitea/workflows -cp /path/to/docker-build-template.yml .gitea/workflows/docker-build.yml + +# Copy from an existing project (e.g., major-domo-database) +cp /mnt/NV2/Development/major-domo/database/.gitea/workflows/docker-build.yml \ + .gitea/workflows/docker-build.yml # Customize: -# - Replace "yourusername/yourrepo" with your Docker Hub repo -# - Replace "Your Project" in notifications -# - Replace Discord webhook URLs -# - Add secrets: DOCKERHUB_USERNAME, DOCKERHUB_TOKEN -# - Create VERSION file: echo "1.0.0" > VERSION +# - Replace Docker Hub image name (manticorum67/your-project) +# - Replace project title in Discord notifications +# - Add repo secrets: DOCKERHUB_USERNAME, DOCKERHUB_TOKEN, DISCORD_WEBHOOK +# +# Action reference rules (DEFAULT_ACTIONS_URL=self): +# - Local actions: short form (cal/gitea-actions/calver@main) +# - GitHub actions: full URL (https://github.com/actions/checkout@v4) ``` ### Add Auto-Deploy (When Ready) @@ -174,10 +175,10 @@ chmod +x /path/to/repo/deploy.sh ## 🆘 Troubleshooting -### Version validation failing -- Check VERSION file format: just `1.2.3` -- Ensure semver rules followed -- See template comments for valid bumps +### CalVer version looks wrong +- CalVer is auto-generated from git tags (YYYY.MM.BUILD) +- BUILD number counts tags in the current month +- Ensure `fetch-depth: 0` in checkout step (needs full tag history) ### Docker Hub push failing - Verify secrets set in Gitea @@ -210,7 +211,7 @@ chmod +x /path/to/repo/deploy.sh - Changing directory structure - Adding reference implementations -**Last updated:** 2026-02-04 +**Last updated:** 2026-02-18 --- diff --git a/server-configs/gitea/README.md b/server-configs/gitea/README.md index 8cf4de0..2bc74e6 100644 --- a/server-configs/gitea/README.md +++ b/server-configs/gitea/README.md @@ -102,6 +102,19 @@ PGPASSWORD=gitea123 psql -U gitea -d gitea -h 127.0.0.1 - ✅ **Organizations** - Multi-user repository groups - ✅ **Webhooks** - Integration with external services +### Key app.ini Settings (Actions) +```ini +[actions] +DEFAULT_ACTIONS_URL = self # Short-form actions resolve against local Gitea instance + +[service] +REQUIRE_SIGNIN_VIEW = false # Public repos (like gitea-actions) cloneable without auth +``` + +- `DEFAULT_ACTIONS_URL=self` means `uses: cal/gitea-actions/calver@main` resolves locally +- `REQUIRE_SIGNIN_VIEW=false` only exposes PUBLIC repos — all private repos remain locked down +- The only public repo is `cal/gitea-actions` (reusable CI composite actions, no sensitive code) + ## Backup ### What to Backup @@ -162,45 +175,64 @@ journalctl -u gitea -f ## Setting Up CI/CD with Gitea Actions -Gitea Actions are enabled and ready to use. To set up a runner: +Gitea Actions are enabled and the runner is deployed on the same LXC. -### Option 1: Docker Runner (Recommended) -Since the LXC has nesting enabled, you can run a Docker-based Actions runner: +### Runner Container ```bash -# Install Docker in the LXC -curl -fsSL https://get.docker.com | sh - -# Run Gitea Actions runner +# Current production runner setup docker run -d \ --name gitea-runner \ --restart unless-stopped \ - -v /var/run/docker.sock:/var/run/docker.sock \ - -e GITEA_INSTANCE_URL=https://git.manticorum.com \ -e GITEA_RUNNER_REGISTRATION_TOKEN= \ + -e GITEA_INSTANCE_URL=http://10.10.0.225:3000 \ + -v /var/run/docker.sock:/var/run/docker.sock \ + -v gitea-runner-data:/data \ + -v /etc/gitea/runner-config.yaml:/config.yaml:ro \ gitea/act_runner:latest ``` -### Option 2: Separate Runner LXC -Create a dedicated LXC for running Actions with more isolation. +**CRITICAL**: `GITEA_INSTANCE_URL` must be the **internal** URL (`http://10.10.0.225:3000`), not the public domain. The runner uses this for API communication and auth token matching. -### Using Actions -Create `.gitea/workflows/main.yml` in your repository: +### Runner Config (`/etc/gitea/runner-config.yaml`) + +Key settings: +- `container.options: --add-host=git.manticorum.com:host-gateway` — lets job containers resolve the public domain +- `container.force_pull: true` — always pulls latest runner images +- Labels: `ubuntu-latest`, `ubuntu-22.04`, `ubuntu-20.04` + +### Shared Composite Actions (`cal/gitea-actions`) + +Reusable CI/CD actions shared across all projects. This repo is **public** (required for runner auth). + +| Action | Purpose | +|--------|---------| +| `cal/gitea-actions/calver@main` | Generate CalVer version (YYYY.MM.BUILD) from git tags | +| `cal/gitea-actions/gitea-tag@main` | Create git tag via Gitea API | +| `cal/gitea-actions/discord-notify@main` | Send Discord embed notification via webhook | + +### Action Reference Rules + +Because `DEFAULT_ACTIONS_URL=self` is set: ```yaml -name: CI -on: [push, pull_request] -jobs: - build: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - name: Run tests - run: | - npm install - npm test +# Local actions (cal/gitea-actions) — use SHORT FORM +uses: cal/gitea-actions/calver@main + +# GitHub actions — use FULL URL (otherwise they'd resolve against local Gitea) +uses: https://github.com/actions/checkout@v4 +uses: https://github.com/docker/setup-buildx-action@v3 +uses: https://github.com/docker/login-action@v3 +uses: https://github.com/docker/build-push-action@v5 ``` +### Creating a New Workflow + +1. Copy an existing workflow as a template (e.g., from major-domo-database) +2. Use short form for `cal/gitea-actions/*` references +3. Use `https://github.com/` prefix for all GitHub action references +4. Required secrets: `DOCKERHUB_USERNAME`, `DOCKERHUB_TOKEN`, `DISCORD_WEBHOOK` + ## Adding Repositories ### Via Web UI @@ -273,9 +305,16 @@ curl http://10.10.0.225:3000 ### Actions runner not working - Ensure runner is registered in Gitea Admin → Actions → Runners - Check runner logs: `docker logs gitea-runner` -- Verify GITEA_INSTANCE_URL is correct +- Verify `GITEA_INSTANCE_URL` uses internal URL (`http://10.10.0.225:3000`), NOT the public domain - Ensure runner has network access to Gitea +### Actions can't clone composite actions ("authentication required") +- Verify `REQUIRE_SIGNIN_VIEW = false` in app.ini (allows public repo clone without auth) +- Verify `DEFAULT_ACTIONS_URL = self` in app.ini +- Use short-form references for local actions (`cal/gitea-actions/calver@main`) +- Use full GitHub URLs for GitHub actions (`https://github.com/actions/checkout@v4`) +- The `cal/gitea-actions` repo must be set to **public** visibility + ## Security Notes - Database password is stored in `/etc/gitea/app.ini` (secured with 640 permissions) @@ -283,6 +322,8 @@ curl http://10.10.0.225:3000 - JWT secrets are auto-generated and stored in config - LXC is unprivileged for better isolation - PostgreSQL only listens on localhost +- `REQUIRE_SIGNIN_VIEW=false` — only public repos are accessible without login; all private repos remain fully protected +- The only public repo is `cal/gitea-actions` (audited — contains no secrets or sensitive code) ## Related Documentation