Skip to content

Commit 02236d7

Browse files
docs: Update README Getting Started with clear setup instructions
- Add prominent link to INSTALLATION.md at top - Expand prerequisites with links to detailed guides - Add Quick Setup Overview with 9 numbered steps - Include Discord bot creation and GitHub token setup overview - Make it clear what needs to be done before installation - Add reference to detailed installation and technical docs Co-authored-by: Cursor <cursoragent@cursor.com>
1 parent b986c68 commit 02236d7

1 file changed

Lines changed: 38 additions & 9 deletions

File tree

README.md

Lines changed: 38 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -126,11 +126,35 @@ Load config -> Ingest -> Score -> Plan -> Audit -> (Optional) Apply
126126

127127
## 🍀 Getting Started
128128

129+
> **📖 New to Gitcord?** For complete step-by-step setup instructions including Discord bot creation and GitHub token setup, see **[INSTALLATION.md](INSTALLATION.md)**.
130+
129131
### Prerequisites
130-
- Python 3.11+
131-
- GitHub and Discord tokens with read permissions
132132

133-
### Installation
133+
Before installing Gitcord, you need:
134+
135+
-**Python 3.11+** installed
136+
-**GitHub Organization** access
137+
-**Discord Server** with admin permissions
138+
-**GitHub Personal Access Token** (fine-grained PAT) - [How to create](INSTALLATION.md#step-1-create-github-token-pat)
139+
-**Discord Bot Token** - [How to create](INSTALLATION.md#step-2-create-discord-bot)
140+
141+
### Quick Setup Overview
142+
143+
**1. Create GitHub Token** ([Detailed Guide](INSTALLATION.md#step-1-create-github-token-pat))
144+
- Go to GitHub → Settings → Developer Settings → Fine-grained tokens
145+
- Permissions: Contents (Read & Write), Issues (Read & Write), Pull requests (Read & Write)
146+
147+
**2. Create Discord Bot** ([Detailed Guide](INSTALLATION.md#step-2-create-discord-bot))
148+
- Go to [Discord Developer Portal](https://discord.com/developers/applications)
149+
- Create Application → Add Bot → Enable **Server Members Intent**
150+
151+
**3. Invite Bot to Server** ([Detailed Guide](INSTALLATION.md#step-3-invite-bot-to-discord-server))
152+
- OAuth2 → URL Generator
153+
- Scopes: `bot`, `applications.commands`
154+
- Permissions: `Manage Roles`, `View Channels`, `Send Messages`, `Embed Links`, `Read Message History`
155+
- ⚠️ **Never** use Administrator permission
156+
157+
**4. Install Gitcord**
134158

135159
#### 1. Clone the Repository
136160

@@ -148,17 +172,22 @@ python3 -m venv .venv
148172
./.venv/bin/python -m pip install -e .
149173
```
150174

151-
#### 3. Configure Environment Variables
175+
**5. Configure Environment Variables**
152176

153-
Create a `.env` file in the root directory (you can copy `.env.example`):
177+
Create a `.env` file (copy from `.env.example`):
154178

155179
```env
156-
GITHUB_TOKEN=your_github_token
157-
DISCORD_TOKEN=your_discord_token
180+
GITHUB_TOKEN=your_github_token_here
181+
DISCORD_TOKEN=your_discord_bot_token_here
158182
```
159183

160-
Notes:
161-
- Tokens must have read permissions for the org/repo and Discord server.
184+
**6. Create Configuration File**
185+
186+
Copy and edit: `cp config/example.yaml config/my-org-config.yaml`
187+
188+
Edit config: Set `github.org`, `discord.guild_id`, and `snapshots.repo_path`
189+
190+
**7. Test Run (Dry-Run Mode)**
162191

163192
#### 4. Configure and Run (Safe Dry‑Run)
164193

0 commit comments

Comments
 (0)