scripts/local-gitea/
├── configs/
│   ├── seed-data.json          # Defines Gitea resources to create
│   └── test-scenarios.json     # Defines integration test scenarios
├── seeder/
│   ├── main.go                 # Go-based seeder implementation
│   └── go.mod                  # Seeder dependencies
├── test-runner/
│   ├── main.go                 # Go-based test runner implementation
│   └── go.mod                  # Test runner dependencies
├── start.sh                   # Main entry point
├── run.sh                     # Gitea container startup script
├── get_credentials.sh         # Setup admin user and credentials
├── seed.sh                    # Seeding script using Go seeder
├── integration-tests.sh       # Test script using Go test runner
└── README.md                  # This file

Quick Start

Running All Tests

# Run the Gitea integration tests
./start.sh

# Or with custom parameters
./start.sh true false latest

Script Arguments

Quick Reference

Script	Arguments	Purpose
`start.sh`	7 optional args	Main entry point - runs entire test suite
`seed.sh`	3 optional args	Seeds Gitea with test data
`integration-tests.sh`	3 optional args	Runs integration tests only
`run.sh`	4 optional args	Starts Gitea container (internal)

`start.sh` Arguments

The main entry point script accepts up to 7 optional arguments. All arguments have sensible defaults if not provided.

Usage:

./start.sh [STOP_GITEA_WHEN_FINISHED] [PERSIST_GITEA_LOCALLY] [GITEA_IMAGE_TAG] [GITEA_HOME] [GITEA_HOST] [GITEA_URL] [LOCAL_GITEA_GHORG_DIR]

Argument	Default	Description
`STOP_GITEA_WHEN_FINISHED`	`'true'`	Whether to stop and remove the Gitea container after tests complete. Set to `'false'` to keep Gitea running for debugging.
`PERSIST_GITEA_LOCALLY`	`'false'`	Whether to persist Gitea data locally across container restarts. Set to `'true'` to keep data between runs.
`GITEA_IMAGE_TAG`	`'latest'`	Gitea Docker image tag to use. Can be specific version like `'1.20.0'` or `'latest'`.
`GITEA_HOME`	`"$HOME/ghorg/local-gitea-data-${GITEA_IMAGE_TAG}"`	Directory where Gitea stores persistent data on the host machine.
`GITEA_HOST`	`'gitea.example.com'`	Hostname for the Gitea instance. Used for container networking and /etc/hosts entries.
`GITEA_URL`	`'http://gitea.example.com:3000'`	Full URL to access the Gitea instance. Used by ghorg and the test tools.
`LOCAL_GITEA_GHORG_DIR`	`"${HOME}/ghorg"`	Local directory where ghorg will clone repositories and store its working files.

Examples:

# Default behavior - run tests and clean up
./start.sh

# Keep Gitea running after tests for debugging
./start.sh false

# Use specific Gitea version and keep it running
./start.sh false false 1.20.0

# Full custom configuration
./start.sh true true latest /tmp/gitea-data gitea.local http://gitea.local:3000 /tmp/ghorg

Common Scenarios:

# Development - keep Gitea running for multiple test iterations
./start.sh false false latest

# CI/CD - use clean environment and cleanup afterwards (default)
./start.sh true false latest

# Testing specific Gitea version
./start.sh true false 1.19.0

# Custom data persistence for repeated testing
./start.sh false true latest /data/gitea-persistent

Individual Component Arguments

`seed.sh` Arguments

Seeds the Gitea instance with test data using the Go-based seeder.

Usage:

./seed.sh [API_TOKEN] [GITEA_URL] [LOCAL_GITEA_GHORG_DIR]

Argument	Default	Description
`API_TOKEN`	From `${LOCAL_GITEA_GHORG_DIR}/gitea_token`	Gitea API token for authentication
`GITEA_URL`	`"http://gitea.example.com:3000"`	Full URL to the Gitea instance
`LOCAL_GITEA_GHORG_DIR`	`"${HOME}/ghorg"`	Directory where ghorg stores its configuration and temp files

Example:

# Use defaults
./seed.sh

