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! π
This project is in early development - use with caution in production environments.
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!
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
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!
- π₯ 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
- π Dry Run Mode: Preview changes before applying them
- π€ Automation Ready: Perfect for CI/CD pipelines
Choose one of the following installation methods:
# Install
brew install dualstacks/tap/gitea-config-wave
# Upgrade
brew upgrade gitea-config-wave
- Download the latest binary for your platform from the releases page
- Extract the archive (if applicable)
- Move the binary to your PATH:
# Example for macOS/Linux
chmod +x gitea-config-wave
sudo mv gitea-config-wave /usr/local/bin/
# 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
- Log in to your Gitea instance
- Go to Settings β Applications β Generate New Token
- Give your token a name (e.g., "Config Wave")
- Select the following permissions:
read:organization
: Read organization informationwrite:repository
: Full control of repositories (includes settings, webhooks, and branch protections)
- Click "Generate Token" and save it securely
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"
# 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
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
# Preview changes (dry run)
gitea-config-wave push --dry-run
# Apply changes to all target repositories
gitea-config-wave push
# .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
# .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"
The tool expects a gitea-config-wave.yaml
file in the current directory. Refer to the example configuration for more details.
- Setting up consistent branch protection rules across repos
- Configuring external issue trackers (e.g., Jira) for multiple repos
- Maintaining uniform PR and issue templates
- Enforcing organization-wide repository settings
This project is in early development - use with caution in production environments.
- Webhook management
- Basic settings sync
- Branch protection rules
- Issue and PR template sync
- Tag protection rules
- Distribute as Gitea Action
TODO:
MIT License - see LICENSE for details.
Gitea Config Wave - An automated configuration management tool for Gitea instances that enables bulk repository settings management, branch protection rules enforcement, and standardized repository configurations through a simple CLI interface.