A Discord bot for GitOps-based Discord server management. Manage your server's channels and categories using YAML templates, version control, and GitHub integration.

The easiest way to get started is to invite the pre-hosted GitCord bot to your Discord server:

📥 Invite GitCord Bot

After inviting the bot, you can start using commands immediately. See the Quick Start Guide for usage examples.

If you prefer to run your own instance of GitCord:

1. Clone the repository:

   git clone https://github.com/evolvewithevan/gitcord.git
   cd gitcord

2. Install dependencies (requires Python 3.9+ and uv)

   uv sync

3. Set up environment variables:

   cp .env.example .env
   # Edit .env and add your Discord bot token

4. Run the bot:

   python -m gitcord

For detailed self-hosting setup, see the Installation Guide.

GitCord is a Discord bot that lets you manage your server's structure using YAML configuration files, stored in Git and optionally synced with GitHub. It enables:

• Version-controlled server configuration
• Automated and manual sync of categories/channels
• Bulk creation of channels/categories from templates
• Easy server setup and reproducibility

• Template-based Channel & Category Creation: Use YAML files to define your server structure
• Manual & Planned Automatic Sync: Pull changes from a GitHub repo or local files
• Slash & Prefix Commands: Use /createcategory, /createchannel, !createcategory, etc.
• Permission Management: Follows Discord's permission system
• Extensible: Modular cog system for easy extension
• Open Source: GPL-3.0 License

See the full feature list.

• Create a channel from YAML:

  # general.yaml
  name: general
  type: text
  topic: General discussion
  position: 0
  nsfw: false

  Use: !createchannel

• Create a category with channels:

  # community.yaml
  name: Community
  type: category
  position: 0
  channels:
    - general
    - memes
    - off-topic

  Use: !createcategory or /createcategory

See Quick Start and Templates Guide.

• !hello / /hello — Greet the bot
• !ping / /slashping — Check bot latency
• !createchannel — Create a channel from YAML
• !createcategory / /createcategory [yaml_path] — Create a category with channels
• !fetchurl <url> / /fetchurl <url> — Fetch text from a website (admin)
• !synccommands / /synccommands — Update slash commands (admin)
• !help / /help — Show help and links

See Commands Reference.

gitcord/
├── src/gitcord/           # Main source code
│   ├── bot.py            # Main bot entry point
│   ├── config.py         # Configuration management
│   ├── events.py         # Discord event handlers
│   ├── cogs/             # Discord.py cogs (command modules)
│   ├── utils/            # Utility functions
│   ├── views/            # Discord UI components
│   └── constants/        # Constants and messages
├── gitcord-template/     # Example template repository
├── docs/                 # Documentation (mdBook)
├── requirements.txt      # Python dependencies
├── pyproject.toml        # Project metadata
└── README.md             # Project documentation

• Alpha: Core features implemented, active development
• See the Roadmap for planned features and progress
• Planned Features:
  • Webhook-based automatic sync
  • Advanced template features (inheritance, variables)
  • More admin tools

We welcome contributions! Please read CONTRIBUTING.md for:

• Coding standards (PEP8, type hints, docstrings)
• How to set up your dev environment
• Testing and documentation guidelines
• Pull request process

• Common Issues
• Error Messages
• GitHub Issues
• Discussions

This project is licensed under the GNU General Public License v3.0. See LICENSE.

Made with ❤️ by the GitCord Team. Full Documentation