Gitea Integration

M3 Forge integrates with Gitea  for self-hosted Git repository management. This enables version control for workflows, prompts, and configurations.

Quick Start

# Create network (if not exists)
docker network create --driver=bridge marie-network
 
# Start Gitea
docker compose --env-file .env -f docker/docker-compose.gitea.yml up -d

Docker Compose Configuration

M3 Forge includes a ready-to-use Gitea compose file at docker/docker-compose.gitea.yml.

Environment Variables

Add these to your .env file:

# Gitea server configuration
GITEA_HTTP_PORT=3001          # Web UI port
GITEA_SSH_PORT=2222           # SSH port
GITEA_DOMAIN=localhost        # Server domain
GITEA_ROOT_URL=http://localhost:3001
GITEA_DB_TYPE=sqlite3         # Use 'postgres' for production
GITEA_LOG_LEVEL=info
GITEA_INSTALL_LOCK=false      # Set to true after initial setup
GITEA_DISABLE_REGISTRATION=false

Commands

Using PostgreSQL

For production deployments, use PostgreSQL instead of SQLite.

# If using Marie-AI PostgreSQL
docker exec marie-psql-server psql -U postgres -c "CREATE DATABASE gitea"
 
# Or standalone PostgreSQL
docker exec postgres psql -U postgres -c "CREATE DATABASE gitea"

GITEA_DB_TYPE=postgres
POSTGRES_HOST=host.docker.internal  # or your PostgreSQL host
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your-password
GITEA_DB_NAME=gitea

Automated Setup

Skip the web wizard by using CLI commands.

Create Admin User

docker exec -u git marie-gitea gitea admin user create \
  --admin \
  --username marie \
  --password your-secure-password \
  --email marie@marie.local \
  --must-change-password=false

After creating the admin, set GITEA_INSTALL_LOCK=true in your .env.

Create OAuth2 App via API

curl -s -u "marie:your-password" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "name": "marie-studio",
    "redirect_uris": ["http://localhost:3000/api/auth/gitea/connect/callback"],
    "confidential_client": true
  }' \
  "http://localhost:3001/api/v1/user/applications/oauth2"

The response contains client_id and client_secret. Save these for Studio configuration.

Using Existing Gitea

If you already have Gitea running elsewhere:

1. Create an OAuth2 application in your Gitea instance
2. Set the redirect URI to: http://YOUR_STUDIO_URL/api/auth/gitea/connect/callback
3. Configure Studio with your Gitea URL and OAuth credentials

Network Configuration

Same Docker Network

When running Gitea alongside M3 Forge on the same Docker network:

# Studio accesses Gitea via container name
GITEA_INTERNAL_URL=http://marie-gitea:3000
 
# Browser accesses Gitea via published port
GITEA_ROOT_URL=http://localhost:3001

External Gitea

When Gitea runs on a different host:

# Both Studio and browser use the same URL
GITEA_URL=https://git.example.com

Troubleshooting

Gitea won’t start

Check if the port is already in use:

lsof -i :3001

View Gitea logs:

docker logs marie-gitea

OAuth redirect fails

Verify the redirect URI matches exactly:

• Configured in Gitea: http://localhost:3000/api/auth/gitea/connect/callback
• Studio callback path: /api/auth/gitea/connect/callback

Database connection errors

If using PostgreSQL, verify:

1. Database gitea exists
2. PostgreSQL is reachable from the Gitea container
3. Credentials are correct

# Test connection from Gitea container
docker exec marie-gitea psql -h host.docker.internal -U postgres -d gitea -c "SELECT 1"

Health check fails

Gitea needs time for initial setup and migrations. The default start_period is 120 seconds. Check status:

docker inspect marie-gitea --format='{{.State.Health.Status}}'

Reference

Ports

Volumes

OAuth Callback Path

The correct callback path for M3 Forge is:

/api/auth/gitea/connect/callback

Full URL examples:

• Local development: http://localhost:3000/api/auth/gitea/connect/callback
• Production: https://studio.example.com/api/auth/gitea/connect/callback