swadhin / opencodehub public

docs(site): add missing docs-site entries for webhooks-api, ci-cd, and slack-integration

Swadhin Biswas committed 5 months ago
d91d749
1 parent ac8f8cc
commit d91d749
3 files changed
+293 -0
Showing 3 changed files+293-0
docs-site/src/content/docs/api/webhooks-api.mddocs-site/src/content/docs/features/ci-cd.mddocs-site/src/content/docs/features/slack-integration.md
▼docs-site/src/content/docs/api/webhooks-api.md
+99-0
@@ -0,0 +1,99 @@
1
+---
2
+title: "Webhooks API"
3
+---
4
+
5
+OpenCodeHub supports outbound webhooks for event-driven integrations with external services like Slack, Discord, CI systems, and custom applications.
6
+
7
+## Supported Events
8
+
9
+| Event | Description |
10
+|-------|-------------|
11
+| `push` | Code pushed to a branch |
12
+| `pull_request.opened` | PR created |
13
+| `pull_request.closed` | PR merged or closed |
14
+| `pull_request.reviewed` | Review submitted on a PR |
15
+| `issues.opened` | Issue created |
16
+| `issues.closed` | Issue closed |
17
+| `release.published` | Release published |
18
+| `merge_queue.merged` | PR merged via queue |
19
+| `merge_queue.failed` | Queue merge failed |
20
+| `repository.created` | New repository created |
21
+
22
+## Managing Webhooks
23
+
24
+### Create a Webhook
25
+
26
+```http
27
+POST /api/repos/{owner}/{repo}/webhooks
28
+```
29
+
30
+**Body:**
31
+```json
32
+{
33
+ "url": "https://yourapp.com/webhook",
34
+ "events": ["push", "pull_request.opened"],
35
+ "secret": "your-webhook-secret",
36
+ "active": true
37
+}
38
+```
39
+
40
+### List Webhooks
41
+
42
+```http
43
+GET /api/repos/{owner}/{repo}/webhooks
44
+```
45
+
46
+### Test a Webhook
47
+
48
+```http
49
+POST /api/repos/{owner}/{repo}/webhooks/{id}/test
50
+```
51
+
52
+## Payload Format
53
+
54
+All payloads follow this structure:
55
+
56
+```json
57
+{
58
+ "event": "pull_request.opened",
59
+ "repository": {
60
+ "id": "repo_123",
61
+ "name": "my-repo",
62
+ "owner": "alice"
63
+ },
64
+ "sender": {
65
+ "id": "usr_456",
66
+ "username": "alice"
67
+ },
68
+ "timestamp": "2024-01-15T10:30:00Z",
69
+ "data": { ... }
70
+}
71
+```
72
+
73
+## Signature Verification
74
+
75
+Webhooks are signed with HMAC-SHA256 using the configured secret.
76
+
77
+**Node.js:**
78
+```javascript
79
+const crypto = require('crypto');
80
+
81
+function verifyWebhook(payload, signature, secret) {
82
+ const expected = crypto
83
+ .createHmac('sha256', secret)
84
+ .update(payload, 'utf8')
85
+ .digest('hex');
86
+ return crypto.timingSafeEqual(
87
+ Buffer.from(signature),
88
+ Buffer.from(`sha256=${expected}`)
89
+ );
90
+}
91
+```
92
+
93
+## Best Practices
94
+
95
+1. Use HTTPS URLs only
96
+2. Always verify the HMAC signature
97
+3. Handle duplicate deliveries with idempotency keys
98
+4. Respond quickly (return 200 immediately)
99
+5. Never leave the webhook secret empty
0
100
▼docs-site/src/content/docs/features/ci-cd.md
+108-0
@@ -0,0 +1,108 @@
1
+---
2
+title: "CI/CD Pipelines"
3
+---
4
+
5
+OpenCodeHub includes a built-in CI/CD pipeline engine that reads workflow definitions from `.github/workflows/*.yml` files in your repository.
6
+
7
+## Supported Features
8
+
9
+- **GitHub Actions-compatible syntax** — familiar `jobs`, `steps`, `runs-on`, and `uses`
10
+- **Docker-based execution** — every job runs in an isolated container
11
+- **Matrix builds** — test across multiple versions or configurations
12
+- **Secrets management** — encrypted repository and organization secrets
13
+- **Artifact storage** — upload and download build artifacts
14
+- **Caching** — cache dependencies between runs
15
+- **Self-hosted runners** — run jobs on your own infrastructure
16
+
17
+## Quick Start
18
+
19
+### 1. Create a Workflow File
20
+
21
+Add `.github/workflows/ci.yml` to your repository:
22
+
23
+```yaml
24
+name: CI
25
+
26
+on:
27
+ push:
28
+ branches: [main]
29
+ pull_request:
30
+ branches: [main]
31
+
32
+jobs:
33
+ test:
34
+ runs-on: ubuntu-latest
35
+ steps:
36
+ - uses: actions/checkout@v4
37
+ - name: Setup Node.js
38
+ uses: actions/setup-node@v4
39
+ with:
40
+ node-version: '20'
41
+ - name: Install dependencies
42
+ run: npm ci
43
+ - name: Run tests
44
+ run: npm test
45
+```
46
+
47
+### 2. Push and Watch
48
+
49
+Push the file to OpenCodeHub. The workflow is automatically detected and a run is triggered.
50
+
51
+## Runner Configuration
52
+
53
+### In-App Runner
54
+
55
+```bash
56
+npm run runner:start
57
+```
58
+
59
+### Docker Runner (Recommended)
60
+
61
+```yaml
62
+services:
63
+ runner:
64
+ build:
65
+ context: .
66
+ dockerfile: Dockerfile.runner
67
+ privileged: true
68
+ environment:
69
+ SERVER_URL: https://git.yourcompany.com
70
+ RUNNER_TOKEN: <from-admin-panel>
71
+```
72
+
73
+## Status Checks & Branch Protection
74
+
75
+Require CI to pass before merging:
76
+
77
+1. Go to Repository → Settings → Branches
78
+2. Add protection rule for `main`
79
+3. Enable **Require status checks to pass**
80
+4. Select your workflow name
81
+
82
+## Monitoring Pipeline Runs
83
+
84
+### Web UI
85
+
86
+Repository → Actions shows run history, step-by-step logs, and artifacts.
87
+
88
+### CLI
89
+
90
+```bash
91
+och actions list
92
+och actions logs <run-id>
93
+och actions cancel <run-id>
94
+```
95
+
96
+### API
97
+
98
+```bash
99
+curl https://git.yourcompany.com/api/repos/owner/repo/actions/runs \
100
+ -H "Authorization: Bearer $TOKEN"
101
+```
102
+
103
+## Best Practices
104
+
105
+- Run lint and unit tests first (fast), integration tests after (slower)
106
+- Use caching for dependencies
107
+- Cancel redundant runs on new pushes
108
+- Use `paths` filters to avoid unnecessary builds
0
109
▼docs-site/src/content/docs/features/slack-integration.md
+86-0
@@ -0,0 +1,86 @@
1
+---
2
+title: "Slack Integration"
3
+---
4
+
5
+OpenCodeHub's Slack integration sends real-time notifications for repository events and allows quick actions directly from Slack channels.
6
+
7
+## Supported Events
8
+
9
+| Event | Notification | Actions |
10
+|-------|-----------|---------|
11
+| Pull Request opened | Title, author, branch | Review, Approve |
12
+| PR approved / changes requested | Reviewer, status | View diff |
13
+| PR merged | Merger, commit count | View commit |
14
+| CI failed | Job name, failure step | View logs, Retry |
15
+| Issue created / assigned | Title, assignee | View, Comment |
16
+| Release published | Version, changelog | View release |
17
+
18
+## Setup
19
+
20
+### 1. Create a Slack App
21
+
22
+1. Go to [api.slack.com/apps](https://api.slack.com/apps)
23
+2. Click **Create New App** → **From scratch**
24
+3. Name it "OpenCodeHub" and select your workspace
25
+
26
+### 2. Configure Permissions
27
+
28
+Add the following **Bot Token Scopes**:
29
+
30
+```
31
+chat:write
32
+chat:write.public
33
+im:write
34
+users:read
35
+files:write
36
+```
37
+
38
+### 3. Install App to Workspace
39
+
40
+1. Click **Install to Workspace**
41
+2. Copy the **Bot User OAuth Token** (starts with `xoxb-`)
42
+
43
+### 4. Configure OpenCodeHub
44
+
45
+Add to your `.env`:
46
+
47
+```bash
48
+SLACK_ENABLED=true
49
+SLACK_BOT_TOKEN=xoxb-your-token-here
50
+SLACK_SIGNING_SECRET=your-signing-secret
51
+```
52
+
53
+Or configure via the web UI:
54
+1. Go to **Organization Settings** → **Integrations** → **Slack**
55
+2. Paste the bot token and signing secret
56
+3. Click **Test Connection**
57
+
58
+### 5. Subscribe Repositories
59
+
60
+Per-repository settings:
61
+1. Go to **Repository** → **Settings** → **Integrations**
62
+2. Enable Slack notifications
63
+3. Choose channel and events
64
+
65
+## Slash Commands
66
+
67
+```
68
+/och prs [repo] List open PRs
69
+/och review <pr-number> Quick review a PR
70
+/och queue [repo] Show merge queue status
71
+/och issues [repo] List open issues
72
+```
73
+
74
+## Troubleshooting
75
+
76
+### "Notifications not appearing"
77
+
78
+1. Verify the bot is invited to the channel (`/invite @OpenCodeHub`)
79
+2. Check repository subscription settings
80
+3. Verify `SLACK_BOT_TOKEN` is correct
81
+
82
+### "Too many notifications"
83
+
84
+- Enable notification batching
85
+- Filter by event type in repository settings
86
+- Use `@mentions` only mode for noisy repos
0
87