Skip to content

Commit d5abbda

Browse files
mizchimizchi
committed
docs: add ci trigger specification in english and japanese
1 parent b39868d commit d5abbda

4 files changed

Lines changed: 239 additions & 0 deletions

File tree

‎docs/ci-trigger-spec-ja.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# CI トリガー仕様
2+
3+
このドキュメントは bit-relay の CI トリガーフローを定義する:
4+
5+
1. Relay が `git-receive-pack` 経由で `refs/relay/incoming/...` を受け取る
6+
2. Relay が外部 Webhook を発火する
7+
3. 外部 CI が relay へ結果を callback する
8+
4. クライアントが relay API から CI 結果を取得する
9+
10+
## 1. トリガー入力
11+
12+
incoming ref は `POST /git/<session_id>/git-receive-pack` の request body から抽出する。
13+
14+
- マッチパターン: `refs/relay/incoming/[A-Za-z0-9._/-]{1,255}`
15+
- 同一 body 内の重複 ref は 1 回に正規化（dedupe）
16+
- 一意な incoming ref ごとに `incoming_ref` イベントを 1 件発行
17+
18+
## 2. Webhook 発火条件
19+
20+
次の条件を満たす場合のみ webhook を送信する:
21+
22+
- `RELAY_TRIGGER_WEBHOOK_URL` が設定されている
23+
- incoming ref が設定済みプレフィックスのいずれかに一致する
24+
- incoming-ref イベント発行パスまで処理が到達している
25+
26+
設定値:
27+
28+
- `RELAY_TRIGGER_WEBHOOK_URL`: 送信先 URL
29+
- `RELAY_TRIGGER_WEBHOOK_TOKEN`: 任意の Bearer token
30+
- `RELAY_TRIGGER_EVENT_TYPE`: 既定 `relay.incoming_ref`
31+
- `RELAY_TRIGGER_REF_PREFIXES`: CSV、既定 `refs/relay/incoming/`
32+
33+
送信結果の扱い:
34+
35+
- 2xx は成功
36+
- 非 2xx とネットワークエラーは trigger dispatch failure としてログ記録
37+
38+
## 3. 送信 Webhook Payload
39+
40+
Relay は `POST <RELAY_TRIGGER_WEBHOOK_URL>` に次の JSON を送る:
41+
42+
```json
43+
{
44+
"event_type": "relay.incoming_ref",
45+
"event_id": "evt-...",
46+
"occurred_at": 1700000000,
47+
"room": "main",
48+
"source": "deno:127.0.0.1:8788",
49+
"target": "session:<session_id>",
50+
"ref": "refs/relay/incoming/repo-ci"
51+
}
52+
```
53+
54+
`RELAY_TRIGGER_WEBHOOK_TOKEN` がある場合はヘッダを追加する:
55+
56+
```text
57+
Authorization: Bearer <token>
58+
```
59+
60+
## 4. CI Callback API
61+
62+
外部 CI は次の endpoint に結果を返す:
63+
64+
- `POST /api/v1/trigger/callback`
65+
66+
必須フィールド:
67+
68+
- `ref` (string)
69+
- `status` (string)
70+
71+
任意フィールド:
72+
73+
- `room`
74+
- `logs_url`
75+
- `artifact_url`
76+
- `external_id`
77+
- `provider`
78+
- `id`
79+
80+
room 解決ルール:
81+
82+
- `room` 指定あり: その値を使う
83+
- それ以外で `ref` が `refs/relay/incoming/<room>/...` 形式: 先頭 `<room>` を使う
84+
- どちらでもない: `main` にフォールバック
85+
86+
publish される envelope:
87+
88+
- `topic`: `ci.result`
89+
- `sender`: `ci:callback`
90+
- payload は `ref`, `status`, `logs_url`, `artifact_url`, `external_id`, `provider`, `received_at`
91+
を含む
92+
93+
## 5. CI 結果の取得
94+
95+
次の API で結果を読める:
96+
97+
- `GET /api/v1/trigger/results?room=<room>&after=<cursor>&limit=<n>`
98+
- `GET /api/v1/poll?room=<room>&after=<cursor>&limit=<n>`（room タイムラインに `ci.result`
99+
が含まれる）
100+
101+
## 6. 認証・room token ルール
102+
103+
- `BIT_RELAY_AUTH_TOKEN` 設定時は `/api/v1/trigger/*` に Bearer 認証が必要
104+
- 対象 room に token が設定されている場合、callback/results は `x-room-token` ヘッダまたは
105+
`room_token` クエリが必要
106+
107+
## 7. 動作確認コマンド
108+
109+
既存の統合テストで確認できる:
110+
111+
```bash
112+
deno test --allow-net --allow-env tests/trigger_incoming_ref_integration_test.ts
113+
deno test --allow-net --allow-env tests/trigger_callback_test.ts
114+
```

