PyPI에서 OpenID Connect 구성하기

워크플로 내에서 OpenID Connect를 사용하여 PyPI로 인증할 수 있습니다.

이 문서의 내용

개요

OIDC(OpenID Connect)를 사용하면 GitHub Actions 워크플로우에서 PyPI로 인증하여 Python 패키지를 게시할 수 있습니다.

이 가이드에서는 GitHub의 OIDC를 페더레이션 ID로 신뢰하도록 PyPI를 구성하는 방법에 대한 개요를 제공하고, 이 구성을 사용하여 pypa/gh-action-pypi-publish 수동 API 토큰 관리 없이 PyPI(또는 다른 Python 패키지 리포지토리)에 패키지를 게시하는 방법을 설명합니다.

필수 조건

  • GitHub가 OIDC(OpenID Connect)를 사용하는 방법과 아키텍처 및 이점에 대한 기본 개념을 알아보려면 “OpenID Connect를 사용한 보안 강화 정보”를 참조하세요.

  • 계속하기 전에 액세스 토큰이 예측 가능한 방식으로만 할당되도록 보안 전략을 계획해야 합니다. 클라우드 공급자가 액세스 토큰을 발급하는 방법을 제어하려면 신뢰할 수 없는 리포지토리가 클라우드 리소스에 대한 액세스 토큰을 요청할 수 없도록 하나 이상의 조건을 정의해야 합니다. 자세한 내용은 "OpenID Connect를 사용한 보안 강화 정보" 항목을 참조하세요.

  • GHE.com에서 이 가이드를 따르는 경우 다음 문서의 특정 값을 대체해야 한다는 점을 알아 두세요. "OpenID Connect를 사용한 보안 강화 정보" 항목을 참조하세요.

PyPI에 ID 공급자 추가하기

PyPI에서 OIDC를 사용하려면 PyPI의 각 프로젝트를 게시가 허용된 각 리포지토리 및 워크플로 조합에 연결하는 신뢰 구성을 추가하세요.

  1. PyPI에 로그인하고 구성하려는 프로젝트의 신뢰할 수 있는 게시 설정으로 이동합니다. 이름이 myproject인 프로젝트의 경우 https://pypi.org/manage/project/myproject/settings/publishing/에 있습니다.

  2. PyPI 프로젝트와 GitHub 리포지토리(및 리포지토리 내의 워크플로) 간의 신뢰 관계를 구성합니다. 예를 들어 GitHub 리포지토리가 myorg/myproject이고 릴리스 워크플로우가 release.yml에 정의되어 있고 환경이 release인 경우 PyPI에서 신뢰할 수 있는 퍼블리셔에 대해 다음 설정을 사용해야 합니다.

    Note

    이 값을 신중하게 입력하세요. 잘못된 사용자, 리포지토리 또는 워크플로우에 PyPI 프로젝트에 게시할 수 있는 권한을 부여하는 것은 API 토큰을 공유하는 것과 같습니다.

    • 소유자: myorg
    • 리포지토리 이름: myproject
    • 워크플로 이름: release.yml
    • (선택 사항) GitHub Actions 환경 이름: release

GitHub Actions 워크플로 업데이트

신뢰할 수 있는 퍼블리셔가 PyPI에 등록되면 릴리스 워크플로를 업데이트하여 신뢰할 수 있는 퍼블리싱을 사용할 수 있습니다.

Note

워크플로 또는 OIDC 정책에서 환경을 사용하는 경우 추가 보안을 위해 환경에 보호 규칙을 추가하는 것이 좋습니다. 예를 들어 환경에 배포할 수 있는 분기 및 태그를 제한하거나 환경 비밀에 액세스하도록 환경에 대한 배포 규칙을 구성할 수 있습니다. 자세한 내용은 "배포 환경 관리" 항목을 참조하세요.

이 pypa/gh-action-pypi-publish 작업은 신뢰할 수 있는 게시에 대한 기본 제공 지원을 제공합니다. 이 작업은 포함된 작업에 id-token: write 사용 권한을 부여하고 생략 username 하고 password생략하여 사용하도록 설정할 수 있습니다.

다음 예제에서는 pypa/gh-action-pypi-publish 작업을 사용하여 OIDC 토큰을 PyPI API 토큰으로 교환한 다음, PyPI API 토큰을 사용하여 패키지의 릴리스 배포를 PyPI에 업로드합니다.

YAML
jobs:
  release-build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: "3.x"

      - name: build release distributions
        run: |
          # NOTE: put your own distribution build steps here.
          python -m pip install build
          python -m build

      - name: upload windows dists
        uses: actions/upload-artifact@v4
        with:
          name: release-dists
          path: dist/

  pypi-publish:
    runs-on: ubuntu-latest
    needs:
      - release-build
    permissions:
      id-token: write

    steps:
      - name: Retrieve release distributions
        uses: actions/download-artifact@v4
        with:
          name: release-dists
          path: dist/

      - name: Publish release distributions to PyPI
        uses: pypa/gh-action-pypi-publish@3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f