패키지 설치

5분

GitHub 패키지에서 패키지를 설치하면 GitHub에서 호스트되는 라이브러리, 종속성 및 컨테이너 이미지를 사용할 수 있습니다. 프로젝트에서 종속성으로 사용할 수 있도록 보기 권한이 있는 패키지를 설치할 수 있습니다.

패키지 검색

GitHub 패키지는 패키지를 검색하는 여러 가지 방법을 제공합니다.

검색 옵션

전역 검색: GitHub의 모든 공용 패키지에서 검색
조직 검색: 특정 조직 내에서 패키지 찾기
리포지토리 검색: 리포지토리에서 게시된 패키지 찾아보기
패키지 형식 필터: npm, NuGet, Maven, Docker 등을 사용하여 필터링합니다.

자세한 내용은 패키지 검색을 참조하세요.

패키지 정보

패키지를 찾으면 패키지 페이지에서 필수 정보를 제공합니다.

묘사: 패키지의 기능 및 용도
설치 지침: 프로젝트에 패키지를 추가하는 방법
버전 기록: 사용 가능한 버전 및 릴리스 정보
종속성: 필수 패키지 및 버전 제약 조건
사용 예제: 일반적인 시나리오를 보여 주는 코드 샘플
면허: 패키지 사용에 대한 법적 조건
통계 다운로드: 패키지가 설치된 횟수

모범 사례: 설치하기 전에 항상 패키지의 설치 및 설명 지침을 읽고 요구 사항, 주요 변경 내용 및 호환성을 이해합니다.

설치 워크플로

패키지 설치는 패키지 유형에 관계없이 일관된 2단계 프로세스를 따릅니다.

1. GitHub 패키지에 인증

read:packages 범위를 사용하여 PAT(개인용 액세스 토큰)를 사용하여 GitHub 패키지로 인증하도록 패키지 클라이언트를 구성합니다.

인증 요구 사항:

공용 패키지: 공용 패키지에 대해서도 인증이 필요합니다.
프라이빗 패키지: 적절한 리포지토리 액세스 권한이 있는 PAT 필요
조직 패키지: 조직 구성원 자격이 필요할 수 있음
내부 패키지: GitHub Enterprise 조직 내에서만 사용 가능

2. 패키지 설치

패키지 클라이언트의 네이티브 설치 명령 (npm 설치, dotnet add package, mvn install 등)을 사용하여 프로젝트에 패키지를 추가합니다.

설치 검사 목록:

패키지 이름 및 버전이 올바른지 확인
프로젝트의 프레임워크 버전과의 호환성 확인
충돌에 대한 종속성 트리 검토
설치 후 패키지 기능 테스트
새 종속성을 반영하도록 설명서 업데이트

NuGet 패키지 설치

NuGet 패키지는Visual Studio 또는 dotnet CLI를 사용하여 설치할 수 있습니다.

방법 1: Visual Studio

Visual Studio는 NuGet 패키지를 관리하기 위한 그래픽 인터페이스 를 제공합니다.

NuGet 패키지 관리자 열기:
- 솔루션 → 프로젝트 확장
- 종속성을 마우스 오른쪽 단추로 클릭
- NuGet 패키지 관리 선택...
찾아보기 및 설치:
- 찾아보기 탭 클릭
- 패키지 이름 검색
- 원하는 버전 선택
- 설치 클릭

여러 레지스트리에서 종속성을 동시에 찾아보고, 설치하고, 업데이트할 수 있습니다. 자세한 내용은 프로젝트 종속성만들기 및 제거를 참조하세요.

메서드 2: .csproj 직접 편집

프로젝트 파일에 패키지 참조를 직접 추가할 수 있습니다.

1단계: GitHub 패키지에 인증

nuget.config 파일을 만들거나 업데이트합니다(인증 세부 정보는 게시 섹션 참조).

2단계: PackageReference 추가

.csproj 파일에 PackageReference를 사용하여 ItemGroup을 추가합니다.

<Project Sdk="Microsoft.NET.Sdk">

    <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>net8.0</TargetFramework>
        <PackageId>OctocatApp</PackageId>
        <Version>1.0.0</Version>
        <Authors>Octocat</Authors>
        <Company>GitHub</Company>
        <PackageDescription>This package adds an Octocat!</PackageDescription>
        <RepositoryUrl>https://github.com/OWNER/REPOSITORY</RepositoryUrl>
    </PropertyGroup>

    <ItemGroup>
        <PackageReference Include="OctokittenApp" Version="12.0.2" />
    </ItemGroup>
</Project>

메모

OctokittenApp을 패키지 이름으로 바꾸고 12.0.2를 사용하려는 버전으로 바꿉다.

3단계: 패키지 복원

복원 명령을 사용하여 패키지를 설치합니다.

dotnet restore

방법 3: dotnet CLI 사용

dotnet add 명령을 사용하여 패키지를 설치할 수 있습니다.

dotnet add package OctokittenApp --version 12.0.2 --source github

NuGet 설치 모범 사례:

