이 문서는 examples/live-github-ops 청사진을 실제 GitHub 저장소 운영 절차로 풀어쓴 단계별 가이드입니다.
다음 상황에서 사용합니다.
- fixture 또는 오프라인 데모에서 live GitHub issue polling으로 넘어갈 때
- Codex CLI를 기본 worker runtime으로 유지할 때
- 보수적인 human approval 정책으로 RepoAgents를 연속 운영할 때
- 큰 플랫폼을 만들기 전, 로컬 머신이나 VM, 간단한 프로세스 매니저 위에서 먼저 운영할 때
live 저장소를 건드리기 전에 아래를 확인합니다.
- RepoAgents checkout에서
uv sync --dev가 끝나 있음 codex --version,codex login이 정상 동작함GITHUB_TOKEN이 export되어 있고, issue read 권한과 필요한 경우에만 comment/PR write 권한이 있음- 대상 저장소가 로컬에 clone되어 있고 기준 상태가 깨끗함
- 현재
merge_policy.mode,safety.*설정을 이해하고 있음
보수적인 기본 경로는 다음을 유지하는 것입니다.
llm.mode: codexmerge_policy.mode: human_approvalsafety.allow_write_comments: false또는 엄격히 통제된 상태- dry-run과 단일 issue trigger가 안정적일 때까지
safety.allow_open_pr: false
live 청사진 예제는 아래에 있습니다.
- ../examples/live-github-ops/README.md
- ../examples/live-github-ops/ops/preflight.md
- ../examples/live-github-ops/ops/repoagents.env.example
- ../examples/live-github-ops/ops/build-handoff.sh
- ../examples/live-github-ops/ops/handoff-order.md
- ../examples/live-github-ops/ops/run-loop.sh
- ../examples/live-github-ops/ops/render-dashboard.sh
RepoAgents가 유지보수할 실제 저장소에서 시작합니다.
git clone git@github.com:OWNER/REPO.git
cd REPO
git status --shortworking tree가 이미 dirty 상태면 먼저 정리하거나, 최소한 workspace.dirty_policy를 의도적으로 설정해야 합니다. live 운영에서는 block이 가장 안전합니다.
대상 저장소 내부에서 초기화를 실행합니다.
uv run --project /path/to/RepoAgents repoagents init \
--preset python-library \
--tracker-repo OWNER/REPO저장소 성격이 더 가깝다면 web-app, docs-only, research-project preset을 사용해도 됩니다.
이 단계에서 다음이 생성됩니다.
.ai-repoagents/repoagents.yamlAGENTS.mdWORKFLOW.md.ai-repoagents/roles/.ai-repoagents/prompts/.ai-repoagents/policies/
.ai-repoagents/repoagents.yaml을 열고 아래 값들을 확인합니다.
권장 기본값:
tracker:
kind: github
mode: rest
repo: OWNER/REPO
poll_interval_seconds: 300
workspace:
strategy: worktree
dirty_policy: block
logging:
json: true
file_enabled: true
llm:
mode: codex
merge_policy:
mode: human_approval
safety:
allow_write_comments: false
allow_open_pr: false이 설정을 권장하는 이유:
tracker.mode: rest는 live GitHub adapter를 사용함workspace.strategy: worktree는 큰 저장소에서 더 현실적임logging.file_enabled: true는.ai-repoagents/logs/repoagents.jsonl에 운영 흔적을 남김human_approval은 rollout 초기에 publication과 merge를 보수적으로 유지함
청사진 env 파일을 시작점으로 사용합니다.
cp /path/to/RepoAgents/examples/live-github-ops/ops/repoagents.env.example ./.ai-repoagents/repoagents.env그 다음 shell, direnv, systemd environment, 또는 별도 secrets manager로 실제 값을 주입합니다.
최소 live 환경:
export GITHUB_TOKEN=...Codex CLI가 이미 로컬에서 로그인돼 있다면 Codex 자격 증명을 저장소 안에 둘 필요는 없습니다.
단일 issue도 실행하기 전에 환경을 검증합니다.
uv run --project /path/to/RepoAgents repoagents doctor건강한 경로에서 기대하는 결과:
- config가 정상 로드됨
- Codex command가 실행 가능함
- GitHub auth와 network 체크가 통과함
- runtime 디렉터리에 쓸 수 있음
worktree모드라면 저장소가 유효한 git work tree임- 예상치 못한 managed template drift가 없음
doctor가 깨끗하지 않으면, 경고가 왜 나는지 이해하기 전까지 live 실행으로 넘어가지 않는 편이 안전합니다.
실제 GitHub API를 치기 전에 handoff bundle 모양을 로컬에서 먼저 rehearsal해 두는 편이 좋습니다.
예제 저장소에는 이를 위한 ops/github-smoke.fixture.json이 포함되어 있습니다. 잠시 아래 값을 추가합니다.
tracker:
smoke_fixture_path: ops/github-smoke.fixture.json그 다음 handoff bundle을 생성합니다.
bash /path/to/RepoAgents/examples/live-github-ops/ops/build-handoff.sh이 단계에서 다음이 생성됩니다.
- root
.ai-repoagents/reports/github-smoke.json|md - root
.ai-repoagents/reports/ops-status.json|md - root
.ai-repoagents/reports/ops-brief.json|md - bundle-local
github-smoke.json|md,ops-status.json|md,ops-brief.json|md - bundle landing 파일
index.html,README.md
어떤 파일부터 열어야 하는지는 ../examples/live-github-ops/ops/handoff-order.md에 고정해 둡니다.
실제 live rollout에 들어가기 전에는 tracker.smoke_fixture_path를 다시 제거합니다.
polling loop를 켜기 전에 표적 dry-run을 실행합니다.
uv run --project /path/to/RepoAgents repoagents trigger 123 --dry-run이때 볼 것:
- issue 선택이 맞는지
- role 순서가 맞는지
- planner의
likely_files가 그럴듯한지 - 막힌 side effect가 정책과 일치하는지
- backend가 demo shim이 아니라
codex인지
특정 issue 번호를 아직 고르기 어렵다면, 다음 poll cycle을 보기 위해 repoagents run --dry-run --once도 유용합니다.
dry-run이 깨끗하면 issue 하나만 실제 실행합니다.
uv run --project /path/to/RepoAgents repoagents trigger 123
uv run --project /path/to/RepoAgents repoagents status --issue 123생성된 데이터를 직접 확인합니다.
.ai-repoagents/artifacts/issue-123/<run-id>/아래 artifact.ai-repoagents/workspaces/issue-123/<run-id>/repo/또는 worktree 경로.ai-repoagents/state/runs.json.ai-repoagents/logs/repoagents.jsonl
reviewer나 policy guardrail이 request_changes를 반환해도, rollout 단계에서는 그 자체가 정상적인 안전장치 동작일 수 있습니다.
단일 issue 동작이 예상대로 보이면 loop를 시작합니다.
bash /path/to/RepoAgents/examples/live-github-ops/ops/run-loop.sh이 helper script는 사실상 아래 명령을 감싼 얇은 wrapper입니다.
uv run repoagents run실운영에서는 systemd, launchd, container runtime, 또는 스케줄러가 있는 CI runner 같은 supervisor 아래에서 돌리는 편이 좋습니다.
운영 대시보드는 주기적으로 다시 생성합니다.
bash /path/to/RepoAgents/examples/live-github-ops/ops/render-dashboard.sh또는 직접:
uv run repoagents dashboard --refresh-seconds 30브라우저에서 .ai-repoagents/dashboard/index.html을 열고 다음을 활용합니다.
- 검색으로 특정 issue를 빠르게 찾기
- status filter로 failure/retry만 보기
- 운영 중 페이지를 띄워둘 때 timed refresh 사용하기
가장 덜 파괴적인 복구 경로부터 사용합니다.
실패했거나 retry 대기 중인 issue라면:
uv run repoagents status --issue 123
uv run repoagents retry 123
uv run repoagents trigger 123 --dry-run
uv run repoagents trigger 123workspace 정리가 필요해도 먼저 clean --dry-run을 봅니다.
uv run repoagents clean --dry-run
uv run repoagents clean문제가 GitHub auth, Codex login, rate limit, dirty worktree에 있다면 그 원인을 먼저 해결한 뒤 issue를 다시 실행합니다.
첫날부터 comment나 draft PR을 열 필요는 없습니다.
권장 rollout:
allow_write_comments: false,allow_open_pr: false로 시작- 단일 issue run이 여러 번 안정적으로 끝난 뒤 issue comment 허용 검토
- reviewer와 policy 동작이 안정적일 때만
allow_open_pr: true검토 - draft PR 생성이 열려 있어도 merge는 계속 사람이 수행
MVP rollout에서는 polling만으로도 충분하지만, 더 빠른 반응이 필요하면 webhook 경로를 붙일 수 있습니다.
관련 경로:
live receiver에 붙이기 전에는 다음으로 payload를 검증합니다.
uv run repoagents webhook --event issues --payload webhook.json --dry-run실운영 전환 전에는 아래를 확인합니다.
doctor가 깨끗함- 최소 1번의
trigger --dry-run과 1번의trigger가 성공적으로 끝남 - operator가 artifact와 로그를 읽을 수 있음
- dashboard가 정상 렌더링됨
dirty_policy, publication policy, safety flag가 저장소 리스크에 맞음- RepoAgents가
request_changes를 낼 때 사람이 어떻게 판단할지 경로가 명확함