Convex

Convex는 Convex 대시보드에서 만든 팀 액세스 토큰으로 연결합니다. 팀 액세스 토큰은 정확히 하나의 팀으로 범위가 지정되므로, 토큰 하나가 팀 하나를 연결합니다. 토큰은 저장 전에 암호화되며 에이전트는 이를 절대 보지 못합니다.

1. Convex 대시보드를 열고 Team Settings → Access Tokens로 이동합니다.
2. Create access token을 클릭하고 토큰 값을 복사합니다.
3. 토큰을 Polylane에 붙여 넣습니다.
4. Polylane이 토큰을 검증하고 동기화를 시작합니다.

Polylane은 프로젝트를 발견하고, 각 프로젝트 안에서 클라우드 배포를 발견합니다: 프로덕션 배포와 프리뷰, 개발, 사용자 정의 배포를 리전, URL, 배포 클래스와 함께 발견합니다.

팀 액세스 토큰은 팀에 대한 관리 접근 권한을 부여합니다. 동기화는 팀 토큰으로 프로젝트와 배포를 읽습니다. 에이전트나 백그라운드 모니터링이 배포의 함수 로그나 메트릭을 읽을 때, Polylane은 그 읽기(로그 보기 또는 메트릭 보기)에만 범위가 지정된 단기 배포 키를 발급하여 한 번의 호출에 사용하고 즉시 삭제하므로, 각 키는 자신이 담당하는 읽기 동안만 존재합니다. Polylane이 읽는 모든 것은 관리 표면에 있습니다: 프로젝트와 배포 목록, 함수 로그, 배포 메트릭입니다.

문제 해결

"Not a team access token" 오류

• 프로젝트 범위 토큰과 배포 키는 팀의 프로젝트를 나열할 수 없습니다. Team Settings → Access Tokens에서 토큰을 만드세요.
• Convex 대시보드에서 토큰이 삭제되지 않았는지 확인하세요.

리소스 누락

• 로컬 배포는 개별 개발자 머신에서 실행되며 의도적으로 동기화되지 않습니다.
• 배포 없이 만들어진 프로젝트는 첫 배포까지 배포가 표시되지 않습니다.
• 다음 예약된 동기화보다 빨리 새로 고치려면 수동 동기화를 실행하세요.

감사 로그

• Convex는 감사 로그 API를 유료 플랜 뒤에 둡니다. 무료 팀에서는 감사 로그 읽기가 명확한 오류를 반환하고, 에이전트는 함수 로그와 컨텍스트 그래프로 대체합니다.

연결 해제

Polylane에서 계정의 연결을 해제한 뒤, Convex 팀 설정에서 액세스 토큰을 삭제하세요.

Convex 연결에는 브라우저가 필요하지 않습니다: 콘솔이 호출하는 것과 같은 엔드포인트를 CI 작업에 담을 수 있습니다. 인증된 POST 하나가 연결을 만들고 첫 동기화를 시작합니다.

사전 요구 사항

• cloud_accounts:write와 cloud_accounts:read 스코프를 가진 Polylane API 키. API 키와 OAuth를 참고하세요.
• ws_로 시작하는 워크스페이스 ID. 같은 키로 GET /v1/workspaces에서 읽을 수 있습니다.
• Team Settings → Access Tokens의 Convex 팀 액세스 토큰.

연결 만들기

curl -X POST https://api.polylane.com/v1/cloud_accounts \
  -H "x-api-key: $POLYLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "convex",
    "workspaceId": "ws_0abc123",
    "token": "<team-access-token>"
  }'

팀 액세스 토큰은 정확히 하나의 팀으로 범위가 지정되므로, 한 번의 호출로 팀 하나가 연결됩니다.

응답은 연결된 것을 나열하며, 첫 동기화는 이미 실행 중입니다. 나머지 흐름이 읽는 두 필드만 남기면:

{
  "success": true,
  "result": {
    "provider": "convex",
    "accounts": [{ "id": "acc_34gky74ibc92h8t2efn8csrh", "status": "syncing" }],
    "failures": []
  }
}

이미 연결된 계정은 accounts 대신 failures에 들어가므로, 호출을 반복해도 연결이 중복되지 않습니다.

첫 동기화 기다리기

반환된 각 계정을 id로 status가 ready에 도달할 때까지 폴링하세요(등록 시 new, 리소스가 들어오는 동안 syncing):

until [ "$(curl -s "https://api.polylane.com/v1/cloud_accounts/$WORKSPACE_ID/$ACCOUNT_ID" \
  -H "x-api-key: $POLYLANE_API_KEY" | jq -r '.result.status')" = "ready" ]; do
  sleep 15
done

실패한 연결이 작업을 멈추게 하는 대신 실패시키도록 루프에 기한을 두세요. 계정이 ready가 되면 리소스는 토폴로지에 있고 Polylane은 첫 검사를 시작한 상태입니다.

API에서 연결 해제

연결을 삭제하면 모든 동기화와 검사가 중단되고 Polylane이 보관하던 자격 증명이 삭제됩니다. 호출에는 cloud_accounts:delete 스코프가 필요합니다:

curl -X DELETE "https://api.polylane.com/v1/cloud_accounts/$WORKSPACE_ID/$ACCOUNT_ID" \
  -H "x-api-key: $POLYLANE_API_KEY"

그 다음 아래 연결 해제에 설명된 대로 제공자 쪽에서 Convex 자격 증명을 취소하세요.