agenteye-enterprise GitHub 조직에서 배포됩니다. 조직에 접근 권한이 부여되면, 각 개발자 또는 운영자가 자신의 토큰을 개별적으로 생성하고 교체하므로, 접근 기록을 감사하고 개인별로 권한을 취소할 수 있습니다.
머신마다 한 번씩 토큰을 환경 변수로 설정하고 Docker 자격증명을 등록하세요:
사용자명 참고: GHCR은docker login의 사용자명을 무시하고 토큰만으로 인증하므로, 비어 있지 않은 값이면 무엇이든 사용할 수 있습니다. 이 문서에서는 간결함을 위해-u x를 사용합니다. Kubernetes 이미지 풀 시크릿을 생성하는 배포 매니페스트에서는agenteye-enterprise와 같이 좀 더 설명적인 사용자명을 사용할 수도 있습니다. 두 방식 모두 허용됩니다.
옵션 A: 클래식 토큰 (권장)
클래식 토큰은 AgentEye에서 가장 안정적인 선택입니다. GHCR의docker login 및 이미지 풀 과정에서 클래식 토큰에 대한 지원이 가장 광범위하고 일관적이기 때문입니다. 두 가지 스코프만으로 필요한 모든 작업(이미지 가져오기 및 릴리스 에셋 다운로드)이 가능하므로, 한 번 인증하면 레지스트리 관련 문제를 따로 해결할 필요가 없습니다. 그 중 read:packages는 진정한 의미의 읽기 전용이지만, repo는 비공개 릴리스 에셋에 대한 접근 권한을 부여하는 유일한 클래식 스코프로, 의도적으로 넓은 범위를 가집니다 — GitHub는 이를 비공개 리포지토리에 대한 완전한 제어권(읽기 및 쓰기)으로 정의하고 있습니다.
1. 토큰 생성
**GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token (classic)**으로 이동합니다.| 필드 | 값 |
|---|---|
| Note | agenteye-<머신 또는 팀 이름> (예: agenteye-prod-server) |
| Expiration | 보안 정책에 맞는 만료 기간 설정; 기본값으로 90일이 적절합니다 |
레이블 참고: GitHub는 클래식 토큰의 경우 이 필드를 Note, 세분화된 토큰의 경우 Token name으로 표시합니다. 두 필드 모두 동일한 목적, 즉 이후 감사 및 취소를 위한 사람이 읽을 수 있는 식별자로 사용됩니다.
2. 스코프 선택
| 스코프 | 필요한 이유 |
|---|---|
read:packages | ghcr.io/agenteye-enterprise/에서 Docker 이미지를 가져오고 패키지 에셋을 다운로드하기 위해 필요 |
repo | agenteye-enterprise/releases의 비공개 리포지토리 콘텐츠, 원시 파일, 릴리스 에셋을 읽기 위해 필요. 이는 GitHub의 “비공개 리포지토리 완전 제어”(읽기 및 쓰기) 스코프로, 읽기 전용이 아니지만 비공개 릴리스 에셋에 접근할 수 있는 유일한 클래식 스코프입니다 |
3. 토큰 생성 및 복사
Generate token을 클릭하고 즉시 값을 복사합니다. 토큰은 한 번만 표시됩니다. 시크릿 매니저 또는 환경 변수에 저장하세요.옵션 B: 세분화된 토큰 (Fine-Grained Token)
세분화된 토큰은 특정 리포지토리와 권한으로 접근 범위를 제한하므로 최소 권한 원칙을 가장 엄격하게 적용할 수 있는 옵션입니다. 조직의 보안 정책에서 세분화된 토큰을 의무적으로 요구하는 경우 이 방법을 선택하세요.참고: GHCR의 세분화된 토큰 지원은 클래식 토큰에 비해 일관성이 낮습니다. 위 단계를 따른 후docker login또는docker pull이 실패하면, 클래식 토큰(옵션 A)으로 전환하세요.
1. 토큰 생성
GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token으로 이동합니다.| 필드 | 값 |
|---|---|
| Token name | agenteye-<머신 또는 팀 이름> (예: agenteye-prod-server) |
| Expiration | 보안 정책에 맞는 만료 기간 설정; 기본값으로 90일이 적절합니다 |
| Resource owner | agenteye-enterprise |
| Repository access | Only select repositories → agenteye-enterprise/releases |
2. 리포지토리 권한 설정
Permissions → Repository permissions에서 다음과 같이 설정합니다:| 권한 | 접근 수준 |
|---|---|
| Contents | Read-only |
| Packages | Read-only |
참고: 컨테이너 이미지(ghcr.io/agenteye-enterprise/...)가 리포지토리 연결 패키지가 아닌 조직 수준 패키지로 게시된 경우, 리포지토리 스코프 권한만으로는 Docker 로그인이 실패할 수 있습니다. 이 경우 조직 수준 권한을 추가하세요: Permissions → Organization permissions → Packages: Read-only.
3. 각 권한이 부여하는 접근 범위
| 권한 | 사용 목적 |
|---|---|
| Contents: Read-only | agenteye-enterprise/releases에서 docker-compose.yml, 릴리스 바이너리, Python 휠 다운로드 |
| Packages: Read-only | ghcr.io/agenteye-enterprise/에서 Docker 이미지 가져오기 |
4. 토큰 생성 및 복사
Generate token을 클릭하고 즉시 값을 복사합니다. 토큰은 한 번만 표시됩니다. 시크릿 매니저 또는 환경 변수에 저장하세요.토큰 교체
정기적으로 토큰을 교체하면 접근 기록을 감사 가능한 상태로 유지하고, 자격증명이 유출되더라도 피해 범위를 최소화할 수 있습니다. 토큰은 만료되거나 언제든지 취소될 수 있으므로, 인증 상태를 유지하기 위한 일반적인 방법이 토큰 교체입니다. 교체 방법:- 위의 단계에 따라 새 토큰을 생성합니다.
- 환경 변수 또는 시크릿 매니저에서
AGENTEYE_TOKEN을 업데이트합니다. - Docker 재인증:
echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin - GitHub → Settings → Developer settings → Personal access tokens에서 이전 토큰을 취소합니다. 토큰 유형에 맞는 Tokens (classic) 또는 Fine-grained tokens 하위 페이지를 열고 삭제합니다.
토큰 검증
배포에 연결하기 전에 토큰이 정상적으로 작동하는지 확인하세요. 인증 오류가 배포 중간에 발생하지 않고 여기서 표면화될 수 있습니다. 아래 각 명령은 위에서 설명한 스코프 중 하나를 검증합니다:docker login이 성공하면 패키지 스코프가 확인된 것이고, 파일이 다운로드되면 콘텐츠 스코프가 확인된 것입니다.
문제 해결
| 증상 | 예상 원인 | 해결 방법 |
|---|---|---|
docker login에서 401 반환 | 세분화된 토큰에서 Packages: Read-only 누락, 또는 클래식 토큰에서 read:packages 누락 | 패키지 스코프를 추가하고 토큰을 재생성하세요 |
curl이 GitHub raw URL에서 404 반환 | Contents: Read-only 또는 repo 스코프 누락 | 콘텐츠 스코프를 추가하고 토큰을 재생성하세요 |
gh release download에서 403 반환 | 토큰이 agenteye-enterprise/releases에 대한 권한 없음 | 세분화된 토큰의 리포지토리 접근에 해당 리포지토리가 포함되어 있는지 확인하거나, repo 스코프가 있는 클래식 토큰을 사용하세요 |
| 토큰은 수락되지만 이미지를 찾을 수 없음 | 세분화된 토큰에 조직 수준 패키지 권한 누락 | 조직 수준 Packages: Read-only 권한을 추가하세요 |
support@exosphere.host로 문의하세요.