SPARC/CONTAINER_REGISTRY.md

Container Registry and CI/CD Setup

This document explains how to build and push Docker images using Gitea Actions and the Gitea Container Registry.

Overview

The SPARC project uses Gitea Actions (GitHub Actions-compatible) to automatically build and push Docker images to the Gitea Container Registry whenever code is pushed to the repository.

Workflow Configuration

The workflow is defined in .gitea/workflows/build.yaml and automatically:

• Builds the Docker image from the Dockerfile
• Tags the image appropriately based on the git ref (branch/tag)
• Pushes to the Gitea Container Registry at 10.0.1.10

Triggers

The workflow runs on:

• Push to main branch: Builds and tags with commit SHA + latest
• Push of tags: Builds and tags with the tag name + latest
• Manual dispatch: Can be triggered manually from Gitea UI

Image Naming

Images are pushed to: 10.0.1.10/0xwheatyz/sparc:<tag>

• Main branch commits: 10.0.1.10/0xwheatyz/sparc:<sha> and 10.0.1.10/0xwheatyz/sparc:latest
• Tags: 10.0.1.10/0xwheatyz/sparc:<tag-name> and 10.0.1.10/0xwheatyz/sparc:latest
• Other branches: 10.0.1.10/0xwheatyz/sparc:<branch-name>

Prerequisites

1. Enable Container Registry in Gitea

The Gitea instance must have the Container Registry (Packages) feature enabled:

1. Access Gitea as administrator
2. Go to Site Administration > Configuration
3. Find "Packages" section
4. Ensure packages/container registry is enabled

2. Create Personal Access Token

The workflow needs a personal access token with package write permissions:

1. In Gitea UI, click your profile → Settings
2. Go to Applications → Manage Access Tokens
3. Click "Generate New Token"
4. Give it a descriptive name (e.g., "Actions Container Registry")
5. Select scopes:
   • write:package (required)
   • read:package (required)
6. Click "Generate Token"
7. Copy the token immediately (you won't see it again)

3. Add Token as Repository Secret

1. Go to your repository in Gitea
2. Click Settings → Secrets
3. Click "Add Secret"
4. Name: GITEA_TOKEN
5. Value: Paste the personal access token
6. Click "Add Secret"

Usage

Automatic Builds

Once configured, the workflow runs automatically:

# Push to main branch - triggers build
git add .
git commit -m "feat: add new feature"
git push origin main

# Create and push a tag - triggers build with tag
git tag v1.0.0
git push origin v1.0.0

Manual Builds

You can also trigger builds manually:

1. Go to repository → Actions
2. Click on "Build and Push Docker Image" workflow
3. Click "Run workflow"
4. Select the branch
5. Click "Run workflow"

Monitor Build Progress

1. Go to repository → Actions
2. Click on the running workflow
3. View logs for each step

Pulling Images

Once built, images can be pulled from the registry:

# Log in to registry
docker login 10.0.1.10 -u your-username

# Pull the latest image
docker pull 10.0.1.10/0xwheatyz/sparc:latest

# Pull a specific tag
docker pull 10.0.1.10/0xwheatyz/sparc:v1.0.0

# Pull a specific commit
docker pull 10.0.1.10/0xwheatyz/sparc:abc1234

Troubleshooting

Workflow Fails at Login Step

Error: Error response from daemon: login attempt to http://10.0.1.10/v2/ failed with status: 404 Not Found

Solution: Container registry is not enabled in Gitea. Contact administrator to enable packages feature.

Workflow Fails with 401 Unauthorized

Error: unauthorized: authentication required

Solutions:

1. Verify GITEA_TOKEN secret exists and is correct
2. Verify token has write:package and read:package scopes
3. Regenerate token if it has expired

Workflow Fails at Push Step

Error: denied: permission denied

Solutions:

1. Ensure your user account has write access to the repository
2. Verify the token has the correct permissions
3. Check if the repository owner matches the registry path

Image Not Appearing in Packages

Check:

1. Go to repository → Packages tab
2. If no packages appear, check workflow logs for errors
3. Verify the image was successfully pushed (check workflow output)

Advanced Configuration

Using a Different Registry

To push to a different container registry (e.g., Docker Hub, GHCR):

1. Update the REGISTRY variable in .gitea/workflows/build.yaml
2. Update the login step with appropriate credentials
3. Add registry credentials as secrets

Building Multi-platform Images

To build for multiple architectures:

- name: Build Docker image
  run: |
    docker buildx build \
      --platform linux/amd64,linux/arm64 \
      -t ${{ steps.tags.outputs.IMAGE_TAG }} \
      --push .    

Adding Build Arguments

To pass build arguments:

- name: Build Docker image
  run: |
    docker build \
      --build-arg VERSION=${{ gitea.sha_short }} \
      -t ${{ steps.tags.outputs.IMAGE_TAG }} .    

References

• Gitea Actions Documentation
• Gitea Packages Documentation
• GitHub Actions Syntax (Gitea Actions compatible)