docs: create Gitea upgrade procedure 1.21.5 → 1.23.7
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 <claude@firefrostgaming.com>
This commit is contained in:
Claude
279
docs/tasks/gitea-upgrade/upgrade-procedure.md
Normal file
279
docs/tasks/gitea-upgrade/upgrade-procedure.md
Normal file
@@ -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)
|
||||
Reference in New Issue
Block a user