프라이빗 패키지 레지스트리

이 가이드가 필요한 경우

프로젝트가 공개 PyPI가 아닌 프라이빗 레지스트리에 호스팅된 내부 또는 독점 Python 패키지에 의존하는 경우, 다음을 수행해야 합니다:

UV에 패키지를 어디서 찾을지 알려줍니다 (index URL)
UV에 어떤 패키지가 해당 index에서 오는지 알려줍니다 (source 매핑)
UV가 설치 중에 인증할 수 있도록 자격 증명을 제공합니다

CrewAI AMP는 의존성 해결 및 설치에 UV를 사용합니다. UV는 pyproject.toml 구성과 자격 증명용 환경 변수를 결합하여 인증된 프라이빗 레지스트리를 지원합니다.

1단계: pyproject.toml 구성

pyproject.toml에서 세 가지 요소가 함께 작동합니다:

1a. 의존성 선언

프라이빗 패키지를 다른 의존성과 마찬가지로 [project.dependencies]에 추가합니다:

[project]
dependencies = [
    "crewai[tools]>=0.100.1,<1.0.0",
    "my-private-package>=1.2.0",
]

1b. index 정의

프라이빗 레지스트리를 [[tool.uv.index]] 아래에 명명된 index로 등록합니다:

[[tool.uv.index]]
name = "my-private-registry"
url = "https://pkgs.dev.azure.com/my-org/_packaging/my-feed/pypi/simple/"
explicit = true

1c. 패키지를 index에 매핑

[tool.uv.sources]를 사용하여 프라이빗 index에서 해결해야 할 패키지를 UV에 알려줍니다:

[tool.uv.sources]
my-private-package = { index = "my-private-registry" }

전체 예시

[project]
name = "my-crew-project"
version = "0.1.0"
requires-python = ">=3.10,<=3.13"
dependencies = [
    "crewai[tools]>=0.100.1,<1.0.0",
    "my-private-package>=1.2.0",
]

[tool.crewai]
type = "crew"

[[tool.uv.index]]
name = "my-private-registry"
url = "https://pkgs.dev.azure.com/my-org/_packaging/my-feed/pypi/simple/"
explicit = true

[tool.uv.sources]
my-private-package = { index = "my-private-registry" }

pyproject.toml을 업데이트한 후 lock 파일을 다시 생성합니다:

uv lock

2단계: 인증 자격 증명 설정

UV는 pyproject.toml에서 정의한 index 이름을 기반으로 한 명명 규칙을 따르는 환경 변수를 사용하여 프라이빗 index에 인증합니다:

UV_INDEX_{UPPER_NAME}_USERNAME
UV_INDEX_{UPPER_NAME}_PASSWORD

여기서 {UPPER_NAME}은 index 이름을 대문자로 변환하고 하이픈을 언더스코어로 대체한 것입니다.

예를 들어, my-private-registry라는 이름의 index는 다음을 사용합니다:

변수	값
`UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME`	레지스트리 사용자 이름 또는 토큰 이름
`UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD`	레지스트리 비밀번호 또는 토큰/PAT

레지스트리 제공업체 참조

아래 표는 일반적인 레지스트리 제공업체의 index URL 형식과 자격 증명 값을 보여줍니다. 자리 표시자 값을 실제 조직 및 피드 세부 정보로 대체하세요.

제공업체	Index URL	사용자 이름	비밀번호
Azure DevOps Artifacts	`https://pkgs.dev.azure.com/{org}/_packaging/{feed}/pypi/simple/`	비어 있지 않은 임의의 문자열 (예: `token`)	Packaging Read 범위의 Personal Access Token (PAT)
GitHub Packages	`https://pypi.pkg.github.com/{owner}/simple/`	GitHub 사용자 이름	`read:packages` 범위의 Personal Access Token (classic)
GitLab Package Registry	`https://gitlab.com/api/v4/projects/{project_id}/packages/pypi/simple/`	`__token__`	`read_api` 범위의 Project 또는 Personal Access Token
AWS CodeArtifact	`aws codeartifact get-repository-endpoint`의 URL 사용	`aws`	`aws codeartifact get-authorization-token`의 토큰
Google Artifact Registry	`https://{region}-python.pkg.dev/{project}/{repo}/simple/`	`_json_key_base64`	Base64로 인코딩된 서비스 계정 키
JFrog Artifactory	`https://{instance}.jfrog.io/artifactory/api/pypi/{repo}/simple/`	사용자 이름 또는 이메일	API 키 또는 ID 토큰
자체 호스팅 (devpi, Nexus 등)	레지스트리의 simple API URL	레지스트리 사용자 이름	레지스트리 비밀번호

