Skip to content

Commit 7847cc6

Browse files
swadhinbiswasswadhinbiswas
committed
docs(site): add missing docs-site entries for webhooks-api, ci-cd, and slack-integration
1 parent 092eae8 commit 7847cc6

3 files changed

Lines changed: 293 additions & 0 deletions

File tree

‎docs-site/src/content/docs/api/webhooks-api.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -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

‎docs-site/src/content/docs/features/ci-cd.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -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

‎docs-site/src/content/docs/features/slack-integration.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -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 commit comments

Comments
 (0)