sync: agent-contract & agent-test updates
This commit is contained in:
parent
c1f6ba43e7
commit
a0bafceae9
4 changed files with 96 additions and 14 deletions
|
|
@ -6,9 +6,9 @@
|
||||||
|
|
||||||
## 제공 계약
|
## 제공 계약
|
||||||
|
|
||||||
| id | 읽는 조건 | path |
|
| id | 읽는 조건 | path |
|
||||||
| --- | --- | --- |
|
| ---------------------------------| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ------------------------------------------------------------|
|
||||||
| `gito.forgejo-branch-events.v1` | Forgejo webhook, `branch.updated`, outbound HTTP webhook delivery, nomadcode branch event wakeup, `/callbacks/forgejo/push`, `/api/listeners/branches`, `/api/webhook-subscriptions` | `agent-contract/provided/gito-forgejo-branch-events-v1.md` |
|
| `gito.forgejo-branch-events.v1` | Forgejo webhook, `branch.updated`, outbound HTTP webhook delivery, NomadCode branch event wakeup, Gito local/dev port profiles `18060/18061`, NomadCode webhook targets `18010/18011`, `/callbacks/forgejo/push`, `/api/listeners/branches`, `/api/webhook-subscriptions` | `agent-contract/provided/gito-forgejo-branch-events-v1.md` |
|
||||||
|
|
||||||
## 소비 계약
|
## 소비 계약
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -12,6 +12,17 @@
|
||||||
- proto-socket은 Gito 내부 control/runtime transport이며 이 외부 계약의 일부가 아니다.
|
- proto-socket은 Gito 내부 control/runtime transport이며 이 외부 계약의 일부가 아니다.
|
||||||
- gRPC는 이 계약 범위가 아니다.
|
- gRPC는 이 계약 범위가 아니다.
|
||||||
|
|
||||||
|
## Environment Port Profiles
|
||||||
|
|
||||||
|
포트 profile은 원격 host에서 local용 환경과 dev용 환경을 동시에 분리 운영하기 위한 기본값이다. API path, headers, request/response schema는 profile과 무관하게 동일하다.
|
||||||
|
|
||||||
|
| Profile | Gito base URL | NomadCode webhook target | Preview | Optional wire | DB/cache 후보 |
|
||||||
|
| --- | --- | --- | ---: | ---: | ---: |
|
||||||
|
| remote local | `http://127.0.0.1:18060` | `http://127.0.0.1:18010/api/integrations/gito/webhook` | `13060` | `19060` | `15460/16360` |
|
||||||
|
| remote dev | `http://127.0.0.1:18061` | `http://127.0.0.1:18011/api/integrations/gito/webhook` | `13061` | `19061` | `15461/16361` |
|
||||||
|
|
||||||
|
Gito Core process/container 내부 listen 포트는 제품 기본값 `8080`을 유지할 수 있다. workspace 충돌 관리는 host publish 또는 direct smoke 포트(`18060`/`18061`)에서 처리한다. IOP dev model endpoint `http://toki-labs.com:18083/v1`은 NomadCode 실행 의존성이지 Gito-owned port가 아니다.
|
||||||
|
|
||||||
## REST Callback
|
## REST Callback
|
||||||
|
|
||||||
### `POST /callbacks/forgejo/push`
|
### `POST /callbacks/forgejo/push`
|
||||||
|
|
@ -156,7 +167,7 @@ Request:
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"name": "nomadcode-develop-wakeup",
|
"name": "nomadcode-develop-wakeup",
|
||||||
"target_url": "https://consumer.example.invalid/gito/events",
|
"target_url": "http://127.0.0.1:18010/api/integrations/gito/webhook",
|
||||||
"events": ["branch.updated"],
|
"events": ["branch.updated"],
|
||||||
"repo_id": "nomadcode",
|
"repo_id": "nomadcode",
|
||||||
"branch": "develop",
|
"branch": "develop",
|
||||||
|
|
@ -179,8 +190,7 @@ Response:
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
`target_url` and `secret_ref` are examples only. Raw signing secrets, tokens, or
|
`target_url`은 remote local profile 예시다. remote dev profile에서는 `http://127.0.0.1:18011/api/integrations/gito/webhook`을 사용한다. `secret_ref`는 예시 참조값이며 raw signing secrets, tokens, or private endpoint values must not be stored in tracked docs.
|
||||||
private endpoint values must not be stored in tracked docs.
|
|
||||||
|
|
||||||
## Event Inspection
|
## Event Inspection
|
||||||
|
|
||||||
|
|
@ -332,6 +342,8 @@ NomadCode 또는 다른 consumer가 Gito branch event webhook delivery를 연동
|
||||||
|
|
||||||
listener bootstrap, webhook subscription, `/api/listeners/branches`, `/api/events`를 secret 없이 재현 가능하게 확인하는 절차다.
|
listener bootstrap, webhook subscription, `/api/listeners/branches`, `/api/events`를 secret 없이 재현 가능하게 확인하는 절차다.
|
||||||
|
|
||||||
|
예시는 remote local profile 기준이다. remote dev profile에서는 `GITO_BASE_URL=http://127.0.0.1:18061`, `GITO_NOMADCODE_TARGET_URL=http://127.0.0.1:18011/api/integrations/gito/webhook`으로 바꾼다.
|
||||||
|
|
||||||
### 필요한 환경 변수
|
### 필요한 환경 변수
|
||||||
|
|
||||||
| 변수 | 필수 | 기본값 | 설명 |
|
| 변수 | 필수 | 기본값 | 설명 |
|
||||||
|
|
@ -339,13 +351,20 @@ listener bootstrap, webhook subscription, `/api/listeners/branches`, `/api/event
|
||||||
| `APP_ENV` | 아니오 | `development` | 앱 환경 |
|
| `APP_ENV` | 아니오 | `development` | 앱 환경 |
|
||||||
| `FORGEJO_WEBHOOK_SECRET` | 아니오 | (없으면 서명 검증 생략) | Forgejo webhook 서명 키 |
|
| `FORGEJO_WEBHOOK_SECRET` | 아니오 | (없으면 서명 검증 생략) | Forgejo webhook 서명 키 |
|
||||||
| `DATABASE_URL` | 아니오 | (없으면 in-memory) | PostgreSQL DSN |
|
| `DATABASE_URL` | 아니오 | (없으면 in-memory) | PostgreSQL DSN |
|
||||||
|
| `GITO_BASE_URL` | 아니오 | `http://127.0.0.1:18060` | Gito profile별 base URL |
|
||||||
|
| `GITO_NOMADCODE_TARGET_URL` | 아니오 | `http://127.0.0.1:18010/api/integrations/gito/webhook` | NomadCode consumer endpoint |
|
||||||
|
|
||||||
기본 smoke는 `FORGEJO_WEBHOOK_SECRET`과 `DATABASE_URL` 없이 실행할 수 있다.
|
기본 smoke는 `FORGEJO_WEBHOOK_SECRET`과 `DATABASE_URL` 없이 실행할 수 있다.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
GITO_BASE_URL="${GITO_BASE_URL:-http://127.0.0.1:18060}"
|
||||||
|
GITO_NOMADCODE_TARGET_URL="${GITO_NOMADCODE_TARGET_URL:-http://127.0.0.1:18010/api/integrations/gito/webhook}"
|
||||||
|
```
|
||||||
|
|
||||||
### Step 1 — Branch watch 등록
|
### Step 1 — Branch watch 등록
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
curl -s -X POST http://localhost:8080/api/listeners/branches \
|
curl -s -X POST "$GITO_BASE_URL/api/listeners/branches" \
|
||||||
-H "Content-Type: application/json" \
|
-H "Content-Type: application/json" \
|
||||||
-d '{"repo_id":"nomadcode","branch":"develop","provider":"forgejo"}'
|
-d '{"repo_id":"nomadcode","branch":"develop","provider":"forgejo"}'
|
||||||
```
|
```
|
||||||
|
|
@ -355,15 +374,15 @@ curl -s -X POST http://localhost:8080/api/listeners/branches \
|
||||||
### Step 2 — 등록된 watch 목록 확인
|
### Step 2 — 등록된 watch 목록 확인
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
curl -s http://localhost:8080/api/listeners/branches
|
curl -s "$GITO_BASE_URL/api/listeners/branches"
|
||||||
```
|
```
|
||||||
|
|
||||||
### Step 3 — webhook subscription 등록
|
### Step 3 — webhook subscription 등록
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
curl -s -X POST http://localhost:8080/api/webhook-subscriptions \
|
curl -s -X POST "$GITO_BASE_URL/api/webhook-subscriptions" \
|
||||||
-H "Content-Type: application/json" \
|
-H "Content-Type: application/json" \
|
||||||
-d '{"name":"nomadcode-develop-wakeup","target_url":"https://consumer.example.invalid/gito/events","events":["branch.updated"],"repo_id":"nomadcode","branch":"develop","secret_ref":"secret://gito/webhooks/nomadcode"}'
|
-d "{\"name\":\"nomadcode-develop-wakeup\",\"target_url\":\"$GITO_NOMADCODE_TARGET_URL\",\"events\":[\"branch.updated\"],\"repo_id\":\"nomadcode\",\"branch\":\"develop\",\"secret_ref\":\"secret://gito/webhooks/nomadcode\"}"
|
||||||
```
|
```
|
||||||
|
|
||||||
기대 응답: `201 Created`, `{"subscription": {...}}`
|
기대 응답: `201 Created`, `{"subscription": {...}}`
|
||||||
|
|
@ -380,7 +399,7 @@ cd services/core && go test -run TestWebhookDeliveryBranchUpdated ./internal/con
|
||||||
### Step 5 — Forgejo push 트리거 (서명 없는 경우)
|
### Step 5 — Forgejo push 트리거 (서명 없는 경우)
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
curl -s -X POST "http://localhost:8080/callbacks/forgejo/push?repo_id=nomadcode" \
|
curl -s -X POST "$GITO_BASE_URL/callbacks/forgejo/push?repo_id=nomadcode" \
|
||||||
-H "Content-Type: application/json" \
|
-H "Content-Type: application/json" \
|
||||||
-H "X-Forgejo-Event: push" \
|
-H "X-Forgejo-Event: push" \
|
||||||
-H "X-Forgejo-Delivery: smoke-delivery-1" \
|
-H "X-Forgejo-Delivery: smoke-delivery-1" \
|
||||||
|
|
@ -392,7 +411,7 @@ curl -s -X POST "http://localhost:8080/callbacks/forgejo/push?repo_id=nomadcode"
|
||||||
### Step 6 — 발행된 event 확인
|
### Step 6 — 발행된 event 확인
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
curl -s http://localhost:8080/api/events
|
curl -s "$GITO_BASE_URL/api/events"
|
||||||
```
|
```
|
||||||
|
|
||||||
기대 응답에 `"type":"branch.updated"`, `"before":"old-sha"`, `"after":"new-sha"`, `changed_files`가 포함된다.
|
기대 응답에 `"type":"branch.updated"`, `"before":"old-sha"`, `"after":"new-sha"`, `changed_files`가 포함된다.
|
||||||
|
|
|
||||||
63
agent-test/dev/rules.md
Normal file
63
agent-test/dev/rules.md
Normal file
|
|
@ -0,0 +1,63 @@
|
||||||
|
---
|
||||||
|
test_env: dev
|
||||||
|
last_rule_updated_at: 2026-07-01
|
||||||
|
---
|
||||||
|
|
||||||
|
# dev 테스트 규칙
|
||||||
|
|
||||||
|
**현재 문서를 반드시 끝까지 정독하고 작업한다. 다 읽지 않고 즉각 작업은 금지한다.**
|
||||||
|
**dev 환경은 remote local profile과 같은 host에서 분리 운영하는 Gito/NomadCode 연동 검증용 profile이다.**
|
||||||
|
|
||||||
|
## 공통 규칙
|
||||||
|
|
||||||
|
- dev 테스트/검증은 이 파일을 기준으로 판단한다.
|
||||||
|
- 원격 host에서 local profile 포트와 dev profile 포트를 동시에 띄울 수 있어야 한다.
|
||||||
|
- 환경값, secret, private endpoint 원문은 tracked docs/roadmap/task log/최종 응답에 기록하지 않는다.
|
||||||
|
- raw token, password, webhook secret, provider credential, private key는 ignored local profile 또는 remote secret store에서만 주입한다.
|
||||||
|
- 컨테이너 내부 listen 포트는 제품 기본값을 우선 유지하고, workspace 충돌 관리는 host publish/direct smoke 포트로 처리한다.
|
||||||
|
- 테스트용 Docker subnet을 새로 만들 때는 `192.168.0.0/24` 대역을 사용하지 않는다.
|
||||||
|
|
||||||
|
## 기본 환경
|
||||||
|
|
||||||
|
- host: standard remote runner `toki@toki-labs.com`.
|
||||||
|
- checkout: dev profile은 `$HOME/agent-work/gito-dev`를 기준으로 둔다. 아직 없으면 현재 검증 대상 branch/commit으로 생성 또는 동기화한 뒤 사용한다.
|
||||||
|
- runtime: repo root helper(`bin/test`, `bin/lint`, `bin/build`)와 변경 범위별 Go, Flutter/Dart toolchain.
|
||||||
|
- package manager: Go modules, Flutter pub.
|
||||||
|
- docker: 별도 compose를 추가하거나 복제할 때는 project/network 이름을 local profile과 분리하고 host publish 기본값을 `GITO_CORE_HOST_PORT=18061`, `GITO_POSTGRES_HOST_PORT=15461`, `GITO_REDIS_HOST_PORT=16361` 계열로 둔다.
|
||||||
|
- external service: Forgejo/Gitea/GitHub/GitLab/Jira/IOP 같은 provider 또는 runner 연동은 도메인/검증 시나리오별 문서가 명시한 경우에만 사용한다.
|
||||||
|
- credential: ignored local file 또는 `credential_ref` only.
|
||||||
|
|
||||||
|
## 포트 매핑
|
||||||
|
|
||||||
|
| 용도 | local profile | dev profile |
|
||||||
|
| --- | ---: | ---: |
|
||||||
|
| Flutter/project preview | `13060` | `13061` |
|
||||||
|
| Gito Core HTTP host publish/direct smoke | `18060` | `18061` |
|
||||||
|
| optional proto-socket/agent transport | `19060` | `19061` |
|
||||||
|
| PostgreSQL host publish 후보 | `15460` | `15461` |
|
||||||
|
| Redis host publish 후보 | `16360` | `16361` |
|
||||||
|
| NomadCode webhook consumer target | `18010` | `18011` |
|
||||||
|
|
||||||
|
dev Gito의 NomadCode delivery target은 `http://127.0.0.1:18011/api/integrations/gito/webhook`이다. local profile target은 `http://127.0.0.1:18010/api/integrations/gito/webhook`으로 유지한다.
|
||||||
|
|
||||||
|
## Gito-NomadCode 연동 기준
|
||||||
|
|
||||||
|
- Gito provider intake는 dev profile에서 `http://127.0.0.1:18061/callbacks/forgejo/push`를 기준으로 검증한다.
|
||||||
|
- branch watch 등록은 `POST http://127.0.0.1:18061/api/listeners/branches`로 수행한다.
|
||||||
|
- webhook subscription은 event `branch.updated`, repo `nomadcode`, branch `develop`, target URL `http://127.0.0.1:18011/api/integrations/gito/webhook`을 기준으로 한다.
|
||||||
|
- signing secret 원문은 `secret_ref` 또는 ignored local profile에만 두고 tracked 문서에는 쓰지 않는다.
|
||||||
|
- 계약 원문은 `agent-contract/provided/gito-forgejo-branch-events-v1.md`를 따른다.
|
||||||
|
|
||||||
|
## 라우팅
|
||||||
|
|
||||||
|
- workspace-ops / smoke / root helpers, docs, agent rules, roadmap, local/dev test rules: `agent-test/local/workspace-ops-smoke.md`
|
||||||
|
- core / smoke / services/core backend, control plane, worker, shell baseline: `agent-test/local/core-smoke.md`
|
||||||
|
- contracts / smoke / packages/contracts and agent-contract notes baseline: `agent-test/local/contracts-smoke.md`
|
||||||
|
- client / smoke / apps/client Flutter control surface baseline: `agent-test/local/client-smoke.md`
|
||||||
|
|
||||||
|
## 라우팅 규칙
|
||||||
|
|
||||||
|
- 여러 항목이 맞으면 모두 읽는다.
|
||||||
|
- 도메인 매핑이나 domain rule이 있으면 각 도메인의 `<domain>-smoke` 문서를 기본 baseline으로 둔다.
|
||||||
|
- 도메인이 아직 없을 때만 `project-smoke`를 fallback baseline으로 둔다.
|
||||||
|
- 도메인/검증 시나리오별 문서는 다른 테스트 문서로 라우팅하지 않는다.
|
||||||
|
|
@ -1,6 +1,6 @@
|
||||||
---
|
---
|
||||||
test_env: local
|
test_env: local
|
||||||
last_rule_updated_at: 2026-06-14
|
last_rule_updated_at: 2026-07-01
|
||||||
---
|
---
|
||||||
|
|
||||||
# local 테스트 규칙
|
# local 테스트 규칙
|
||||||
|
|
@ -24,7 +24,7 @@ last_rule_updated_at: 2026-06-14
|
||||||
## 기본 환경
|
## 기본 환경
|
||||||
|
|
||||||
- host: standard remote runner `toki@toki-labs.com`, code-server compose checkout. Host path is `$HOME/docker/services/code-server/data/volume/workspace/gito`; container path is `/config/workspace/gito`. `$HOME/agent-work/gito` is not the baseline checkout for gito.
|
- host: standard remote runner `toki@toki-labs.com`, code-server compose checkout. Host path is `$HOME/docker/services/code-server/data/volume/workspace/gito`; container path is `/config/workspace/gito`. `$HOME/agent-work/gito` is not the baseline checkout for gito.
|
||||||
- port: Flutter/project preview는 `13060`, Core HTTP host publish 또는 direct smoke는 `18060`을 쓴다. Core process/container 내부 기본 listen은 `8080`으로 유지하고, `127.0.0.1:8080`은 명시적 product compatibility 확인에만 사용한다. proto-socket/agent transport를 Core HTTP와 분리해 host publish해야 할 때는 `19060`을 gito-owned 후보로 쓴다. code-server service 자체는 `$HOME/docker/services/code-server/compose/docker-compose.yml`가 관리하며, gito 테스트 포트로 재정의하지 않는다. PostgreSQL/Redis는 기본적으로 같은 compose의 internal service(`code-server-postgres:5432`, `code-server-redis:6379`)를 사용하고, 별도 host publish가 필요할 때만 `15460/16360` 후보를 쓴다.
|
- port: remote local profile은 Flutter/project preview `13060`, Core HTTP host publish 또는 direct smoke `18060`, optional proto-socket/agent transport `19060`, PostgreSQL/Redis host publish 후보 `15460/16360`을 쓴다. Core process/container 내부 기본 listen은 `8080`으로 유지하고, `127.0.0.1:8080`은 명시적 product compatibility 확인에만 사용한다. NomadCode local consumer target은 `http://127.0.0.1:18010/api/integrations/gito/webhook`이다. dev profile은 `agent-test/dev/rules.md`의 `13061/18061/19061/15461/16361`과 NomadCode dev `18011`을 사용한다. code-server service 자체는 `$HOME/docker/services/code-server/compose/docker-compose.yml`가 관리하며, gito 테스트 포트로 재정의하지 않는다.
|
||||||
- runtime: repo root helper(`bin/test`, `bin/lint`, `bin/build`)와 변경 범위별 Go, Flutter/Dart toolchain.
|
- runtime: repo root helper(`bin/test`, `bin/lint`, `bin/build`)와 변경 범위별 Go, Flutter/Dart toolchain.
|
||||||
- package manager: Go modules, Flutter pub.
|
- package manager: Go modules, Flutter pub.
|
||||||
- docker: 기본 runner는 `$HOME/docker/services/code-server/compose/docker-compose.yml`의 `code-server`, `code-server-postgres`, `code-server-redis`를 사용한다. 비대화형 ssh에서 Docker CLI가 PATH에 없으면 `/usr/local/bin/docker`를 사용한다. gito 전용 DB 검증은 `code-server-postgres`에 `gito_test` DB를 만들고, code-server 컨테이너의 `DATABASE_URL`에서 DB 이름만 `gito_test`로 바꿔 `GITO_TEST_DATABASE_URL`에 주입한다. raw DSN/password는 출력하거나 tracked 파일에 기록하지 않는다. 별도 compose를 추가하거나 복제할 때는 project/network 이름을 `gito`로 분리하고 host publish 기본값을 `GITO_CORE_HOST_PORT=18060`, `GITO_POSTGRES_HOST_PORT=15460`, `GITO_REDIS_HOST_PORT=16360` 계열로 둔다.
|
- docker: 기본 runner는 `$HOME/docker/services/code-server/compose/docker-compose.yml`의 `code-server`, `code-server-postgres`, `code-server-redis`를 사용한다. 비대화형 ssh에서 Docker CLI가 PATH에 없으면 `/usr/local/bin/docker`를 사용한다. gito 전용 DB 검증은 `code-server-postgres`에 `gito_test` DB를 만들고, code-server 컨테이너의 `DATABASE_URL`에서 DB 이름만 `gito_test`로 바꿔 `GITO_TEST_DATABASE_URL`에 주입한다. raw DSN/password는 출력하거나 tracked 파일에 기록하지 않는다. 별도 compose를 추가하거나 복제할 때는 project/network 이름을 `gito`로 분리하고 host publish 기본값을 `GITO_CORE_HOST_PORT=18060`, `GITO_POSTGRES_HOST_PORT=15460`, `GITO_REDIS_HOST_PORT=16360` 계열로 둔다.
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue