# Gitea Integration Guide\n\nComplete guide to using Gitea integration for workspace management, extension distribution, and collaboration.\n\n**Version:** 1.0.0\n**Last Updated:** 2025-10-06\n\n---\n\n## Table of Contents\n\n1. [Overview](#overview)\n2. [Setup](#setup)\n3. [Workspace Git Integration](#workspace-git-integration)\n4. [Workspace Locking](#workspace-locking)\n5. [Extension Publishing](#extension-publishing)\n6. [Service Management](#service-management)\n7. [API Reference](#api-reference)\n8. [Troubleshooting](#troubleshooting)\n\n---\n\n## Overview\n\nThe Gitea integration provides:\n\n- **Workspace Git Integration**: Version control for workspaces\n- **Distributed Locking**: Prevent concurrent workspace modifications\n- **Extension Distribution**: Publish and download extensions via releases\n- **Collaboration**: Share workspaces and extensions across teams\n- **Service Management**: Deploy and manage local Gitea instance\n\n### Architecture\n\n```\n┌─────────────────────────────────────────────────────────┐\n│                 Provisioning System                      │\n├─────────────────────────────────────────────────────────┤\n│                                                          │\n│  ┌────────────┐  ┌──────────────┐  ┌─────────────────┐ │\n│  │ Workspace  │  │   Extension  │  │    Locking      │ │\n│  │   Git      │  │  Publishing  │  │   (Issues)      │ │\n│  └─────┬──────┘  └──────┬───────┘  └────────┬────────┘ │\n│        │                │                     │          │\n│        └────────────────┼─────────────────────┘          │\n│                         │                                │\n│                  ┌──────▼──────┐                         │\n│                  │  Gitea API  │                         │\n│                  │   Client    │                         │\n│                  └──────┬──────┘                         │\n│                         │                                │\n└─────────────────────────┼────────────────────────────────┘\n                          │\n                  ┌───────▼────────┐\n                  │  Gitea Service │\n                  │  (Local/Remote)│\n                  └────────────────┘\n```\n\n---\n\n## Setup\n\n### Prerequisites\n\n- **Nushell 0.107.1+**\n- **Git** installed and configured\n- **Docker** (for local Gitea deployment) or access to remote Gitea instance\n- **SOPS** (for encrypted token storage)\n\n### Configuration\n\n#### 1. Add Gitea Configuration to Nickel\n\nEdit your `provisioning/schemas/modes.ncl` or workspace config:\n\n```\nimport provisioning.gitea as gitea\n\n# Local Docker deployment\n_gitea_config = gitea.GiteaConfig {\n    mode = "local"\n    local = gitea.LocalGitea {\n        enabled = True\n        deployment = "docker"\n        port = 3000\n        auto_start = True\n        docker = gitea.DockerGitea {\n            image = "gitea/gitea:1.21"\n            container_name = "provisioning-gitea"\n        }\n    }\n    auth = gitea.GiteaAuth {\n        token_path = "~/.provisioning/secrets/gitea-token.enc"\n        username = "provisioning"\n    }\n}\n\n# Or remote Gitea instance\n_gitea_remote = gitea.GiteaConfig {\n    mode = "remote"\n    remote = gitea.RemoteGitea {\n        enabled = True\n        url = "https://gitea.example.com"\n        api_url = "https://gitea.example.com/api/v1"\n    }\n    auth = gitea.GiteaAuth {\n        token_path = "~/.provisioning/secrets/gitea-token.enc"\n        username = "myuser"\n    }\n}\n```\n\n#### 2. Create Gitea Access Token\n\nFor local Gitea:\n\n1. Start Gitea: `provisioning gitea start`\n2. Open <http://localhost:3000>\n3. Register admin account\n4. Go to Settings → Applications → Generate New Token\n5. Save token to encrypted file:\n\n```\n# Create encrypted token file\necho "your-gitea-token" | sops --encrypt /dev/stdin > ~/.provisioning/secrets/gitea-token.enc\n```\n\nFor remote Gitea:\n\n1. Login to your Gitea instance\n2. Generate personal access token\n3. Save encrypted as above\n\n#### 3. Verify Setup\n\n```\n# Check Gitea status\nprovisioning gitea status\n\n# Validate token\nprovisioning gitea auth validate\n\n# Show current user\nprovisioning gitea user\n```\n\n---\n\n## Workspace Git Integration\n\n### Initialize Workspace with Git\n\nWhen creating a new workspace, enable git integration:\n\n```\n# Initialize new workspace with Gitea\nprovisioning workspace init my-workspace --git --remote gitea\n\n# Or initialize existing workspace\ncd workspace_my-workspace\nprovisioning gitea workspace init . my-workspace --remote gitea\n```\n\nThis will:\n\n1. Initialize git repository in workspace\n2. Create repository on Gitea (`workspaces/my-workspace`)\n3. Add remote origin\n4. Push initial commit\n\n### Clone Existing Workspace\n\n```\n# Clone from Gitea\nprovisioning workspace clone workspaces/my-workspace ./workspace_my-workspace\n\n# Or using full identifier\nprovisioning workspace clone my-workspace ./workspace_my-workspace\n```\n\n### Push/Pull Changes\n\n```\n# Push workspace changes\ncd workspace_my-workspace\nprovisioning workspace push --message "Updated infrastructure configs"\n\n# Pull latest changes\nprovisioning workspace pull\n\n# Sync (pull + push)\nprovisioning workspace sync\n```\n\n### Branch Management\n\n```\n# Create branch\nprovisioning workspace branch create feature-new-cluster\n\n# Switch branch\nprovisioning workspace branch switch feature-new-cluster\n\n# List branches\nprovisioning workspace branch list\n\n# Delete branch\nprovisioning workspace branch delete feature-new-cluster\n```\n\n### Git Status\n\n```\n# Get workspace git status\nprovisioning workspace git status\n\n# Show uncommitted changes\nprovisioning workspace git diff\n\n# Show staged changes\nprovisioning workspace git diff --staged\n```\n\n---\n\n## Workspace Locking\n\nDistributed locking prevents concurrent modifications to workspaces using Gitea issues.\n\n### Lock Types\n\n- **read**: Multiple readers allowed, blocks writers\n- **write**: Exclusive access, blocks all other locks\n- **deploy**: Exclusive access for deployments\n\n### Acquire Lock\n\n```\n# Acquire write lock\nprovisioning gitea lock acquire my-workspace write \\n    --operation "Deploying servers" \\n    --expiry "2025-10-06T14:00:00Z"\n\n# Output:\n# ✓ Lock acquired for workspace: my-workspace\n#   Lock ID: 42\n#   Type: write\n#   User: provisioning\n```\n\n### Check Lock Status\n\n```\n# List locks for workspace\nprovisioning gitea lock list my-workspace\n\n# List all active locks\nprovisioning gitea lock list\n\n# Get lock details\nprovisioning gitea lock info my-workspace 42\n```\n\n### Release Lock\n\n```\n# Release lock\nprovisioning gitea lock release my-workspace 42\n```\n\n### Force Release Lock (Admin)\n\n```\n# Force release stuck lock\nprovisioning gitea lock force-release my-workspace 42 \\n    --reason "Deployment failed, releasing lock"\n```\n\n### Automatic Locking\n\nUse `with-workspace-lock` for automatic lock management:\n\n```\nuse lib_provisioning/gitea/locking.nu *\n\nwith-workspace-lock "my-workspace" "deploy" "Server deployment" {\n    # Your deployment code here\n    # Lock automatically released on completion or error\n}\n```\n\n### Lock Cleanup\n\n```\n# Cleanup expired locks\nprovisioning gitea lock cleanup\n```\n\n---\n\n## Extension Publishing\n\nPublish taskservs, providers, and clusters as versioned releases on Gitea.\n\n### Publish Extension\n\n```\n# Publish taskserv\nprovisioning gitea extension publish \\n    ./extensions/taskservs/database/postgres \\n    1.2.0 \\n    --release-notes "Added connection pooling support"\n\n# Publish provider\nprovisioning gitea extension publish \\n    ./extensions/providers/aws_prov \\n    2.0.0 \\n    --prerelease\n\n# Publish cluster\nprovisioning gitea extension publish \\n    ./extensions/clusters/buildkit \\n    1.0.0\n```\n\nThis will:\n\n1. Validate extension structure\n2. Create git tag (if workspace is git repo)\n3. Package extension as `.tar.gz`\n4. Create Gitea release\n5. Upload package as release asset\n\n### List Published Extensions\n\n```\n# List all extensions\nprovisioning gitea extension list\n\n# Filter by type\nprovisioning gitea extension list --type taskserv\nprovisioning gitea extension list --type provider\nprovisioning gitea extension list --type cluster\n```\n\n### Download Extension\n\n```\n# Download specific version\nprovisioning gitea extension download postgres 1.2.0 \\n    --destination ./extensions/taskservs/database\n\n# Extension is downloaded and extracted automatically\n```\n\n### Extension Metadata\n\n```\n# Get extension information\nprovisioning gitea extension info postgres 1.2.0\n```\n\n### Publishing Workflow\n\n```\n# 1. Make changes to extension\ncd extensions/taskservs/database/postgres\n\n# 2. Update version in kcl/kcl.mod\n# 3. Update CHANGELOG.md\n\n# 4. Commit changes\ngit add .\ngit commit -m "Release v1.2.0"\n\n# 5. Publish to Gitea\nprovisioning gitea extension publish . 1.2.0\n```\n\n---\n\n## Service Management\n\n### Start/Stop Gitea\n\n```\n# Start Gitea (local mode)\nprovisioning gitea start\n\n# Stop Gitea\nprovisioning gitea stop\n\n# Restart Gitea\nprovisioning gitea restart\n```\n\n### Check Status\n\n```\n# Get service status\nprovisioning gitea status\n\n# Output:\n# Gitea Status:\n#   Mode: local\n#   Deployment: docker\n#   Running: true\n#   Port: 3000\n#   URL: http://localhost:3000\n#   Container: provisioning-gitea\n#   Health: ✓ OK\n```\n\n### View Logs\n\n```\n# View recent logs\nprovisioning gitea logs\n\n# Follow logs\nprovisioning gitea logs --follow\n\n# Show specific number of lines\nprovisioning gitea logs --lines 200\n```\n\n### Install Gitea Binary\n\n```\n# Install latest version\nprovisioning gitea install\n\n# Install specific version\nprovisioning gitea install 1.21.0\n\n# Custom install directory\nprovisioning gitea install --install-dir ~/bin\n```\n\n---\n\n## API Reference\n\n### Repository Operations\n\n```\nuse lib_provisioning/gitea/api_client.nu *\n\n# Create repository\ncreate-repository "my-org" "my-repo" "Description" true\n\n# Get repository\nget-repository "my-org" "my-repo"\n\n# Delete repository\ndelete-repository "my-org" "my-repo" --force\n\n# List repositories\nlist-repositories "my-org"\n```\n\n### Release Operations\n\n```\n# Create release\ncreate-release "my-org" "my-repo" "v1.0.0" "Release Name" "Notes"\n\n# Upload asset\nupload-release-asset "my-org" "my-repo" 123 "./file.tar.gz"\n\n# Get release\nget-release-by-tag "my-org" "my-repo" "v1.0.0"\n\n# List releases\nlist-releases "my-org" "my-repo"\n```\n\n### Workspace Operations\n\n```\nuse lib_provisioning/gitea/workspace_git.nu *\n\n# Initialize workspace git\ninit-workspace-git "./workspace_test" "test" --remote "gitea"\n\n# Clone workspace\nclone-workspace "workspaces/my-workspace" "./workspace_my-workspace"\n\n# Push changes\npush-workspace "./workspace_my-workspace" "Updated configs"\n\n# Pull changes\npull-workspace "./workspace_my-workspace"\n```\n\n### Locking Operations\n\n```\nuse lib_provisioning/gitea/locking.nu *\n\n# Acquire lock\nlet lock = acquire-workspace-lock "my-workspace" "write" "Deployment"\n\n# Release lock\nrelease-workspace-lock "my-workspace" $lock.lock_id\n\n# Check if locked\nis-workspace-locked "my-workspace" "write"\n\n# List locks\nlist-workspace-locks "my-workspace"\n```\n\n---\n\n## Troubleshooting\n\n### Gitea Not Starting\n\n**Problem**: `provisioning gitea start` fails\n\n**Solutions**:\n\n```\n# Check Docker status\ndocker ps\n\n# Check if port is in use\nlsof -i :3000\n\n# Check Gitea logs\nprovisioning gitea logs\n\n# Remove old container\ndocker rm -f provisioning-gitea\nprovisioning gitea start\n```\n\n### Token Authentication Failed\n\n**Problem**: `provisioning gitea auth validate` returns false\n\n**Solutions**:\n\n```\n# Verify token file exists\nls ~/.provisioning/secrets/gitea-token.enc\n\n# Test decryption\nsops --decrypt ~/.provisioning/secrets/gitea-token.enc\n\n# Regenerate token in Gitea UI\n# Save new token\necho "new-token" | sops --encrypt /dev/stdin > ~/.provisioning/secrets/gitea-token.enc\n```\n\n### Cannot Push to Repository\n\n**Problem**: Git push fails with authentication error\n\n**Solutions**:\n\n```\n# Check remote URL\ncd workspace_my-workspace\ngit remote -v\n\n# Reconfigure remote with token\ngit remote set-url origin http://username:token@localhost:3000/org/repo.git\n\n# Or use SSH\ngit remote set-url origin git@localhost:workspaces/my-workspace.git\n```\n\n### Lock Already Exists\n\n**Problem**: Cannot acquire lock, workspace already locked\n\n**Solutions**:\n\n```\n# Check active locks\nprovisioning gitea lock list my-workspace\n\n# Get lock details\nprovisioning gitea lock info my-workspace 42\n\n# If lock is stale, force release\nprovisioning gitea lock force-release my-workspace 42 --reason "Stale lock"\n```\n\n### Extension Validation Failed\n\n**Problem**: Extension publishing fails validation\n\n**Solutions**:\n\n```\n# Check extension structure\nls -la extensions/taskservs/myservice/\n# Required:\n# - schemas/manifest.toml\n# - schemas/*.ncl (main schema file)\n\n# Verify manifest.toml format\ncat extensions/taskservs/myservice/schemas/manifest.toml\n\n# Should have:\n# [package]\n# name = "myservice"\n# version = "1.0.0"\n```\n\n### Docker Volume Permissions\n\n**Problem**: Gitea Docker container has permission errors\n\n**Solutions**:\n\n```\n# Fix data directory permissions\nsudo chown -R 1000:1000 ~/.provisioning/gitea\n\n# Or recreate with correct permissions\nprovisioning gitea stop --remove\nrm -rf ~/.provisioning/gitea\nprovisioning gitea start\n```\n\n---\n\n## Best Practices\n\n### Workspace Management\n\n1. **Always use locking** for concurrent operations\n2. **Commit frequently** with descriptive messages\n3. **Use branches** for experimental changes\n4. **Sync before operations** to get latest changes\n\n### Extension Publishing\n\n1. **Follow semantic versioning** (MAJOR.MINOR.PATCH)\n2. **Update CHANGELOG.md** for each release\n3. **Test extensions** before publishing\n4. **Use prerelease flag** for beta versions\n\n### Security\n\n1. **Encrypt tokens** with SOPS\n2. **Use private repositories** for sensitive workspaces\n3. **Rotate tokens** regularly\n4. **Audit lock history** via Gitea issues\n\n### Performance\n\n1. **Cleanup expired locks** periodically\n2. **Use shallow clones** for large workspaces\n3. **Archive old releases** to reduce storage\n4. **Monitor Gitea resources** for local deployments\n\n---\n\n## Advanced Usage\n\n### Custom Gitea Deployment\n\nEdit `docker-compose.yml`:\n\n```\nservices:\n  gitea:\n    image: gitea/gitea:1.21\n    environment:\n      - GITEA__server__DOMAIN=gitea.example.com\n      - GITEA__server__ROOT_URL=https://gitea.example.com\n      # Add custom settings\n    volumes:\n      - /custom/path/gitea:/data\n```\n\n### Webhooks Integration\n\nConfigure webhooks for automated workflows:\n\n```\nimport provisioning.gitea as gitea\n\n_webhook = gitea.GiteaWebhook {\n    url = "https://provisioning.example.com/api/webhooks/gitea"\n    events = ["push", "pull_request", "release"]\n    secret = "webhook-secret"\n}\n```\n\n### Batch Extension Publishing\n\n```\n# Publish all taskservs with same version\nprovisioning gitea extension publish-batch \\n    ./extensions/taskservs \\n    1.0.0 \\n    --extension-type taskserv\n```\n\n---\n\n## References\n\n- **Gitea API Documentation**: <https://docs.gitea.com/api/>\n- **Nickel Schema**: `/Users/Akasha/project-provisioning/provisioning/schemas/gitea.ncl`\n- **API Client**: `/Users/Akasha/project-provisioning/provisioning/core/nulib/lib_provisioning/gitea/api_client.nu`\n- **Workspace Git**: `/Users/Akasha/project-provisioning/provisioning/core/nulib/lib_provisioning/gitea/workspace_git.nu`\n- **Locking**: `/Users/Akasha/project-provisioning/provisioning/core/nulib/lib_provisioning/gitea/locking.nu`\n\n---\n\n**Version:** 1.0.0\n**Maintained By:** Provisioning Team\n**Last Updated:** 2025-10-06
