> ## Documentation Index > Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt > Use this file to discover all available pages before exploring further. # GitHub 토큰 설정 > AgentEye GitHub 토큰 설정 문서입니다. GitHub Personal Access Token(PAT)은 모든 AgentEye 아티팩트에 접근할 수 있는 단일 자격증명입니다. 토큰 하나로 Docker 이미지 가져오기, 릴리스 바이너리 다운로드, Python 휠 설치가 모두 가능하며, 컴포넌트별 로그인이나 공유 시크릿을 배포할 필요가 없습니다. 모든 AgentEye 아티팩트는 `agenteye-enterprise` GitHub 조직에서 배포됩니다. 조직에 접근 권한이 부여되면, 각 개발자 또는 운영자가 자신의 토큰을 개별적으로 생성하고 교체하므로, 접근 기록을 감사하고 개인별로 권한을 취소할 수 있습니다. 머신마다 한 번씩 토큰을 환경 변수로 설정하고 Docker 자격증명을 등록하세요: ```bash theme={null} export AGENTEYE_TOKEN= echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin ``` > **사용자명 참고:** 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 | 그 외 모든 권한은 **No access**로 유지할 수 있습니다. > **참고:** 컨테이너 이미지(`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**을 클릭하고 즉시 값을 복사합니다. 토큰은 한 번만 표시됩니다. 시크릿 매니저 또는 환경 변수에 저장하세요. *** ## 토큰 교체 정기적으로 토큰을 교체하면 접근 기록을 감사 가능한 상태로 유지하고, 자격증명이 유출되더라도 피해 범위를 최소화할 수 있습니다. 토큰은 만료되거나 언제든지 취소될 수 있으므로, 인증 상태를 유지하기 위한 일반적인 방법이 토큰 교체입니다. 교체 방법: 1. 위의 단계에 따라 새 토큰을 생성합니다. 2. 환경 변수 또는 시크릿 매니저에서 `AGENTEYE_TOKEN`을 업데이트합니다. 3. Docker 재인증: `echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin` 4. GitHub → Settings → Developer settings → Personal access tokens에서 이전 토큰을 취소합니다. 토큰 유형에 맞는 **Tokens (classic)** 또는 **Fine-grained tokens** 하위 페이지를 열고 삭제합니다. *** ## 토큰 검증 배포에 연결하기 전에 토큰이 정상적으로 작동하는지 확인하세요. 인증 오류가 배포 중간에 발생하지 않고 여기서 표면화될 수 있습니다. 아래 각 명령은 위에서 설명한 스코프 중 하나를 검증합니다: ```bash theme={null} # Packages scope - authenticate Docker against GHCR echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin # Contents scope - fetch a raw release file curl -fsSL \ -H "Authorization: token $AGENTEYE_TOKEN" \ https://raw.githubusercontent.com/agenteye-enterprise/releases/main/docker-compose.yml \ -o /tmp/agenteye-compose-check.yml ``` `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`로 문의하세요.