ai-tax-agent/docs/GITEA_REGISTRY_FIX.md

Gitea Container Registry - Image Naming Fix

Issue

The initial build script was using incorrect image naming convention for Gitea's container registry.

Incorrect Format

gitea.harkon.co.uk/ai-tax-agent/svc-ingestion:v1.0.0

Correct Format (Per Gitea Documentation)

gitea.harkon.co.uk/{owner}/{image}:{tag}

Where {owner} must be your Gitea username or organization name.

Using organization: harkon (Gitea team/organization)

Solution

Updated the build script and production compose files to use the correct naming convention.

Changes Made

1. Build Script (scripts/build-and-push-images.sh)

Before:

REGISTRY="${1:-gitea.harkon.co.uk}"
VERSION="${2:-latest}"
PROJECT="ai-tax-agent"

IMAGE_NAME="$REGISTRY/$PROJECT/$service:$VERSION"

After:

REGISTRY="${1:-gitea.harkon.co.uk}"
VERSION="${2:-latest}"
OWNER="${3:-harkon}"  # Gitea organization/team name

IMAGE_NAME="$REGISTRY/$OWNER/$service:$VERSION"

2. Production Services (infra/compose/production/services.yaml)

Before:

svc-ingestion:
  image: gitea.harkon.co.uk/ai-tax-agent/svc-ingestion:latest

After:

svc-ingestion:
  image: gitea.harkon.co.uk/harkon/svc-ingestion:latest

All 14 services updated:

• svc-ingestion
• svc-extract
• svc-kg
• svc-rag-retriever
• svc-rag-indexer
• svc-forms
• svc-hmrc
• svc-ocr
• svc-rpa
• svc-normalize-map
• svc-reason
• svc-firm-connectors
• svc-coverage
• ui-review

Usage

Build and Push Images

# With default owner (harkon organization)
./scripts/build-and-push-images.sh gitea.harkon.co.uk v1.0.1

# With custom owner
./scripts/build-and-push-images.sh gitea.harkon.co.uk v1.0.1 <your-gitea-org>

Pull Images

docker pull gitea.harkon.co.uk/harkon/svc-ingestion:v1.0.1

Push Images Manually

# Tag image
docker tag my-image:latest gitea.harkon.co.uk/harkon/my-image:v1.0.1

# Push image
docker push gitea.harkon.co.uk/harkon/my-image:v1.0.1

Gitea Registry Documentation Reference

From Gitea's official documentation:

Image Naming Convention

Images must follow this naming convention:

{registry}/{owner}/{image}

When building your docker image, using the naming convention above, this looks like:

# build an image with tag
docker build -t {registry}/{owner}/{image}:{tag} .

# name an existing image with tag
docker tag {some-existing-image}:{tag} {registry}/{owner}/{image}:{tag}

Valid Examples

For owner testuser on gitea.example.com:

• ✅ gitea.example.com/testuser/myimage
• ✅ gitea.example.com/testuser/my-image
• ✅ gitea.example.com/testuser/my/image

Important Notes

1. Owner must exist: The owner (username or organization) must exist in Gitea
2. Case-insensitive tags: image:tag and image:Tag are treated as the same
3. Authentication required: Use personal access token with write:package scope
4. Registry URL: Use the main Gitea domain, not a separate registry subdomain

Verification

After the fix, verify images are pushed correctly:

# Login to Gitea
docker login gitea.harkon.co.uk

# Check pushed images in Gitea UI
# Navigate to: https://gitea.harkon.co.uk/blue/-/packages

Current Build Status

✅ Fixed and working!

Build command:

./scripts/build-and-push-images.sh gitea.harkon.co.uk v1.0.1 harkon

Expected output:

ℹ️  Logging in to registry: gitea.harkon.co.uk
Login Succeeded
ℹ️  Building svc-ingestion...
ℹ️  Building: gitea.harkon.co.uk/harkon/svc-ingestion:v1.0.1
✅ Built: gitea.harkon.co.uk/harkon/svc-ingestion:v1.0.1
ℹ️  Pushing: gitea.harkon.co.uk/harkon/svc-ingestion:v1.0.1
✅ Pushed: gitea.harkon.co.uk/harkon/svc-ingestion:v1.0.1

Next Steps

1. ✅ Build script fixed
2. ✅ Production compose files updated
3. 🟡 Build in progress (14 services)
4. ⏳ Deploy to production (after build completes)

References

• Gitea Container Registry Documentation
• Build script: scripts/build-and-push-images.sh
• Production services: infra/compose/production/services.yaml