AMP에서 환경 변수 설정

프라이빗 레지스트리 자격 증명은 CrewAI AMP에서 환경 변수로 구성해야 합니다. 두 가지 옵션이 있습니다:

웹 인터페이스

CrewAI AMP에 로그인합니다
자동화로 이동합니다
Environment Variables 탭을 엽니다
각 변수 (UV_INDEX_*_USERNAME 및 UV_INDEX_*_PASSWORD)에 값을 추가합니다

자세한 내용은 AMP에 배포하기 — 환경 변수 설정하기 단계를 참조하세요.

CLI 배포

crewai deploy create를 실행하기 전에 로컬 .env 파일에 변수를 추가합니다. CLI가 이를 안전하게 플랫폼으로 전송합니다:

OPENAI_API_KEY=sk-...
UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME=token
UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD=your-pat-here

crewai deploy create

기존 배포의 자격 증명을 업데이트하려면 Crew 업데이트하기 — 환경 변수를 참조하세요.

전체 동작 흐름

CrewAI AMP가 자동화를 빌드할 때, 해결 흐름은 다음과 같이 작동합니다:

빌드 시작

AMP가 저장소를 가져오고 pyproject.toml과 uv.lock을 읽습니다.
UV가 의존성 해결

UV가 [tool.uv.sources]를 읽어 각 패키지가 어떤 index에서 와야 하는지 결정합니다.
UV가 인증

각 프라이빗 index에 대해 UV가 AMP에서 구성한 환경 변수에서 UV_INDEX_{NAME}_USERNAME과 UV_INDEX_{NAME}_PASSWORD를 조회합니다.
패키지 설치

UV가 공개(PyPI) 및 프라이빗(레지스트리) 패키지를 모두 다운로드하고 설치합니다.
자동화 실행

모든 의존성이 사용 가능한 상태에서 crew 또는 flow가 시작됩니다.

문제 해결

빌드 중 인증 오류

증상: 프라이빗 패키지를 해결할 때 401 Unauthorized 또는 403 Forbidden으로 빌드가 실패합니다.

확인사항:

UV_INDEX_* 환경 변수 이름이 index 이름과 정확히 일치하는지 확인합니다 (대문자, 하이픈 -> 언더스코어)
자격 증명이 로컬 .env뿐만 아니라 AMP 환경 변수에 설정되어 있는지 확인합니다
토큰/PAT에 패키지 피드에 필요한 읽기 권한이 있는지 확인합니다
토큰이 만료되지 않았는지 확인합니다 (특히 AWS CodeArtifact의 경우)

패키지를 찾을 수 없음

증상: No matching distribution found for my-private-package.

확인사항:

pyproject.toml의 index URL이 /simple/로 끝나는지 확인합니다
[tool.uv.sources] 항목이 올바른 패키지 이름을 올바른 index 이름에 매핑하는지 확인합니다
패키지가 실제로 프라이빗 레지스트리에 게시되어 있는지 확인합니다
동일한 자격 증명으로 로컬에서 uv lock을 실행하여 해결이 작동하는지 확인합니다

Lock 파일 충돌

증상: 프라이빗 index를 추가한 후 uv lock이 실패하거나 예상치 못한 결과를 생성합니다.

해결책: 로컬에서 자격 증명을 설정하고 다시 생성합니다:

export UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME=token
export UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD=your-pat
uv lock

그런 다음 업데이트된 uv.lock을 커밋합니다.