# Custom parameters
./seed.sh "my-token" "http://gitea.local:3000" "/tmp/ghorg"

`integration-tests.sh` Arguments

Runs the integration tests using the Go-based test runner.

Usage:

./integration-tests.sh [LOCAL_GITEA_GHORG_DIR] [API_TOKEN] [GITEA_URL]

Argument	Default	Description
`LOCAL_GITEA_GHORG_DIR`	`"${HOME}/ghorg"`	Directory where ghorg will clone repositories for testing
`API_TOKEN`	From `${LOCAL_GITEA_GHORG_DIR}/gitea_token`	Gitea API token for authentication
`GITEA_URL`	`"http://gitea.example.com:3000"`	Full URL to the Gitea instance

Example:

# Use defaults
./integration-tests.sh

# Custom parameters
./integration-tests.sh "/tmp/ghorg" "my-token" "http://gitea.local:3000"

`run.sh` Arguments (Internal)

Starts the Gitea Docker container. Called internally by start.sh.

Usage:

./run.sh [GITEA_IMAGE_TAG] [GITEA_HOME] [GITEA_HOST] [PERSIST_GITEA_LOCALLY]

Argument	Default	Description
`GITEA_IMAGE_TAG`	`"latest"`	Gitea Docker image tag
`GITEA_HOME`	Dynamic	Host directory for Gitea data persistence
`GITEA_HOST`	`"gitea.example.com"`	Container hostname
`PERSIST_GITEA_LOCALLY`	`"false"`	Whether to persist data between container restarts

Go Tool Arguments (Direct Usage)

For advanced usage, you can run the Go tools directly:

Seeder (seeder/gitea-seeder):

./gitea-seeder [flags]
  -config string
        Path to seed data configuration file (default "configs/seed-data.json")
  -token string
        Gitea API token (required)
  -base-url string
        Gitea base URL (required)

Test Runner (test-runner/gitea-test-runner):

./gitea-test-runner [flags]
  -config string
        Path to test scenarios configuration file (default "configs/test-scenarios.json")
  -token string
        Gitea API token (required)
  -base-url string
        Gitea base URL (required)
  -ghorg-dir string
        Ghorg directory path (default "${HOME}/ghorg")
  -test string
        Run specific test by name (optional)
  -list
        List all available tests and exit

Examples:

# List all available test scenarios
./test-runner/gitea-test-runner -list -token="your-token"

# Run specific test
./test-runner/gitea-test-runner -test="all-orgs-basic" -token="your-token" -base-url="http://gitea.example.com:3000"

# Seed with custom config
./seeder/gitea-seeder -config="my-seed-data.json" -token="your-token" -base-url="http://gitea.example.com:3000"

Running Individual Components

# Seed Gitea instance only
./seed.sh "your-token" "http://gitea.example.com:3000" "${HOME}/ghorg"

# Run integration tests only (assumes seeded instance)
./integration-tests.sh "${HOME}/ghorg" "your-token" "http://gitea.example.com:3000"

Configuration

Seed Data Configuration (`configs/seed-data.json`)

Defines the Gitea resources to create during seeding:

{
  "organizations": [
    {
      "name": "My Organization",
      "username": "my-org",
      "description": "My test organization",
      "repositories": [
        {
          "name": "my-repo",
          "initialize_with_readme": true,
          "description": "My test repository"
        }
      ]
    }
  ],
  "users": [
    {
      "username": "testuser",
      "email": "test@example.com",
      "password": "password123",
      "full_name": "Test User",
      "repositories": [...]
    }
  ],
  "root_user": {
    "repositories": [...]
  }
}

Test Scenarios Configuration (`configs/test-scenarios.json`)

Defines the integration test scenarios:

{
  "test_scenarios": [
    {
      "name": "my-test-scenario",
      "description": "Test description",
      "command": "ghorg clone all-orgs --scm=gitea --base-url={{.BaseURL}} --token={{.Token}} --output-dir=test-output",
      "run_twice": true,
      "setup_commands": ["git init {{.GhorgDir}}/test-setup"],
      "verify_commands": ["test -d '{{.GhorgDir}}/test-output'"],
      "expected_structure": [
        "test-output/org1/repo1",
        "test-output/org2/repo2"
      ]
    }
  ]
}

