firefrost-operations-manual/docs/tasks/gitea-upgrade/upgrade-procedure.md

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

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

# 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:

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

# Check architecture
uname -m

(Should show x86_64)

# 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

# Verify download
ls -lh /tmp/gitea-1.23.7-linux-amd64

Step 2: Stop Gitea Service

sudo systemctl stop gitea

# Verify it's stopped
sudo systemctl status gitea

Step 3: Replace Binary

# Make new binary executable
chmod +x /tmp/gitea-1.23.7-linux-amd64

# Replace old binary with new one
sudo mv /tmp/gitea-1.23.7-linux-amd64 /usr/local/bin/gitea

# Set correct ownership
sudo chown root:root /usr/local/bin/gitea

# Set correct permissions
sudo chmod 755 /usr/local/bin/gitea

Step 4: Run Database Migration

# 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

sudo systemctl start gitea

# Check service status
sudo systemctl status gitea

# 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

# 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

# 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

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

# 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

# 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:

# Stop Gitea
sudo systemctl stop gitea

# Restore old binary
sudo cp /usr/local/bin/gitea-1.21.5.backup /usr/local/bin/gitea

# Restore database
sudo cp /var/lib/gitea/data/gitea.db.backup-2026-03-21 /var/lib/gitea/data/gitea.db

# Restore config (if needed)
sudo cp /etc/gitea/app.ini.backup-2026-03-21 /etc/gitea/app.ini

# Start Gitea
sudo systemctl start gitea

# 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)