---

Gitcord (Discord–GitHub Automation Engine)

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.

---

🚀 Features

• 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.

---

💻 Tech Stack

Backend

• Python 3.11+
• SQLite (local state)
• Pydantic + PyYAML

---

✅ Project Checklist

• Audit-first workflow: reports generated for review.
• Dry-run default: writes gated by mode and permissions.
• Permission-limited operation: safe under missing permissions.

---

🔗 Repository Links

1. Main Repository

---

🏗️ Architecture Diagram

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.

---

🔄 User Flow

Load config -> Ingest -> Score -> Plan -> Audit -> (Optional) Apply

Key User Journeys

1. Dry‑run review

   • Configure tokens and org
   • Run run-once in dry‑run mode
   • Review audit reports

2. Observer mode

   • Run read‑only without write permissions
   • Produce audit output for reviewers

---

🍀 Getting Started

Prerequisites

• Python 3.11+
• GitHub and Discord tokens with read permissions

Installation

1. Clone the Repository

git clone https://github.com/AOSSIE-Org/Gitcord-GithubDiscordBot.git
cd Gitcord-GithubDiscordBot

2. Install Dependencies

python3 -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 .

3. Configure Environment Variables

Create a .env file in the root directory (you can copy .env.example):

GITHUB_TOKEN=your_github_token
DISCORD_TOKEN=your_discord_token

Notes:

• Tokens must have read permissions for the org/repo and Discord server.

4. Configure and Run (Safe Dry‑Run)

cp config/example.yaml /tmp/ghdcbot-config.yaml
# Use the venv python explicitly to avoid alias/PATH issues
./.venv/bin/python -m ghdcbot.cli --config /tmp/ghdcbot-config.yaml run-once

Expected output files (see data_dir in /tmp/ghdcbot-config.yaml):

<data_dir>/reports/audit.json
<data_dir>/reports/audit.md

5. Run Discord Bot

Start the Discord bot with slash commands:

./.venv/bin/python -m ghdcbot.cli --config config/your-config.yaml bot

Bot Invitation: Invite the bot with scopes bot and applications.commands, plus permissions Manage Roles, View Channels, and Read Message History.

6. Testing in Discord

1. Dry-run (default): Run run-once with 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.md to see planned role add/remove actions.
2. Live role updates: To have the bot actually add/remove roles in Discord, set in your config:
   • runtime.mode: "active"
   • discord.permissions.write: true Then run run-once again. Ensure the bot’s role in the server is above any roles it should assign (Server Settings → Roles). See Testing in Discord for details.

---

🤖 Discord Bot Commands

Identity Linking

• /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

Contribution & Metrics

• /summary - Show your contribution metrics (7 and 30 days)
• /pr-info - Show PR context preview (repository, reviews, CI status)

Issue Management

• /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.

---

📱 App Screenshots

Not applicable (CLI automation engine).

---

🙌 Contributing

Thank you for considering contributing to this project! Contributions are highly appreciated and welcomed. To ensure smooth collaboration, please refer to our Contribution Guidelines.

---

✨ Maintainers

See contributors.

---

📍 License

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

---

💪 Thanks To All Contributors

Thanks a lot for spending your time helping Gitcord grow. Keep rocking 🥂

© 2026 AOSSIE