‎docs/ci-trigger-spec.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# CI Trigger Specification
2+
3+
This document defines the CI trigger flow in bit-relay:
4+
5+
1. Relay receives `refs/relay/incoming/...` through `git-receive-pack`
6+
2. Relay dispatches an external webhook event
7+
3. External CI posts the result back to relay
8+
4. Clients consume CI results from relay APIs
9+
10+
## 1. Trigger Source
11+
12+
Incoming refs are extracted from `POST /git/<session_id>/git-receive-pack` request bodies.
13+
14+
- Matching pattern: `refs/relay/incoming/[A-Za-z0-9._/-]{1,255}`
15+
- Duplicate refs in the same request body are deduplicated
16+
- For each unique incoming ref, relay emits one `incoming_ref` event
17+
18+
## 2. Webhook Dispatch Conditions
19+
20+
Relay dispatches a webhook only when all of the following are true:
21+
22+
- `RELAY_TRIGGER_WEBHOOK_URL` is configured
23+
- Incoming ref matches one of configured prefixes
24+
- Request handling reached the incoming-ref event emission path
25+
26+
Configuration:
27+
28+
- `RELAY_TRIGGER_WEBHOOK_URL`: destination URL
29+
- `RELAY_TRIGGER_WEBHOOK_TOKEN`: optional bearer token
30+
- `RELAY_TRIGGER_EVENT_TYPE`: default `relay.incoming_ref`
31+
- `RELAY_TRIGGER_REF_PREFIXES`: CSV list, default `refs/relay/incoming/`
32+
33+
Dispatch result behavior:
34+
35+
- Any 2xx is treated as success
36+
- Non-2xx or network errors are logged as trigger dispatch failures
37+
38+
## 3. Outbound Webhook Payload
39+
40+
Relay sends `POST <RELAY_TRIGGER_WEBHOOK_URL>` with JSON body:
41+
42+
```json
43+
{
44+
"event_type": "relay.incoming_ref",
45+
"event_id": "evt-...",
46+
"occurred_at": 1700000000,
47+
"room": "main",
48+
"source": "deno:127.0.0.1:8788",
49+
"target": "session:<session_id>",
50+
"ref": "refs/relay/incoming/repo-ci"
51+
}
52+
```
53+
54+
If `RELAY_TRIGGER_WEBHOOK_TOKEN` is set, relay adds:
55+
56+
```text
57+
Authorization: Bearer <token>
58+
```
59+
60+
## 4. CI Callback API
61+
62+
External CI should report results to:
63+
64+
- `POST /api/v1/trigger/callback`
65+
66+
Required fields:
67+
68+
- `ref` (string)
69+
- `status` (string)
70+
71+
Optional fields:
72+
73+
- `room`
74+
- `logs_url`
75+
- `artifact_url`
76+
- `external_id`
77+
- `provider`
78+
- `id`
79+
80+
Room resolution:
81+
82+
- If `room` is provided: use it
83+
- Else if `ref` starts with `refs/relay/incoming/<room>/...`: use that first `<room>` segment
84+
- Else: fallback to `main`
85+
86+
Published envelope:
87+
88+
- `topic`: `ci.result`
89+
- `sender`: `ci:callback`
90+
- payload includes `ref`, `status`, `logs_url`, `artifact_url`, `external_id`, `provider`,
91+
`received_at`
92+
93+
## 5. Reading CI Results
94+
95+
Two APIs are available:
96+
97+
- `GET /api/v1/trigger/results?room=<room>&after=<cursor>&limit=<n>`
98+
- `GET /api/v1/poll?room=<room>&after=<cursor>&limit=<n>` (includes `ci.result` in room timeline)
99+
100+
## 6. Auth and Room Token Rules
101+
102+
- If `BIT_RELAY_AUTH_TOKEN` is configured, `/api/v1/trigger/*` requires Bearer auth
103+
- If a room token is configured for the room, callback/results access must include `x-room-token`
104+
header or `room_token` query param
105+
106+
## 7. Verification Commands
107+
108+
Use the existing integration tests:
109+
110+
```bash
111+
deno test --allow-net --allow-env tests/trigger_incoming_ref_integration_test.ts
112+
deno test --allow-net --allow-env tests/trigger_callback_test.ts
113+
```

‎docs/usage-guide-ja.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -202,6 +202,12 @@ bit relay sync push relay+https://bit-relay.mizchi.workers.dev
202202
| `relay+http://host` | relay API を直接使用（非 TLS、ローカル開発用） |
203203
| `https://host/repo.git` | smart-http を試行、404 時に relay fallback |
204204

205+
## CI トリガーフロー（Incoming Ref）
206+
207+
`refs/relay/incoming/...` の受信、webhook 発火、callback/result API の仕様は以下を参照:
208+
209+
- [CI トリガー仕様](./ci-trigger-spec-ja.md)
210+
205211
## 運用者向け API（キャッシュ/同期）
206212

207213
relay 運用者向けに、issue キャッシュと relay 間交換の確認 API を用意している。

‎docs/usage-guide.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -206,6 +206,12 @@ Once verified, relay sessions use named paths (e.g., `alice/my-repo`) instead of
206206
| `relay+http://host` | Use relay API directly (no TLS, for local dev) |
207207
| `https://host/repo.git` | Try smart-http first, fall back to relay on 404 |
208208

209+
## CI Trigger Flow (Incoming Ref)
210+
211+
For the spec of `refs/relay/incoming/...` handling, webhook dispatch, and callback/result APIs, see:
212+
213+
- [CI Trigger Specification](./ci-trigger-spec.md)
214+
209215
## Full Workflow: Alice and Bob
210216

211217
### Alice (Host)

0 commit comments

Comments
 (0)