🌊 Gitea Config Wave

Effortlessly enforce branch protections, standardize external trackers, and maintain consistent repository defaults across your entire self-hosted Gitea instance with just one command - say goodbye to manual configuration! 🚀

Project Status 🚧

This project is in early development - use with caution in production environments.

What is this? 🤔

Gitea Config Wave is a CLI tool that helps you manage repository settings across multiple repositories in your Gitea instance. Think of it as a "settings propagator" that lets you define settings once and apply them everywhere!

The Problem 🗿

If you're managing many repos in a self-hosted Gitea instance (not Enterprise), you might have faced these challenges:

• No way to set organization-wide branch protection rules or repo defaults like external trackers
• Manual configuration needed for each repository's settings
• Time-consuming process to maintain consistent settings across repos
• Need to push issue and PR templates to each repo

The Solution 🎯

Gitea Config Wave provides a simple CLI to pull settings from a "canonical" repository and push them to multiple target repositories. It's like copy-paste, but for repo settings!

Features ✨

• 📥 Pull Settings: Extract settings from any repo to use as a template
• 🔎 Manage config as YAML: Store and version control your repository settings as YAML files
• 📤 Push Settings: Apply settings to multiple repos at once
• 🛡️ Branch Protection: Sync branch protection rules across repos
• 🎯 Repository Settings: Manage core repo settings and topics
• 📋 Issue & PR Templates: Sync issue and pull request templates across Gitea repositories
• 🔍 Dry Run Mode: Preview changes before applying them
• 🤖 Automation Ready: Perfect for CI/CD pipelines

Installation 🔧

Choose one of the following installation methods:

Using Homebrew (macOS/Linux)

# Install
brew install dualstacks/tap/gitea-config-wave

# Upgrade
brew upgrade gitea-config-wave

Using Pre-built Binaries

1. Download the latest binary for your platform from the releases page
2. Extract the archive (if applicable)
3. Move the binary to your PATH:

# Example for macOS/Linux
chmod +x gitea-config-wave
sudo mv gitea-config-wave /usr/local/bin/

Building from Source

# Clone the repository
git clone https://github.com/DUALSTACKS/gitea-config-wave.git
cd gitea-config-wave

# Build the binary
make build

# Optional: Install to your PATH
sudo make install

Quick Start 🚀

1. Create a Gitea Access Token

1. Log in to your Gitea instance
2. Go to Settings → Applications → Generate New Token
3. Give your token a name (e.g., "Config Wave")
4. Select the following permissions:
   • read:organization: Read organization information
   • write:repository: Full control of repositories (includes settings, webhooks, and branch protections)
5. Click "Generate Token" and save it securely

2. Configure the Tool

Create a gitea-config-wave.yaml in your working directory:

gitea_url: "https://your-gitea-instance.com"  # Your Gitea instance URL
gitea_token: "${GITEA_TOKEN}"                 # Use environment variable for token

config:
  output_dir: .gitea/defaults                 # Where to store pulled settings

targets:
  repos:
    - "org/repo1"                            # List of target repositories
    - "org/repo2"
    - "org/repo3"

3. Pull Settings from a Template

# Export your Gitea token
export GITEA_TOKEN="your-token-here"

# Pull settings from a template repository
gitea-config-wave pull org/template-repo

# This will create YAML files in .gitea/defaults/ with the current settings

4. Review and Customize Settings

The pulled settings are stored in YAML files:

• .gitea/defaults/branch_protections.yaml: Branch protection rules
• .gitea/defaults/repo_settings.yaml: Repository settings
• .gitea/defaults/topics.yaml: Repository topics
• .gitea/defaults/webhooks.yaml: Webhook configurations

5. Push Settings to Target Repositories

# Preview changes (dry run)
gitea-config-wave push --dry-run

# Apply changes to all target repositories
gitea-config-wave push

Configuration Examples 📝

Branch Protection Rules

# .gitea/defaults/branch_protections.yaml
branch_protections:
  - branch_name: "main"
    enable_push: false
    enable_push_whitelist: true
    push_whitelist_usernames: ["maintainer1", "maintainer2"]
    enable_status_check: true
    status_check_contexts: ["ci/jenkins"]
    require_signed_commits: true

Issue and PR Templates

Gitea Config Wave supports syncing issue and pull request templates across repositories. Templates can be stored in any of the officially supported locations, including:

• .gitea/ISSUE_TEMPLATE/
• .gitea/PULL_REQUEST_TEMPLATE/
• .github/ISSUE_TEMPLATE/
• .github/PULL_REQUEST_TEMPLATE/
• etc (check the Gitea docs for more info)

When you run pull, it will extract templates from your source repository and store them in YAML format. When you run push, it will open a PR to create or update the templates in all target repositories.

Repository Settings

# .gitea/defaults/repo_settings.yaml
repository_settings:
  enable_issues: true
  enable_projects: true
  enable_pull_requests: true
  ignore_whitespace_conflicts: true
  enable_merge_commits: false
  enable_rebase: true
  enable_squash: true
  default_merge_style: "rebase"

Examples 💡

Check out the examples/ directory for complete usage scenarios:

• partial-config/: How to update only specific settings while preserving others
• multi-target-config/: Managing different configurations for internal vs open source repositories
• kubernetes-cronjob/: Running gitea-config-wave as a Kubernetes CronJob

Configuration 🛠️

The tool expects a gitea-config-wave.yaml file in the current directory. Refer to the example configuration for more details.

Use Cases 💡

Check out the examples/ directory for real-world usage scenarios:

• partial-config/: How to update only specific settings while preserving others
• multi-target-config/: Managing different configurations for internal vs open source repositories
• kubernetes-cronjob/: Running gitea-config-wave as a Kubernetes CronJob