고정 버전: 재현 가능한 빌드에 대한 정확한 버전 지정
중앙 패키지 관리 사용: Directory.Packages.props의 버전 통합
취약성 검토: 설치하기 전에 보안 권고 확인
호환성 테스트: 패키지가 대상 프레임워크에서 작동하는지 확인

npm 패키지 설치

npm 패키지는.npmrc 파일을 구성하여 GitHub 패키지를 레지스트리로 지정해야 합니다.

.npmrc 파일 구성

1단계: GitHub 패키지에 인증

인증 토큰 으로 ~/.npmrc 파일을 만들거나 업데이트합니다(인증 세부 정보는 게시 섹션 참조).

2단계: 프로젝트 .npmrc 만들기

package.json 파일과 동일한 디렉터리 에서 .npmrc 파일을 만들거나 편집합니다.

@OWNER:registry=https://npm.pkg.github.com

메모

OWNER를 패키지를 소유하는 사용자 또는 조직 계정의 이름으로 바꿉다.

3단계: .npmrc를 리포지토리에 커밋

모든 팀 구성원이 동일한 구성을 사용하도록 .npmrc 파일을 리포지토리에 추가합니다. 리포지토리에 파일 추가를 참조하세요.

package.json 종속성 추가

패키지를 종속성으로 포함하도록 package.json 구성합니다.

{
  "name": "@my-org/server",
  "version": "1.0.0",
  "description": "Server app that uses the @octo-org/octo-app package",
  "main": "index.js",
  "author": "",
  "license": "MIT",
  "dependencies": {
    "@octo-org/octo-app": "1.0.0"
  }
}

종속성 사양:

정확한 버전:"1.0.0" 특정 버전을 설치합니다.
캐럿 범위:"^1.0.0" 호환되는 마이너/패치 업데이트 설치
틸드 범위:"~1.0.0" 호환 가능한 패치 업데이트만 설치합니다.
최근:"latest" 최신 버전을 설치합니다(프로덕션에는 권장되지 않음).

패키지 설치

npm install 명령을 실행합니다.

npm install

또는 특정 패키지를 설치합니다.

npm install @octo-org/octo-app

여러 조직

여러 조직에서 패키지를 설치해야 하는 경우 .npmrc 파일에 줄을 더 추가합니다.

@first-org:registry=https://npm.pkg.github.com
@second-org:registry=https://npm.pkg.github.com
@third-org:registry=https://npm.pkg.github.com

npm 설치 모범 사례:

package-lock.json사용: 환경 전체에서 일관된 설치를 위한 잠금 파일 커밋
종속성 감사: 취약성을 확인하려면 npm audit 실행
npm ci 사용: CI/CD 파이프라인에서 더 빠르고 안정적인 설치를 위해 사용 npm ci
버전 제약 조건: 의미 체계 버전 범위를 사용하여 안정성 및 업데이트 균형 조정
먼저 프라이빗 레지스트리: 공용 npm 전에 GitHub 패키지를 확인하도록 범위 구성

CI/CD 파이프라인에 설치

동일한 방법을 사용하여 GitHub Actions 워크플로에 패키지를 설치할 수 있습니다.

GitHub Actions의 npm

- uses: actions/setup-node@v4
  with:
    node-version: "18"
    registry-url: "https://npm.pkg.github.com"
    scope: "@OWNER"
- run: npm ci
  env:
    NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

GitHub Actions의 NuGet

- uses: actions/setup-dotnet@v4
  with:
    dotnet-version: "8.0.x"
    source-url: https://nuget.pkg.github.com/OWNER/index.json
  env:
    NUGET_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- run: dotnet restore

GITHUB_TOKEN 이점:

PAT가 필요하지 않습니다. 워크플로에서 자동으로 사용 가능
설정된 권한: 워크플로우의 리포지토리 액세스로 제한됩니다
자동 회전: 각 워크플로 실행에 대해 토큰이 다시 생성됩니다.
보안: 로그나 아티팩트에 절대 노출되지 않습니다.

설치 문제 해결

일반적인 문제 및 해결 방법:

문제	원인	Solution
401 권한 없음	PAT가 없거나 잘못되었습니다.	토큰에 `read:packages` 스코프가 있는지 확인
404 찾을 수 없음	패키지 이름 또는 레지스트리 URL이 잘못되었습니다.	패키지가 있고 소유자가 올바른지 확인
403 금지됨	패키지에 액세스할 수 있는 권한 없음	액세스 요청 또는 조직 구성원 자격 확인
버전을 찾을 수 없음	요청된 버전이 없습니다.	패키지 페이지에서 사용 가능한 버전 확인
종속성 충돌	호환되지 않는 패키지 버전	다른 종속성 업데이트 또는 해결 방법 사용

추가 리소스

자세한 내용은 다음을 참조하세요.

GitHub 패키지 레지스트리 작업 - 지원되는 모든 레지스트리에 대한 전체 가이드입니다.
NuGet 레지스트리 작업 - 자세한 NuGet 설치 가이드
npm 레지스트리 작업 - 자세한 npm 설치 가이드
GitHub 패키지에 대한 권한 정보 - 패키지 액세스 제어 이해

피드백

이 페이지가 도움이 되었나요?