From 6d280f6773d4e3c9544bfc7a825cf05a4711124a Mon Sep 17 00:00:00 2001 From: 0xWheatyz Date: Wed, 4 Mar 2026 02:59:05 +0000 Subject: [PATCH] docs: add comprehensive Gitea container registry guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add detailed documentation for using Gitea's built-in container registry with Gitea Actions for automated Docker image builds. New documentation: - GITEA_CONTAINER_REGISTRY.md: Complete guide covering: - Enabling and configuring container registry - Authentication for Docker CLI and CI/CD - Automated builds with Gitea Actions workflows - Using registry images in Kubernetes deployments - FluxCD integration with Gitea registry - Troubleshooting common issues - Best practices for tagging and security Updates to CLAUDE.md: - Added reference to GITEA_CONTAINER_REGISTRY.md in repo structure - Added Container Registry section to Gitea deployment docs - Included quick reference for registry login and usage This enables complete GitOps CI/CD pipelines with Gitea similar to GitLab Container Registry functionality. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- CLAUDE.md | 20 ++ GITEA_CONTAINER_REGISTRY.md | 442 ++++++++++++++++++++++++++++++++++++ 2 files changed, 462 insertions(+) create mode 100644 GITEA_CONTAINER_REGISTRY.md diff --git a/CLAUDE.md b/CLAUDE.md index 1493121..6cf60c1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -301,6 +301,7 @@ This is a Talos Kubernetes cluster management repository with the following stru - **install-local-path-storage.sh** - Install storage provisioner - **diagnose-storage.sh** - Storage diagnostic tool - **APP_DEPLOYMENT.md** - Comprehensive guide for deploying applications +- **GITEA_CONTAINER_REGISTRY.md** - Guide for using Gitea container registry and CI/CD - **CLAUDE.md** - This file - development guidance ### Cluster Configuration @@ -465,3 +466,22 @@ jobs: - `ubuntu-22.04` → `docker://node:20-bullseye` You can customize these labels in `testing1/first-cluster/apps/gitea/runner-deployment.yaml` under `GITEA_RUNNER_LABELS`. + +**Container Registry:** + +Gitea includes a built-in container registry (via Packages feature) for storing Docker images. This enables complete CI/CD pipelines similar to GitLab. + +Using the container registry: +```bash +# Log in to Gitea registry +docker login 10.0.1.10 -u your-username + +# Push images +docker tag myapp:latest 10.0.1.10/username/repo:latest +docker push 10.0.1.10/username/repo:latest + +# Pull images +docker pull 10.0.1.10/username/repo:latest +``` + +For complete container registry setup, CI/CD workflows, and Kubernetes integration, see **[GITEA_CONTAINER_REGISTRY.md](GITEA_CONTAINER_REGISTRY.md)**. diff --git a/GITEA_CONTAINER_REGISTRY.md b/GITEA_CONTAINER_REGISTRY.md new file mode 100644 index 0000000..aff331c --- /dev/null +++ b/GITEA_CONTAINER_REGISTRY.md @@ -0,0 +1,442 @@ +# Gitea Container Registry Guide + +This guide explains how to use the Gitea Container Registry with Gitea Actions for automated Docker image builds and deployments. + +## Overview + +Gitea includes a built-in container registry (via the Packages feature) that supports Docker/OCI images. Combined with Gitea Actions, this provides a complete CI/CD pipeline similar to GitLab CI/CD with Container Registry. + +## Enabling Container Registry + +### Check if Enabled + +1. Access Gitea UI at `http://10.0.1.10` +2. Go to any repository +3. Look for "Packages" tab +4. If visible, registry is enabled + +### Enable via Configuration (if needed) + +If the container registry is not enabled, update Gitea configuration: + +1. Access the Gitea pod: + ```bash + kubectl exec -it -n gitea deployment/gitea -- sh + ``` + +2. Edit `app.ini`: + ```bash + vi /data/gitea/conf/app.ini + ``` + +3. Add/update the following section: + ```ini + [packages] + ENABLED = true + ``` + +4. Restart Gitea: + ```bash + kubectl rollout restart deployment/gitea -n gitea + ``` + +## Using the Container Registry + +### Authentication + +#### For Developers (Docker CLI) + +```bash +# Log in to registry +docker login 10.0.1.10 -u your-username + +# When prompted, enter your Gitea password or personal access token +``` + +#### For CI/CD (Gitea Actions) + +Create a personal access token: + +1. Gitea UI → User Settings → Applications → Access Tokens +2. Click "Generate New Token" +3. Name: "CI/CD Container Registry" +4. Select scopes: + - `write:package` + - `read:package` +5. Generate and copy the token + +Add as repository secret: + +1. Repository → Settings → Secrets +2. Add secret: `GITEA_TOKEN` = `` + +### Push Images Manually + +```bash +# Log in +docker login 10.0.1.10 -u your-username + +# Tag your image +docker tag my-app:latest 10.0.1.10/your-username/my-repo:latest + +# Push to registry +docker push 10.0.1.10/your-username/my-repo:latest +``` + +### Pull Images + +```bash +# Public images (no auth needed) +docker pull 10.0.1.10/username/repo:tag + +# Private images (auth required) +docker login 10.0.1.10 -u your-username +docker pull 10.0.1.10/username/repo:tag +``` + +## Automated Builds with Gitea Actions + +### Basic Workflow + +Create `.gitea/workflows/build.yaml`: + +```yaml +name: Build and Push Docker Image + +on: + push: + branches: + - main + tags: + - '*' + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set image tags + id: tags + run: | + REGISTRY="10.0.1.10" + IMAGE="${REGISTRY}/${{ gitea.repository }}" + echo "IMAGE_TAG=${IMAGE}:${{ gitea.sha_short }}" >> $GITHUB_OUTPUT + echo "IMAGE_LATEST=${IMAGE}:latest" >> $GITHUB_OUTPUT + + - name: Log in to registry + run: | + echo "${{ secrets.GITEA_TOKEN }}" | docker login 10.0.1.10 -u "${{ gitea.actor }}" --password-stdin + + - name: Build and push + run: | + docker build -t ${{ steps.tags.outputs.IMAGE_TAG }} -t ${{ steps.tags.outputs.IMAGE_LATEST }} . + docker push ${{ steps.tags.outputs.IMAGE_TAG }} + docker push ${{ steps.tags.outputs.IMAGE_LATEST }} +``` + +### Advanced Workflow with Multi-stage Build + +```yaml +name: Build Multi-platform Image + +on: + push: + branches: [main] + tags: ['v*'] + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Log in to registry + run: | + echo "${{ secrets.GITEA_TOKEN }}" | docker login 10.0.1.10 -u "${{ gitea.actor }}" --password-stdin + + - name: Build and push + run: | + IMAGE="10.0.1.10/${{ gitea.repository }}" + docker buildx build \ + --platform linux/amd64,linux/arm64 \ + -t ${IMAGE}:${{ gitea.sha_short }} \ + -t ${IMAGE}:latest \ + --push . +``` + +## Using Images in Kubernetes + +### Pull from Gitea Registry in Deployments + +#### Public Images (No Authentication) + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: my-app +spec: + template: + spec: + containers: + - name: app + image: 10.0.1.10/username/my-app:latest +``` + +#### Private Images (With Authentication) + +1. Create a Docker registry secret: + ```bash + kubectl create secret docker-registry gitea-registry \ + --docker-server=10.0.1.10 \ + --docker-username=your-username \ + --docker-password=your-token \ + -n your-namespace + ``` + +2. Reference in deployment: + ```yaml + apiVersion: apps/v1 + kind: Deployment + metadata: + name: my-app + spec: + template: + spec: + imagePullSecrets: + - name: gitea-registry + containers: + - name: app + image: 10.0.1.10/username/my-app:latest + ``` + +### GitOps Deployment with FluxCD + +FluxCD can monitor and deploy images from Gitea registry: + +```yaml +# image-repository.yaml +apiVersion: image.toolkit.fluxcd.io/v1beta2 +kind: ImageRepository +metadata: + name: my-app + namespace: flux-system +spec: + image: 10.0.1.10/username/my-app + interval: 1m + secretRef: + name: gitea-registry +--- +# image-policy.yaml +apiVersion: image.toolkit.fluxcd.io/v1beta2 +kind: ImagePolicy +metadata: + name: my-app + namespace: flux-system +spec: + imageRepositoryRef: + name: my-app + policy: + semver: + range: '>=1.0.0' +``` + +## Registry Management + +### View Packages + +1. Go to repository in Gitea UI +2. Click "Packages" tab +3. See all published container images + +### Delete Images + +1. Repository → Packages +2. Click on the package +3. Click on specific version +4. Click "Delete" + +### View Package Details + +Each package shows: +- Image tags +- Size +- Published date +- Pull commands + +## Troubleshooting + +### Cannot Push: 404 Not Found + +**Issue**: Registry not enabled + +**Solution**: +```bash +kubectl exec -it -n gitea deployment/gitea -- sh +vi /data/gitea/conf/app.ini +# Add: [packages] ENABLED = true +kubectl rollout restart deployment/gitea -n gitea +``` + +### Cannot Push: 401 Unauthorized + +**Issue**: Invalid credentials + +**Solutions**: +- Verify username and password/token +- Regenerate personal access token +- Check token scopes include `write:package` + +### Workflow Cannot Push + +**Issue**: Missing or invalid `GITEA_TOKEN` secret + +**Solution**: +1. Generate personal access token with `write:package` scope +2. Add as repository secret named `GITEA_TOKEN` +3. Re-run workflow + +### Image Not Showing in Packages Tab + +**Issue**: Push succeeded but package not visible + +**Solutions**: +- Refresh the page +- Check if logged in as correct user +- Verify repository permissions +- Check Gitea logs: `kubectl logs -n gitea deployment/gitea` + +### Kubernetes Cannot Pull Image + +**Issue**: ImagePullBackOff error + +**Solutions**: +1. Verify image name and tag are correct +2. For private repos, create imagePullSecret: + ```bash + kubectl create secret docker-registry gitea-registry \ + --docker-server=10.0.1.10 \ + --docker-username=your-user \ + --docker-password=your-token \ + -n namespace + ``` +3. Add imagePullSecrets to pod spec + +### Registry Running Out of Space + +**Issue**: Gitea PVC full + +**Solutions**: +1. Check PVC usage: + ```bash + kubectl exec -n gitea deployment/gitea -- df -h /data + ``` + +2. Expand PVC: + ```bash + kubectl edit pvc gitea-data -n gitea + # Increase spec.resources.requests.storage + ``` + +3. Clean up old images via Gitea UI + +## Best Practices + +### Tagging Strategy + +- **Latest tag**: Always update `latest` on main branch builds +- **Semantic versions**: Use tags like `v1.2.3` for releases +- **Commit SHA**: Tag with short SHA for traceability +- **Branch names**: Tag feature branches for testing + +### Security + +- Use personal access tokens instead of passwords +- Limit token scopes to minimum required +- Rotate tokens periodically +- Use imagePullSecrets for private images in Kubernetes + +### Image Size Optimization + +- Use multi-stage builds +- Use Alpine-based images where possible +- Clean up package manager caches +- Use .dockerignore to exclude unnecessary files + +### CI/CD Pipeline + +1. Build on every commit to main +2. Tag with semantic version on git tags +3. Run tests before building +4. Scan images for vulnerabilities +5. Deploy automatically via FluxCD + +## Example: Complete CI/CD Pipeline + +```yaml +name: Complete CI/CD Pipeline + +on: + push: + branches: [main] + tags: ['v*'] + pull_request: + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Run tests + run: | + pip install -r requirements.txt + pytest + + build: + needs: test + if: github.event_name == 'push' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Set image tags + id: tags + run: | + IMAGE="10.0.1.10/${{ gitea.repository }}" + if [[ "${{ gitea.ref }}" == refs/tags/* ]]; then + VERSION=${GITHUB_REF#refs/tags/} + echo "IMAGE_TAG=${IMAGE}:${VERSION}" >> $GITHUB_OUTPUT + else + echo "IMAGE_TAG=${IMAGE}:${{ gitea.sha_short }}" >> $GITHUB_OUTPUT + fi + echo "IMAGE_LATEST=${IMAGE}:latest" >> $GITHUB_OUTPUT + + - name: Build and push + run: | + echo "${{ secrets.GITEA_TOKEN }}" | docker login 10.0.1.10 -u "${{ gitea.actor }}" --password-stdin + docker build -t ${{ steps.tags.outputs.IMAGE_TAG }} -t ${{ steps.tags.outputs.IMAGE_LATEST }} . + docker push ${{ steps.tags.outputs.IMAGE_TAG }} + docker push ${{ steps.tags.outputs.IMAGE_LATEST }} + + - name: Update Kubernetes manifest + if: github.ref == 'refs/heads/main' + run: | + # Update image tag in Kubernetes manifest + sed -i "s|image:.*|image: ${{ steps.tags.outputs.IMAGE_TAG }}|" k8s/deployment.yaml + git config user.name "Gitea Actions" + git config user.email "actions@gitea.local" + git add k8s/deployment.yaml + git commit -m "chore: update image to ${{ steps.tags.outputs.IMAGE_TAG }}" + git push +``` + +## References + +- [Gitea Packages Documentation](https://docs.gitea.com/usage/packages/overview) +- [Gitea Actions Documentation](https://docs.gitea.com/usage/actions/overview) +- [Docker Registry HTTP API](https://docs.docker.com/registry/spec/api/)