From 000eaa8c7f17cef9ba821196fc2b02f1838ebbbd Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 21 Mar 2026 07:51:53 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20create=20Gitea=20upgrade=20procedure=20?= =?UTF-8?q?1.21.5=20=E2=86=92=201.23.7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Complete upgrade guide to enable Projects REST API: - Pre-upgrade checklist with backup procedures - Step-by-step binary upgrade process - Database migration steps - Post-upgrade verification tests - Rollback procedure if needed - API endpoint testing commands Why: Gitea 1.21.5 has no Projects API (confirmed by Gemini). Projects API introduced in 1.22.x, fully functional in 1.23.x. This upgrade enables automated issue-to-project-board workflow. Estimated time: 15-30 minutes Risk level: LOW (SQLite backup + binary rollback) Signed-off-by: The Chronicler --- docs/tasks/gitea-upgrade/upgrade-procedure.md | 279 ++++++++++++++++++ 1 file changed, 279 insertions(+) create mode 100644 docs/tasks/gitea-upgrade/upgrade-procedure.md diff --git a/docs/tasks/gitea-upgrade/upgrade-procedure.md b/docs/tasks/gitea-upgrade/upgrade-procedure.md new file mode 100644 index 0000000..33eb560 --- /dev/null +++ b/docs/tasks/gitea-upgrade/upgrade-procedure.md @@ -0,0 +1,279 @@ +# Gitea Upgrade: 1.21.5 → 1.23.x (Projects API) + +**Date:** March 21, 2026 +**Reason:** Enable Projects REST API for automatic issue-to-board syncing +**Current Version:** 1.21.5 +**Target Version:** 1.23.7 (latest stable as of March 2026) +**Estimated Time:** 15-30 minutes +**Downtime:** ~5 minutes + +--- + +## Why We're Upgrading + +**Problem:** Gitea 1.21.5 has NO Projects REST API - endpoints literally don't exist in the router + +**Solution:** Upgrade to 1.23.x which includes: +- ✅ Full Projects REST API +- ✅ Ability to programmatically add issues to project columns +- ✅ Automated workflow: script creates issue → auto-adds to "Backlog" column + +**Gemini confirmed:** Projects API introduced in 1.22.x (basic), fully functional in 1.23.x + +--- + +## Pre-Upgrade Checklist + +**CRITICAL - Do these FIRST:** + +### 1. Check Latest Gitea Version +```bash +curl -s https://api.github.com/repos/go-gitea/gitea/releases/latest | grep "tag_name" +``` +This shows the actual latest version. Adjust target version if needed. + +### 2. Backup Everything +```bash +# Stop Gitea +sudo systemctl stop gitea + +# Backup database +sudo cp /var/lib/gitea/data/gitea.db /var/lib/gitea/data/gitea.db.backup-2026-03-21 + +# Backup configuration +sudo cp /etc/gitea/app.ini /etc/gitea/app.ini.backup-2026-03-21 + +# Backup current binary +sudo cp /usr/local/bin/gitea /usr/local/bin/gitea-1.21.5.backup + +# Start Gitea again +sudo systemctl start gitea +``` + +**Verify backups exist:** +```bash +ls -lh /var/lib/gitea/data/gitea.db.backup-2026-03-21 +ls -lh /etc/gitea/app.ini.backup-2026-03-21 +ls -lh /usr/local/bin/gitea-1.21.5.backup +``` + +--- + +## Upgrade Procedure + +### Step 1: Download New Gitea Binary +```bash +# Check architecture +uname -m +``` +(Should show x86_64) + +```bash +# Download Gitea 1.23.7 (adjust version if latest is different) +cd /tmp +wget https://dl.gitea.com/gitea/1.23.7/gitea-1.23.7-linux-amd64 +``` + +```bash +# Verify download +ls -lh /tmp/gitea-1.23.7-linux-amd64 +``` + +### Step 2: Stop Gitea Service +```bash +sudo systemctl stop gitea +``` + +```bash +# Verify it's stopped +sudo systemctl status gitea +``` + +### Step 3: Replace Binary +```bash +# Make new binary executable +chmod +x /tmp/gitea-1.23.7-linux-amd64 +``` + +```bash +# Replace old binary with new one +sudo mv /tmp/gitea-1.23.7-linux-amd64 /usr/local/bin/gitea +``` + +```bash +# Set correct ownership +sudo chown root:root /usr/local/bin/gitea +``` + +```bash +# Set correct permissions +sudo chmod 755 /usr/local/bin/gitea +``` + +### Step 4: Run Database Migration +```bash +# Run as gitea user to apply schema updates +sudo -u gitea /usr/local/bin/gitea migrate -c /etc/gitea/app.ini +``` + +**IMPORTANT:** This step migrates the SQLite database schema to support new features (including Projects API). Watch for any errors. + +### Step 5: Start Gitea +```bash +sudo systemctl start gitea +``` + +```bash +# Check service status +sudo systemctl status gitea +``` + +```bash +# Watch logs for errors +sudo journalctl -u gitea -f --lines=50 +``` +(Press Ctrl+C to stop watching logs once you see "Server is running") + +### Step 6: Verify Upgrade +```bash +# Check version via API +curl -s https://git.firefrostgaming.com/api/v1/version +``` + +Should show version 1.23.7 (or whatever you installed) + +**Test in browser:** +1. Open https://git.firefrostgaming.com +2. Login as mkrause612 +3. Navigate to Firefrost Operations project board +4. Verify board still works and all issues are present + +--- + +## Post-Upgrade Verification + +### Check Projects API Is Now Available +```bash +# This should NOW work (was 404 before) +curl -s -H "Authorization: token e0e330cba1749b01ab505093a160e4423ebbbe36" \ +"https://git.firefrostgaming.com/api/v1/orgs/firefrost-gaming/projects" +``` + +**Expected:** JSON response with project list (not 404) + +### Test Adding Issue to Project Column + +**Step 1: Get Project ID** +```bash +curl -s -H "Authorization: token e0e330cba1749b01ab505093a160e4423ebbbe36" \ +"https://git.firefrostgaming.com/api/v1/orgs/firefrost-gaming/projects" | python3 -c "import sys, json; projects = json.load(sys.stdin); [print(f'Project: {p[\"title\"]} (ID: {p[\"id\"]})') for p in projects]" +``` + +**Step 2: Get Column IDs** +```bash +# Replace PROJECT_ID with actual ID from step 1 +curl -s -H "Authorization: token e0e330cba1749b01ab505093a160e4423ebbbe36" \ +"https://git.firefrostgaming.com/api/v1/projects/PROJECT_ID/columns" | python3 -c "import sys, json; cols = json.load(sys.stdin); [print(f'Column: {c[\"title\"]} (ID: {c[\"id\"]})') for c in cols]" +``` + +**Step 3: Test Adding Issue to Backlog** +```bash +# Replace COLUMN_ID with Backlog column ID, ISSUE_ID with a test issue number +curl -X POST -H "Authorization: token e0e330cba1749b01ab505093a160e4423ebbbe36" \ +-H "Content-Type: application/json" \ +-d '{"issues": [ISSUE_ID]}' \ +"https://git.firefrostgaming.com/api/v1/projects/columns/COLUMN_ID/issues" +``` + +Check the project board - the issue should now appear in the Backlog column! + +--- + +## Rollback Procedure (If Something Goes Wrong) + +**If upgrade fails, here's how to rollback:** + +```bash +# Stop Gitea +sudo systemctl stop gitea +``` + +```bash +# Restore old binary +sudo cp /usr/local/bin/gitea-1.21.5.backup /usr/local/bin/gitea +``` + +```bash +# Restore database +sudo cp /var/lib/gitea/data/gitea.db.backup-2026-03-21 /var/lib/gitea/data/gitea.db +``` + +```bash +# Restore config (if needed) +sudo cp /etc/gitea/app.ini.backup-2026-03-21 /etc/gitea/app.ini +``` + +```bash +# Start Gitea +sudo systemctl start gitea +``` + +```bash +# Verify version is back to 1.21.5 +curl -s https://git.firefrostgaming.com/api/v1/version +``` + +--- + +## Success Criteria + +- ✅ Gitea reports version 1.23.7 (or target version) +- ✅ Web UI loads and login works +- ✅ "Firefrost Operations" project board displays correctly +- ✅ All issues and columns are present +- ✅ Projects API endpoints return JSON (not 404) +- ✅ Can retrieve project/column IDs via API +- ✅ Can add test issue to project column via API + +--- + +## Next Steps After Successful Upgrade + +1. **Update sync script** to use Projects API +2. **Test automated workflow:** create issue → auto-add to Backlog +3. **Update documentation** with new version number +4. **Remove manual label workflow** (no longer needed) +5. **Commit upgrade notes** to operations manual + +--- + +## Common Issues & Solutions + +**Issue:** "gitea migrate" fails with schema error +**Solution:** Check /var/lib/gitea/log/gitea.log for details, may need to restore backup and investigate + +**Issue:** Nginx returns 502 Bad Gateway after upgrade +**Solution:** Check `sudo systemctl status gitea` - service may have failed to start, check logs with `journalctl -u gitea` + +**Issue:** Projects API still returns 404 after upgrade +**Solution:** Verify version with `curl https://git.firefrostgaming.com/api/v1/version` - may have wrong binary + +**Issue:** Database corruption after migration +**Solution:** Restore backup database, investigate migration logs before retrying + +--- + +## Documentation Updates Required + +After successful upgrade: +- [ ] Update `docs/deployment/gitea.md` with new version number +- [ ] Update `docs/core/infrastructure-manifest.md` +- [ ] Document Projects API endpoints in reference docs +- [ ] Update task sync script with Projects API integration +- [ ] Create "How to use Projects API" guide + +--- + +**Created:** March 21, 2026 (Session 37 - The Chronicler) +**Status:** READY TO EXECUTE +**Risk Level:** LOW (SQLite backup + binary rollback = easy recovery)