Adding New Seed Data

Edit the configuration: Modify configs/seed-data.json to add new organizations, repositories, or users
Test the changes: Run ./seed.sh to verify the new seed data is created correctly

Example: Adding a New Organization

{
  "name": "New Organization",
  "username": "new-org",
  "description": "Description of the new organization",
  "repositories": [
    {
      "name": "new-repo",
      "initialize_with_readme": true,
      "description": "New repository description"
    }
  ]
}

Adding New Test Scenarios

Manual Configuration

Edit configs/test-scenarios.json
Add a new test scenario object to the test_scenarios array
Test with: ./test-runner/gitea-test-runner -test="your-test-name"

Programmatically

# Build the test runner
cd test-runner && go build -o gitea-test-runner main.go

# List available tests
./gitea-test-runner -list -token="your-token"

# Run a specific test
./gitea-test-runner -test="specific-test-name" -token="your-token" -base-url="http://gitea.example.com:3000"

Template Variables

Both seeder and test runner support template variables:

{{.BaseURL}} - Gitea base URL
{{.Token}} - Gitea API token
{{.GhorgDir}} - Ghorg directory path

Development

Building the Components

# Build seeder
cd seeder && go build -o gitea-seeder main.go

# Build test runner
cd test-runner && go build -o gitea-test-runner main.go

Running Tests in Development

# Run specific test scenario
cd test-runner
go run main.go -test="all-orgs-basic" -token="your-token" -base-url="http://gitea.example.com:3000"

# List all available test scenarios
go run main.go -list -token="your-token"

Troubleshooting

Build Errors

# Ensure Go modules are downloaded
cd seeder && go mod download
cd test-runner && go mod download

Test Failures

# Check Gitea is accessible
curl -I http://gitea.example.com:3000

# Verify seeding completed
./seeder/gitea-seeder -token="your-token" -base-url="http://gitea.example.com:3000"

# Run specific failing test
./test-runner/gitea-test-runner -test="failing-test-name" -token="your-token"

Configuration Issues

# Validate JSON configuration
python3 -m json.tool configs/seed-data.json
python3 -m json.tool configs/test-scenarios.json

Differences from GitLab Integration Tests

Uses organizations instead of groups (Gitea terminology)
Gitea runs on port 3000 by default (vs GitLab's 80/443)
Different API endpoints and authentication mechanisms
Simplified user management (no complex namespace handling)
Uses the code.gitea.io/sdk/gitea Go SDK instead of GitLab's SDK

GitHub Actions Integration

The Gitea integration tests can be run in GitHub Actions via the workflow file at .github/workflows/gitea-integration-tests.yml. This workflow:

Sets up Go and Docker
Builds ghorg
Adds necessary host entries
Runs the full Gitea integration test suite

The tests run automatically on pull requests to ensure ghorg's Gitea functionality remains working.

README.md

Gitea Integration Tests

Directory Structure

Quick Start

Running All Tests

Script Arguments

Quick Reference

start.sh Arguments

Individual Component Arguments

seed.sh Arguments

integration-tests.sh Arguments

run.sh Arguments (Internal)

Go Tool Arguments (Direct Usage)

Running Individual Components

Configuration

Seed Data Configuration (configs/seed-data.json)

Test Scenarios Configuration (configs/test-scenarios.json)

Adding New Seed Data

Example: Adding a New Organization

Adding New Test Scenarios

Manual Configuration

Programmatically

Template Variables

Development

Building the Components

Running Tests in Development

Troubleshooting

Build Errors

Test Failures

Configuration Issues

Differences from GitLab Integration Tests

GitHub Actions Integration

`start.sh` Arguments

`seed.sh` Arguments

`integration-tests.sh` Arguments

`run.sh` Arguments (Internal)

Seed Data Configuration (`configs/seed-data.json`)

Test Scenarios Configuration (`configs/test-scenarios.json`)