unitforge/docs/CI-CD-SECRETS.md

CI/CD Secrets Setup Guide

This guide explains how to configure the required secrets for UnitForge's Gitea CI/CD workflows.

Overview

UnitForge's CI/CD pipelines require several secrets to function properly:

• Container Registry credentials for pushing multi-arch images
• PyPI token for automated package publishing
• GitHub token for release management
• Optional notification and deployment secrets

Required Secrets

1. Container Registry Authentication

Required for: All build workflows (build-container.yml, release.yml, nightly.yml)

CONTAINER_REGISTRY_USERNAME=your-registry-username
CONTAINER_REGISTRY_PASSWORD=your-registry-password-or-token

Docker Hub Example:

CONTAINER_REGISTRY_USERNAME=dockerhubusername
CONTAINER_REGISTRY_PASSWORD=dckr_pat_xxxxxxxxxxxxxxxxxxxxxxxxxx

GitLab Container Registry Example:

CONTAINER_REGISTRY_USERNAME=gitlab-ci-token
CONTAINER_REGISTRY_PASSWORD=glpat-xxxxxxxxxxxxxxxxxxxx

GitHub Container Registry Example:

CONTAINER_REGISTRY_USERNAME=github-username
CONTAINER_REGISTRY_PASSWORD=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

2. PyPI Publishing Token

Required for: Release workflow (release.yml) - stable releases only

PYPI_API_TOKEN=pypi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

How to get PyPI token:

1. Go to PyPI Account Settings
2. Click "Add API token"
3. Set scope to "Entire account" or specific project
4. Copy the token (starts with pypi-)

3. GitHub Token (Optional)

Required for: GitHub releases and integration

GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

How to get GitHub token:

1. Go to GitHub Settings > Developer settings > Personal access tokens
2. Click "Generate new token (classic)"
3. Select scopes: repo, write:packages
4. Copy the token (starts with ghp_)

Setting Up Secrets in Gitea

Repository Secrets

1. Navigate to your repository in Gitea
2. Go to Settings > Secrets and Variables > Actions
3. Click New repository secret
4. Add each required secret:

Name: CONTAINER_REGISTRY_USERNAME
Value: your-registry-username

Name: CONTAINER_REGISTRY_PASSWORD
Value: your-registry-password

Name: PYPI_API_TOKEN
Value: pypi-your-token-here

Name: GITHUB_TOKEN
Value: ghp_your-token-here

Organization Secrets (Optional)

For multiple repositories, set up organization-level secrets:

1. Go to your Gitea organization
2. Navigate to Settings > Secrets and Variables > Actions
3. Add secrets that will be shared across repositories

Optional Secrets

Notification Services

# Slack notifications
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX

# Discord notifications
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/000000000000000000/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Email notifications
EMAIL_NOTIFICATION_ADDRESS=ci-notifications@yourdomain.com

Deployment Secrets

# SSH key for server deployments (base64 encoded)
DEPLOYMENT_SSH_KEY=LS0tLS1CRUdJTi...

# Kubernetes service account token
KUBERNETES_TOKEN=eyJhbGciOiJSUzI1NiIsImtpZCI6Ii...

# Production API key
PRODUCTION_API_KEY=prod-api-key-xxxxxxxxxxxx

Security Scanning

# Enhanced security scanning (Snyk, etc.)
SECURITY_SCAN_TOKEN=your-security-service-token

Environment Configuration

Update your .env file with registry and configuration details:

# Container Registry Configuration
CONTAINER_REGISTRY_URL=https://your-registry.example.com/your-namespace/unitforge
CONTAINER_TAG=latest

# Build Configuration
DOCKER_PLATFORMS=linux/amd64,linux/arm64
BUILDX_CACHE_FROM=type=gha
BUILDX_CACHE_TO=type=gha,mode=max

Workflow-Specific Requirements

Pull Request Workflow (pr-check.yml)

• No secrets required - Only builds and tests, no pushing

Build Container Workflow (build-container.yml)

• CONTAINER_REGISTRY_USERNAME ✅ Required
• CONTAINER_REGISTRY_PASSWORD ✅ Required

Release Workflow (release.yml)

• CONTAINER_REGISTRY_USERNAME ✅ Required
• CONTAINER_REGISTRY_PASSWORD ✅ Required
• PYPI_API_TOKEN ✅ Required (stable releases)
• GITHUB_TOKEN ⚠️ Optional (for GitHub releases)

Nightly Workflow (nightly.yml)

• CONTAINER_REGISTRY_USERNAME ✅ Required
• CONTAINER_REGISTRY_PASSWORD ✅ Required

Security Best Practices

1. Secret Rotation

• Rotate secrets regularly (quarterly recommended)
• Use tokens with limited scope and expiration
• Monitor token usage in registry/service dashboards

2. Principle of Least Privilege

• Grant minimum required permissions
• Use service-specific tokens where possible
• Avoid using personal access tokens in production

3. Token Security

• Never commit secrets to version control
• Use environment-specific secrets
• Enable audit logging where available

4. Backup and Recovery

• Document secret sources and renewal procedures
• Maintain secure backup of critical tokens
• Test secret rotation procedures

Troubleshooting

Common Issues

Authentication Failed:

Error: unauthorized: authentication required

• Verify CONTAINER_REGISTRY_USERNAME and CONTAINER_REGISTRY_PASSWORD
• Check token permissions and expiration
• Ensure registry URL matches token scope

PyPI Publishing Failed:

Error: 403 Forbidden

• Verify PYPI_API_TOKEN format (should start with pypi-)
• Check token scope (project vs account-wide)
• Ensure package name matches PyPI project

GitHub Release Failed:

Error: Resource not accessible by integration

• Verify GITHUB_TOKEN permissions include repo scope
• Check if token is expired
• Ensure repository access is granted

Testing Secrets

Test your secrets locally:

# Test container registry login
echo "$CONTAINER_REGISTRY_PASSWORD" | docker login "$CONTAINER_REGISTRY_URL" -u "$CONTAINER_REGISTRY_USERNAME" --password-stdin

# Test PyPI token (dry run)
twine check dist/* --repository testpypi

# Test GitHub API access
curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user

Monitoring and Alerts

Registry Usage

• Monitor container registry storage and bandwidth
• Set up alerts for failed pushes
• Track image pull statistics

Build Metrics

• Monitor workflow success rates
• Track build duration trends
• Alert on consecutive failures

Security Monitoring

• Enable security scanning alerts
• Monitor vulnerability trends
• Set up notifications for critical issues

Support

For additional help:

• Check Gitea Actions Documentation
• Review workflow logs in Gitea Actions UI
• Open an issue in the UnitForge repository
• Consult your container registry documentation

Quick Reference

Secret	Required For	Format	Purpose
CONTAINER_REGISTRY_USERNAME	All builds	Username	Registry authentication
CONTAINER_REGISTRY_PASSWORD	All builds	Token/Password	Registry authentication
PYPI_API_TOKEN	Releases	pypi-...	Package publishing
GITHUB_TOKEN	Releases	ghp_...	GitHub integration
SLACK_WEBHOOK_URL	Notifications	HTTPS URL	Slack alerts
DEPLOYMENT_SSH_KEY	Deployments	Base64 SSH key	Server access

---

Last updated: December 2024 For the latest information, see the CI/CD Workflows README