Gitcord is a local, offline‑first automation engine that reads GitHub activity and Discord state, then plans role changes and GitHub assignments in a deterministic, reviewable way. It is designed for safety: dry‑run and observer modes produce audit reports without mutating anything.
- Offline‑first execution: run locally on demand, no daemon required.
- Audit‑first workflow: JSON + Markdown reports before any writes.
- Deterministic planning: identical inputs produce identical plans.
- Permission‑aware IO: readers degrade safely on missing permissions.
- Discord Bot: Interactive slash commands for identity linking, issue management, and contribution tracking.
- Python 3.11+
- SQLite (local state)
- Pydantic + PyYAML
- Audit-first workflow: reports generated for review.
- Dry-run default: writes gated by mode and permissions.
- Permission-limited operation: safe under missing permissions.
- Main Repository
- Installation Guide - Complete setup instructions
- Technical Documentation - Architecture and design
- Docker Guide - Docker setup and mentor-friendly deployment
Read -> Plan -> Report -> Apply
Core boundaries:
- Readers are read‑only (GitHub/Discord ingestion).
- Planners are pure, deterministic logic.
- Writers are thin executors gated by
MutationPolicy.
Load config -> Ingest -> Score -> Plan -> Audit -> (Optional) Apply
-
Dry‑run review
- Configure tokens and org
- Run
run-oncein dry‑run mode - Review audit reports
-
Observer mode
- Run read‑only without write permissions
- Produce audit output for reviewers
📖 New to Gitcord? For complete step-by-step setup instructions including Discord bot creation and GitHub token setup, see INSTALLATION.md.
Before installing Gitcord, you need:
- ✅ GitHub Organization access
- ✅ Discord Server with admin permissions
- ✅ GitHub Personal Access Token (fine-grained PAT) - How to create
- ✅ Discord Bot Token - How to create
If you have Docker installed, you can skip Python setup and run Gitcord in one go:
git clone https://github.com/AOSSIE-Org/Gitcord-GithubDiscordBot.git
cd Gitcord-GithubDiscordBot
cp .env.example .env # Add your GITHUB_TOKEN and DISCORD_TOKEN
cp config/docker-example.yaml config/config.yaml # Set github.org and discord.guild_id
docker compose up -dThe Discord bot stays running; SQLite data and reports persist in a Docker volume. To run a one-off sync (e.g. dry-run):
docker compose run --rm bot --config /app/config/config.yaml run-once
See docs/DOCKER.md for details, pitfalls, and audit-first workflow.
1. Create GitHub Token (Detailed Guide)
- Go to GitHub → Settings → Developer Settings → Fine-grained tokens
- Permissions: Contents (Read & Write), Issues (Read & Write), Pull requests (Read & Write)
2. Create Discord Bot (Detailed Guide)
- Go to Discord Developer Portal
- Create Application → Add Bot → Enable Server Members Intent
3. Invite Bot to Server (Detailed Guide)
- OAuth2 → URL Generator
- Scopes:
bot,applications.commands - Permissions:
Manage Roles,View Channels,Send Messages,Embed Links,Read Message History ⚠️ Never use Administrator permission
4. Install Gitcord
git clone https://github.com/AOSSIE-Org/Gitcord-GithubDiscordBot.git
cd Gitcord-GithubDiscordBotpython3 -m venv .venv
. .venv/bin/activate
# Use the venv's pip to avoid shell aliases or PATH issues
./.venv/bin/python -m pip install -e .5. Configure Environment Variables
Create a .env file (copy from .env.example):
GITHUB_TOKEN=your_github_token_here
DISCORD_TOKEN=your_discord_bot_token_here6. Create Configuration File
Copy and edit: cp config/example.yaml config/my-org-config.yaml
Edit config: Set github.org, discord.guild_id, and snapshots.repo_path
7. Test Run (Dry-Run Mode)
./.venv/bin/python -m ghdcbot.cli --config config/my-org-config.yaml run-onceThis generates audit reports without making changes. Review data/my-org/reports/audit.md.
8. Run Discord Bot
./.venv/bin/python -m ghdcbot.cli --config config/my-org-config.yaml botWait 30 seconds for commands to sync.
9. Enable Active Mode (After Testing)
- Dry-run (default): Run
run-oncewith your config. The bot reads your guild’s members and roles, scores GitHub activity, and writes audit reports. No roles are changed in Discord; check<data_dir>/reports/audit.mdto see planned role add/remove actions. - Live role updates: To have the bot actually add/remove roles in Discord, set in your config:
runtime.mode: "active"discord.permissions.write: trueThen runrun-onceagain. Ensure the bot’s role in the server is above any roles it should assign (Server Settings → Roles). See Testing in Discord for details.
/link- Link your Discord account to GitHub (creates verification code)/verify-link- Verify your GitHub link after adding code to bio/gist/verify- Check your verification status/status- Show verification state, activity window, and roles/unlink- Unlink your GitHub identity
/summary- Show your contribution metrics (7 and 30 days)/pr-info- Show PR context preview (repository, reviews, CI status)
/request-issue- Request to be assigned to a GitHub issue/assign-issue- Assign issue to Discord user (mentor-only)/issue-requests- Review pending issue requests (mentor-only)/sync- Manually sync GitHub events and notifications (mentor-only)
Note: Commands marked "mentor-only" require roles configured in assignments.issue_assignees. The bot also auto-detects PR URLs in configured channels and shows PR previews.
Not applicable (CLI automation engine).
Thank you for considering contributing to this project! Contributions are highly appreciated and welcomed. To ensure smooth collaboration, please refer to our Contribution Guidelines.
See contributors.
This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.
Thanks a lot for spending your time helping Gitcord grow. Keep rocking 🥂
© 2026 AOSSIE
