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, contributor profiles, metrics, and notifications.
- 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 (Docker and local)
- Environment Variables -
.envreference - 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
-
Preflight check
- Configure tokens and org
- Run
ghdcbot --config config/config.yaml validate - Fix any ✗ failures before continuing
-
Dry‑run review
- Run
run-oncein dry‑run mode - Review audit reports
- Run
-
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 -d
docker compose logs -f botThe 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.
For development and user testing, run Gitcord locally with Docker as described above. When the bot must stay online while your computer is off, deploy the same Compose setup to an always-on Linux host.
This works with Oracle Cloud Free Tier, a small VM from another provider, or your own always-on server. Gitcord does not accept inbound web traffic, so the VM only needs outbound HTTPS access plus SSH for administration.
-
Create an Ubuntu/Debian VM, install Git, Docker Engine and the Compose plugin, then clone this repository.
-
Create
.envandconfig/config.yamlexactly as in the Docker quick start. Keepruntime.data_dir: "/data"so SQLite survives restarts. -
Validate the configuration, then start the bot and scheduled sync:
docker compose run --rm bot --config /app/config/config.yaml validate docker compose --profile scheduler up -d --build docker compose ps docker compose logs -f bot sync-scheduler
Both services use restart: unless-stopped, and the named gitcord_data volume preserves identities, notification history, and sync cursors across container or VM restarts. The scheduler runs every six hours by default; set GITCORD_SYNC_INTERVAL_SECONDS in .env to change it.
For updates:
git pull
docker compose --profile scheduler up -d --buildProtect .env, restrict SSH access, and back up the gitcord_data volume. Never commit production tokens or config/config.yaml.
Fly.io is possible, but the repository is not currently a one-command Fly deployment: its Compose file uses host networking and a local named volume. A Fly deployment must remove network_mode: host, provide secrets through fly secrets, mount a persistent volume at /data, and run the bot and scheduler without allowing overlapping syncs. Use a Linux VPS for the supported copy-and-run path until platform-specific deployment files are added.
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 → set App Icon + Bot Icon from
public/gitcord-discord-icon-large.png→ 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
source .venv/bin/activate
pip install -e .Full walkthrough: INSTALLATION.md.
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/config.yamlEdit config/config.yaml: set github.org, discord.guild_id, and runtime.data_dir: "./data". Match role_mappings to role names in your Discord server.
7. Test Run (Dry-Run Mode)
ghdcbot --config config/config.yaml run-onceThis generates audit reports without making changes. Review data/reports/audit.md.
8. Run Discord Bot
ghdcbot --config config/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, ingests 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
config/config.yaml:runtime.mode: "active"runtime.enable_discord_role_updates: truediscord.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 and INSTALLATION.md for details.
/link- Link your Discord account to GitHub (creates verification code)/verify-link- Verify your GitHub link after adding code to bio/gist/profile- Show contributor profile (GitHub, verification, socials, roles); optional Discord member/unlink- Unlink your GitHub identity/connect-social- Connect X or LinkedIn (enter your username or profile URL)/disconnect-social- Disconnect X or LinkedIn from Gitcord
/summary- Show contribution metrics (7 and 30 days); optional Discord member for another verified contributor/open-prs- List a contributor's currently open PRs in configured repos
/sync- Manually sync GitHub events and send notifications
Note: /sync requires a mentor role configured in discord.command_permissions. The bot can also auto-detect PR URLs in configured channels and post passive 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