---
test_env: dev
last_rule_updated_at: 2026-07-03
---

# dev 테스트 규칙

**현재 문서를 반드시 끝까지 정독하고 작업한다. 다 읽지 않고 즉각 작업은 금지한다.**
**dev 환경은 remote local profile과 같은 host에서 분리 운영하는 NomadCode/Gito 연동 검증용 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` 대역을 사용하지 않는다.
- Plane-origin full-cycle 검증은 `agent-test/live-cycle-smoke.md`를 따른다. 수동 Gito redelivery는 진단/복구 근거일 뿐 자동 Forgejo -> Gito 경로 통과 근거로 기록하지 않는다.

## 기본 환경

- host: standard remote runner `toki@toki-labs.com`.
- checkout: dev profile은 `$HOME/agent-work/nomadcode-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는 Core 내부 listen `8080`을 유지하고 host publish를 `NOMADCODE_CORE_HOST_PORT=18011`로 둔다. 별도 DB/cache host publish가 필요할 때만 `15411/16311` 후보를 사용한다.
- external service: Mattermost, FCM, Plane, Gito 등 도메인/검증 시나리오별 문서가 명시한 서비스만 사용한다.
- model endpoint: 기본 IOP dev dependency는 `http://toki-labs.com:18083/v1`이다. 이 포트는 NomadCode-owned slot이 아니며 IOP dev 환경이 소유한다.
- credential: ignored local file only.

## 포트 매핑

| 용도 | local profile | dev profile |
| --- | ---: | ---: |
| Flutter/code-server preview | `13010` | `13011` |
| NomadCode Core host publish | `18010:8080` | `18011:8080` |
| PostgreSQL host publish 후보 | `15410` | `15411` |
| Redis host publish 후보 | `16310` | `16311` |
| Gito delivery source | `18060` | `18061` |

dev NomadCode의 Gito webhook 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 Webhook Consumer 기준

- consumer endpoint는 `POST /api/integrations/gito/webhook`이다.
- dev Gito base URL은 `http://127.0.0.1:18061`이고 subscription target은 `http://127.0.0.1:18011/api/integrations/gito/webhook`이다.
- consumer enablement에는 `GITO_WEBHOOK_SECRET`, `GITO_REPO_ID`, `GITO_DEVELOP_REPO_PATH`, `ROADMAP_CREATION_TODO_STATE_ID` 또는 `PLANE_TODO_STATE_ID`가 필요하다.
- `GITO_BRANCH` 기본값은 `develop`, `GITO_REMOTE_NAME` 기본값은 `origin`이다.
- `GITO_DEVELOP_REPO_PATH`는 Core container에서 접근 가능한 checkout path여야 한다.
- 계약 원문은 `agent-contract/outer/gito-branch-webhook-consumer-v1.md`와 Gito 제공 계약 `../gito/agent-contract/provided/gito-forgejo-branch-events-v1.md`를 함께 따른다.

## Forgejo -> Gito Webhook 기준

- dev Forgejo repository hook이 host Gito dev port로 delivery할 때 target은 `http://host.docker.internal:18061/callbacks/forgejo/push?repo_id=nomadcode` 형태일 수 있다.
- 이 경우 Forgejo app config `[webhook] ALLOWED_HOST_LIST`에는 기존 허용 host와 함께 `host.docker.internal`이 포함되어야 한다.
- allowlist가 막히면 Forgejo `hook_task.response_content`에 `webhook can only call allowed HTTP servers`가 남고, Core task는 git push 후 `develop_match` 대기에서 멈출 수 있다.
- allowlist를 조정할 때는 config 백업을 먼저 만들고, raw secret이나 token 값은 조회/출력/기록하지 않는다.
- Forgejo 컨테이너에서 `curl http://host.docker.internal:18061/healthz`가 성공해야 provider callback 네트워크가 열린 것으로 본다.

## 라우팅

- core / full-cycle / Plane-origin milestone authoring, git develop push, Forgejo/Gito branch.updated, Plane Todo projection: `agent-test/live-cycle-smoke.md`
- core / smoke / services/core backend baseline: `agent-test/local/core-smoke.md`
- mobile / smoke / apps/client Flutter baseline: `agent-test/local/mobile-smoke.md`
- mobile / smoke / Android SDK remote runner and debug APK validation: `agent-test/local/mobile-android-sdk-smoke.md`
- mobile / smoke / Mattermost server-generated signed push, Nexo parity, Android remote push evidence: `agent-test/local/mattermost-server-generated-push-smoke.md`
- contracts / smoke / packages/contracts contract docs/schema baseline: `agent-test/local/contracts-smoke.md`
- workspace-ops / smoke / root helpers, docs, agent rules, roadmap baseline: `agent-test/local/workspace-ops-smoke.md`

## 라우팅 규칙

- 여러 항목이 맞으면 모두 읽는다.
- 도메인 매핑이나 domain rule이 있으면 각 도메인의 `<domain>-smoke` 문서를 기본 baseline으로 둔다.
- 도메인이 아직 없을 때만 `project-smoke`를 fallback baseline으로 둔다.
- 도메인/검증 시나리오별 문서는 다른 테스트 문서로 라우팅하지 않는다.
