워크스루: 두 머신과 CI가 판정을 공유하기
이 실습에서는 examples/runtime-relations 예제 프로젝트를 사용합니다.
Alice와 Bob은 서로 다른 체크아웃과 상태 디렉터리를 씁니다. CI에는 세 번째
체크아웃이 있습니다. artifactize server 하나가 공유 판정을 보관합니다. 모든
단계를 머신 한 대에서 실행할 수 있습니다. 이 실습에서는 --state-dir로 상태 디렉터리를
달리 지정해 각 “머신“을 구분하고, USER로 결과를 만든 사람의 이름을 정합니다. Linux, macOS, WSL에서 POSIX 셸을 연 다음, examples/가 있는 artifactize 저장소
(git clone https://github.com/lhj6102/artifactize)의
루트 디렉터리에서 아래 명령을 실행하세요.
export WALK=$(mktemp -d) # outside any Git checkout
cp -r examples/runtime-relations "$WALK/alice"
cp -r examples/runtime-relations "$WALK/bob"
printf 'WALK directory: %s\n' "$WALK"
mktemp -d로 체크아웃 밖에 새 임시 폴더를 만듭니다. 생성된 폴더의 경로는 WALK에 저장되며 마지막 명령으로 출력됩니다. 출력된 WALK 경로를 복사해 두세요.
서버, Alice, Bob, 로컬 CI 시연에는 각각 별도의 터미널을 쓰세요.
새 터미널마다 다음을 실행하되, COPIED_WALK_PATH를 방금 출력된
절대 경로로 바꾸세요.
export WALK="COPIED_WALK_PATH"
한 터미널에서 export해도 다른 터미널의 변수는 설정되지 않습니다.
mktemp를 다시 실행하지 마세요. 이 로컬 예제는 모두 같은 폴더를 써야 합니다. 아래
출력은 Alice/Bob 역할을 보여 주는 예이며, 실제 Run ID와 user/host 라벨은
다릅니다.
1. 서버
저장소를 실행하는 호스트에서 머신마다 토큰을 하나씩 만드세요. token add는
각 토큰을 한 번만 출력하며 다시 볼 수 없으니, 그때 저장해 두세요.
artifactize --state-dir "$WALK/server" server token add alice-laptop --scopes read,publish,human
artifactize --state-dir "$WALK/server" server token add bob-laptop --scopes read,publish
artifactize --state-dir "$WALK/server" server token add ci --scopes read
artifactize --state-dir "$WALK/server" server run # Listening on http://127.0.0.1:8417/
server run은 별도 터미널에서 계속 실행해 두세요. 이 실습에서는 같은 머신에서
실행되는 프로그램끼리만 연결합니다. 서로 다른 머신에서 실행한다면 먼저
안전한 연결 설정을 따르세요.
2. Alice가 먼저 리뷰하기
Alice를 위한 두 번째 터미널을 여세요. 첫 번째 터미널에서는 서버가 계속 실행됩니다.
export WALK='/path/from/setup'
cd "$WALK/alice"
export ARTIFACTIZE_STATE_HOME="$WALK/state-alice"
artifactize remote login http://127.0.0.1:8417/ # paste alice-laptop's token; input is hidden when supported
artifactize verify --all --wait
guide/terms [run-FBh4xF-1]: GREEN
intro/heading [run-FBh4xF-2]: GREEN
usage/heading [run-FBh4xF-3]: GREEN
Summary: executed 3 (runtime 3, agent 0, human 0), reused 0 (runtime 0, agent 0, human 0)
verify는 각 결과의 fingerprint를 다시 확인한 뒤 GREEN으로 판정했으므로, 판정, 추가 결과 필드, 프로필, 사용량 카운터, 만든 사람, 타임스탬프를 담은 요약 기록을 게시했습니다.
요약에는 캡처한 stdout/stderr, 별도의 호출 감사 기록,
로컬 저장소 출처가 빠졌습니다. 선언된 Runtime 명령과 인자는
프로필의 일부로 공유되었으며, 그 인자 안의 경로와 민감한 리터럴은
가려지지 않습니다.
3. Bob이 Alice의 판정 재사용하기
Bob을 위한 세 번째 터미널을 열고, 앞에서 복사해 둔 것과 같은 디렉터리 경로를 설정하세요.
export WALK='/path/from/setup'
cd "$WALK/bob"
export ARTIFACTIZE_STATE_HOME="$WALK/state-bob"
artifactize remote login http://127.0.0.1:8417/ # bob-laptop's token
artifactize status | tail -1
artifactize verify --all --wait
Verify actions: will execute 0, will reuse 3, wait 0, blocked 0
guide/terms [run-MxxJJJ-1]: GREEN (reused from remote: alice@laptop, run-FBh4xF)
intro/heading [run-MxxJJJ-2]: GREEN (reused from remote: alice@laptop, run-FBh4xF)
usage/heading [run-MxxJJJ-3]: GREEN (reused from remote: alice@laptop, run-FBh4xF)
Summary: executed 0 (runtime 0, agent 0, human 0), reused 3 (runtime 3, agent 0, human 0)
Bob의 체크아웃에서도 Artifact의 이름·종류·내용이 Alice의 체크아웃과 같으므로 fingerprint와 eval 정의 해시, 재사용 키가 모두 일치합니다. 경로는 상관없습니다. status는 Bob의 로컬 상태를 바꾸지 않고
저장소를 조회했으며, 저장소에서는 이 조회도 기록을 사용한 것으로 집계합니다. verify는 세 기록을 Bob의 로컬 캐시에 미러링했습니다.
artifactize cache list가 저장소를 출처로 하는 그 기록을 보여 줍니다. 이후의
verify는 저장소가 없어도 그 기록을 로컬에서 재사용합니다.
4. Bob이 오프라인으로 작업한 뒤 푸시하기
Bob의 터미널에서 작업 디렉터리를 $WALK/bob으로 유지한 채 다음 명령을 실행하세요.
printf 'Nothing unchanged is reviewed twice.\n' >> guide/usage/page.md
ARTIFACTIZE_REMOTE=off artifactize verify --all --wait
artifactize remote push --dry-run
artifactize remote push
guide/terms [run-PzLGma-1]: GREEN
intro/heading [run-PzLGma-2]: GREEN (reused from remote: alice@laptop, run-FBh4xF)
usage/heading [run-PzLGma-3]: GREEN
Summary: executed 2 (runtime 2, agent 0, human 0), reused 1 (runtime 1, agent 0, human 0)
Would push 2, already in the store 0, skipped 0.
Pushed 2, already in the store 0, skipped 0.
guide/terms는 usage를 참조하므로 재사용 키에 usage가 들어 있습니다. 그래서 다시 리뷰한 Artifact는 usage와 guide뿐입니다.
저장소 연동을 off로 끈 것이 아니라 저장소에 연결할 수 없는 상황이었더라도, verify는 한 번 경고한 뒤
같은 방식으로 로컬에서 리뷰했을 것입니다. remote push는 각 키에 대해 저장소에
아직 없는 가장 최근 로컬 결과를 보냅니다. 미러링한 기록은 보내지 않으며, 토큰에 human이 없으면
Human 승인은 건너뜁니다.
5. CI가 둘 다 재사용하기
CI 설정은 환경 변수로만 합니다. 1단계의 읽기 전용 ci 토큰을 쓰며,
여기서는 CI_TOKEN 변수로 전달합니다. 토큰은 커밋한 파일이 아니라 CI 시크릿으로 등록하세요. --reuse-only agent,human을 쓰면 Agent 리뷰와 Human 승인은 저장소나 캐시에 있는 결과만 재사용합니다.
로컬 시연에서는 먼저 이 터미널에도 WALK를 복사하고,
1단계에서 server token add ci가 출력한 토큰을 CI_TOKEN으로 붙여 넣으세요.
export WALK='/path/from/setup'
export CI_TOKEN='token-printed-for-ci'
cp -r "$WALK/bob" "$WALK/ci" && cd "$WALK/ci"
ARTIFACTIZE_STATE_HOME="$WALK/state-ci" \
ARTIFACTIZE_REMOTE=http://127.0.0.1:8417/ \
ARTIFACTIZE_REMOTE_TOKEN="$CI_TOKEN" \
artifactize verify --all --wait --reuse-only agent,human
guide/terms [run-GpqdSQ-1]: GREEN (reused from remote: bob@laptop, run-PzLGma)
intro/heading [run-GpqdSQ-2]: GREEN (reused from remote: alice@laptop, run-FBh4xF)
usage/heading [run-GpqdSQ-3]: GREEN (reused from remote: bob@laptop, run-PzLGma)
Summary: executed 0 (runtime 0, agent 0, human 0), reused 3 (runtime 3, agent 0, human 0)
CI는 아무것도 실행하지 않았습니다. 읽기 토큰으로는 결과를 게시할 수 없으므로, CI에서 만든 결과는 CI의 로컬 상태에만 남습니다. 서버를 멈추고 새 상태 디렉터리로 같은 명령을 실행해 보세요. 저장소에 연결할 수 없으므로 CI는 로컬에서 리뷰하고 계속 통과합니다.
Remote store is unreachable: Connection refused (os error 111); continuing without the remote review store.
Summary: executed 3 (runtime 3, agent 0, human 0), reused 0 (runtime 0, agent 0, human 0)
반면 토큰이 거부되면 작업은 종료 코드 2로 실패합니다.
Human 승인
Human 판정은 기본적으로 artifactsum을 통해 재사용되며, fingerprint = false면 재사용되지 않습니다. 아래 명령으로
Human 승인이 필요한 파일 하나짜리 프로젝트를 만들고, Bob이 쓸 복사본도 준비하세요. WALK가 아직 공유 디렉터리를
가리키고 있는 Alice의 터미널로 돌아가세요.
mkdir "$WALK/brand" && cd "$WALK/brand"
echo 'logo v1' > logo.txt
cat > index.artf <<'TOML'
name = "brand"
[evals.signoff]
title = "Sign off"
profile = { kind = "human" }
payload.instruction = "Approve the logo."
TOML
cp -r "$WALK/brand" "$WALK/brand-bob"
Alice가 verify --wait를 실행하면 Run이 제출되고 그 Run에 요청이 기록됩니다. 포그라운드에서는 Run이 끝날 때까지 진행 상황을 보여 주며 대기합니다. Alice는 두 번째 터미널에서 같은 디렉터리로 이동하고
ARTIFACTIZE_STATE_HOME을 같은 값으로 설정한 뒤 요청을 맡아
승인합니다. Alice의 토큰에는 human 범위가 있으므로 request submit이
승인을 게시하고, Alice의 verify --wait는 GREEN으로 끝납니다.
첫 번째 터미널에서는 Alice의 verify --wait를 계속 실행해 두세요.
export ARTIFACTIZE_STATE_HOME="$WALK/state-alice"
artifactize verify --all --wait
새 터미널에서도 앞에서 복사한 경로로 WALK를 설정하고, 같은 프로젝트 디렉터리로 이동한 뒤
Alice가 쓰는 상태 디렉터리를 지정하세요. REQUEST_ID는 request list가 출력한
대기 중인 요청의 식별자로 바꾸세요.
cd "$WALK/brand"
export ARTIFACTIZE_STATE_HOME="$WALK/state-alice"
artifactize request list
artifactize request claim REQUEST_ID
artifactize request submit REQUEST_ID --verdict GREEN
이제 $WALK/brand-bob에서 Bob의 상태로 verify --all --wait를 실행하면 그 승인을 재사용하며
(--reuse-only agent,human을 쓰는 CI도 마찬가지), 출력에
리뷰어와 인증된 게시자가 모두 나옵니다.
brand/signoff [run-rWExIl-1]: GREEN (reused from remote: Human sign-off by alice, published by alice-laptop, run-FD9ny6)
Summary: executed 0 (runtime 0, agent 0, human 0), reused 1 (runtime 0, agent 0, human 1)
Bob이 먼저 verify --all --wait를 실행했다면, Bob의 verify --wait는
Run의 진행 상황을 보여 주며 끝날 때까지 대기했을 것이고, Bob의 Run이 아직 열려 있는 동안
Alice가 제출한 승인이 저장소에 반영되면 Bob의 요청도 바로 확정됐을 것입니다. Bob은 승인 요청을 직접 맡지 않으므로
Bob의 Run은 2분 뒤 YELLOW로 끝나고 더는 저장소를 확인하지 않습니다. 그 뒤에 Alice가 승인하면 Bob은
verify를 다시 실행해 그 승인을 재사용합니다. Bob의 토큰에는 human이 없으므로, Bob이 제출한 승인은
경고와 함께 로컬에만 남습니다.
정리하려면 서버를 멈추고 rm -rf "$WALK"를 실행하세요.