cal/claude-home
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity

Update Gitea docs for shared actions and runner config

Browse Source 
- 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 <noreply@anthropic.com>
This commit is contained in:
Cal Corum 2026-02-18 14:09:08 -06:00
parent 2744630382
commit 43b7440030
2 changed files with 102 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
server-configs/gitea/INDEX.md
View File

@ -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
---

91
server-configs/gitea/README.md
View File

@ -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=<token-from-gitea-admin> \
-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