소개
이 가이드에서는 Python 패키지를 빌드하고 테스트하고 게시하는 방법을 보여 줍니다.
GitHub 호스트 실행기에는 Python 및 PyPy를 포함하는 소프트웨어가 사전 설치된 도구 캐시가 있습니다. 사용자는 아무것도 설치할 필요가 없습니다. 최신 소프트웨어 및 사전 설치된 Python 및 PyPy 버전의 전체 목록은 GitHub 호스팅 실행기 사용을(를) 참조하세요.
필수 조건
YAML 및 GitHub Actions의 구문에 대해 잘 알고 있어야 합니다. 자세한 내용은 워크플로 작성을(를) 참조하세요.
Python과 pip에 대한 기본 학습을 선행하는 것이 좋습니다. 자세한 내용은 다음을 참조하세요.
Python 워크플로 템플릿 사용
빠르게 시작하려면 워크플로 템플릿을 리포지토리의 .github/workflows 디렉터리에 추가합니다.
GitHub은(는) 리포지토리에 이미 하나 이상의 .py 파일이 있는 경우에 작동해야 하는 Python용 워크플로 템플릿을 제공합니다. 이 가이드의 후속 섹션에서는 이 워크플로 템플릿을 사용자 지정하는 방법에 대한 예시를 제공합니다.
-
GitHub에서 리포지토리의 기본 페이지로 이동합니다.
-
리포지토리 이름 아래에서 작업을 클릭합니다.
-
리포지토리에 워크플로가 이미 있는 경우 새 워크플로를 클릭합니다.
-
"워크플로 선택" 페이지에는 권장되는 워크플로 템플릿의 선택 항목이 표시됩니다. "Python 애플리케이션"을 검색합니다.
-
"Python 애플리케이션" 워크플로에서 구성을 클릭합니다.
-
필요에 따라 워크플로를 편집합니다. 예를 들어 Python 버전을 변경합니다.
-
변경 내용 커밋을 클릭합니다.
python-app.yml 워크플로 파일이 리포지토리의 .github/workflows 디렉터리에 추가됩니다.
Python 버전 지정
GitHub 호스트 실행기에서 사전 설치된 버전의 Python 또는 PyPy를 사용하려면 setup-python 작업을 사용하세요. 이 작업은 각 실행기의 도구 캐시에서 Node.js의 특정 버전을 찾아 필수 이진 파일을 PATH에 추가합니다. 이는 나머지 작업 동안 유지됩니다. 특정 버전의 Python이 도구 캐시에 사전 설치되어 있지 않으면 setup-python 작업이 python-versions 리포지토리에서 적절한 버전을 다운로드하고 설정합니다.
setup-python 작업을 사용하는 것은 다양한 실행기 및 Python 버전 간에 일관된 동작을 보장하므로 GitHub Actions로 Python을 사용하는 데 권장되는 방법입니다. 자체 호스트 실행기를 사용하는 경우 Python을 설치하고 이를 PATH에 추가해야 합니다. 자세한 내용은 setup-python 작업을 참조하세요.
아래 테이블에서는 각 GitHub호스트 실행기에서 도구 캐시의 위치를 설명합니다.
| Ubuntu | Mac | Windows | |
|---|---|---|---|
| 도구 캐시 디렉터리 | /opt/hostedtoolcache/* | /Users/runner/hostedtoolcache/* | C:\hostedtoolcache\windows\* |
| Python 도구 캐시 | /opt/hostedtoolcache/Python/* | /Users/runner/hostedtoolcache/Python/* | C:\hostedtoolcache\windows\Python\* |
| PyPy 도구 캐시 | /opt/hostedtoolcache/PyPy/* | /Users/runner/hostedtoolcache/PyPy/* | C:\hostedtoolcache\windows\PyPy\* |
자체 호스팅 실행기를 사용하는 경우 setup-python 작업을 사용하여 종속성을 관리하도록 실행기를 구성할 수 있습니다. 자세한 내용은 setup-python 추가 정보에서 자체 호스트 실행기로 setup-python 사용을 참조하세요.
GitHub는 의미 체계 버전 관리 구문을 지원합니다. 자세한 내용은 의미 체계 버전 관리 사용 및 의미 체계 버전 관리 사양을 참조하세요.
여러 Python 버전 사용
다음 예시에서는 작업에 대한 행렬을 사용하여 여러 Python 버전을 설정합니다. 자세한 내용은 워크플로에서 작업 변형 실행을(를) 참조하세요.
name: Python package
on: [push]
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: ["pypy3.10", "3.9", "3.10", "3.11", "3.12", "3.13"]
steps:
- uses: actions/checkout@v4
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python-version }}
# You can test your matrix by printing the current Python version
- name: Display Python version
run: python -c "import sys; print(sys.version)"
name: Python package
on: [push]
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: ["pypy3.10", "3.9", "3.10", "3.11", "3.12", "3.13"]
steps:
- uses: actions/checkout@v4
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python-version }}
# You can test your matrix by printing the current Python version
- name: Display Python version
run: python -c "import sys; print(sys.version)"
특정 Python 버전 사용
특정한 Python 버전을 구성할 수 있습니다. 예: 3.12. 또는 의미 체계 버전 구문을 사용하여 최신 부 릴리스를 가져올 수 있습니다. 이 예시에서는 Python 3의 최신 부 릴리스를 사용합니다.
name: Python package
on: [push]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Python
# This is the version of the action for setting up Python, not the Python version.
uses: actions/setup-python@v5
with:
# Semantic version range syntax or exact version of a Python version
python-version: '3.x'
# Optional - x64 or x86 architecture, defaults to x64
architecture: 'x64'
# You can test your matrix by printing the current Python version
- name: Display Python version
run: python -c "import sys; print(sys.version)"
name: Python package
on: [push]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Python
# This is the version of the action for setting up Python, not the Python version.
uses: actions/setup-python@v5
with:
# Semantic version range syntax or exact version of a Python version
python-version: '3.x'
# Optional - x64 or x86 architecture, defaults to x64
architecture: 'x64'
# You can test your matrix by printing the current Python version
- name: Display Python version
run: python -c "import sys; print(sys.version)"
버전 제외
사용할 수 없는 Python 버전을 지정하면 setup-python이 ##[error]Version 3.7 with arch x64 not found 오류와 함께 실패합니다. 오류 메시지에는 사용 가능한 버전이 포함됩니다.
실행하지 않으려는 Python 구성이 있는 경우 워크플로에서 exclude 키워드를 사용할 수도 있습니다. 자세한 내용은 GitHub Actions에 대한 워크플로 구문을(를) 참조하세요.
name: Python package
on: [push]
jobs:
build:
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-latest, macos-latest, windows-latest]
python-version: ["3.9", "3.11", "3.13", "pypy3.10"]
exclude:
- os: macos-latest
python-version: "3.11"
- os: windows-latest
python-version: "3.11"
name: Python package
on: [push]
jobs:
build:
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-latest, macos-latest, windows-latest]
python-version: ["3.9", "3.11", "3.13", "pypy3.10"]
exclude:
- os: macos-latest
python-version: "3.11"
- os: windows-latest
python-version: "3.11"
기본 Python 버전 사용
종속성을 명시적으로 설정하는 데 도움이 되므로 setup-python을 사용하여 워크플로에서 사용되는 Python 버전을 구성하는 것이 좋습니다. setup-python을 사용하지 않으면 python을 호출할 때 PATH에서 설정된 Python의 기본 버전이 모든 셸에서 사용됩니다. Python의 기본 버전은 GitHub 호스트 실행기마다 다르며 이로 인해 예기치 않은 변경이 발생하거나 예상보다 이전 버전을 사용할 수 있습니다.
| GitHub 호스트 실행기 | 설명 |
|---|---|
| Ubuntu | Ubuntu 실행기에는 /usr/bin/python 및 /usr/bin/python3에 설치된 여러 버전의 시스템 Python이 있습니다. Ubuntu와 함께 패키지된 Python 버전은 GitHub가 도구 캐시에 설치하는 버전에 추가됩니다. |
| Windows | 도구 캐시에 있는 Python 버전을 제외하고 Windows에는 동일한 버전의 시스템 Python이 제공되지 않습니다. 다른 실행기와 일관된 동작을 유지하고 setup-python 작업 없이 즉시 사용 가능한 Python을 허용하기 위해 GitHub는 도구 캐시의 몇 가지 버전을 PATH에 추가합니다. |
| macOS | macOS 실행기에는 도구 캐시의 일부인 버전 외에 둘 이상의 시스템 Python 버전이 설치되어 있습니다. 시스템 Python 버전은 /usr/local/Cellar/python/* 디렉터리에 있습니다. |
종속성 설치
GitHub 호스트 실행기에는 pip 패키지 관리자가 설치되어 있습니다. 코드를 빌드하고 테스트하기 전에 pip을 사용하여 PyPI 패키지 레지스트리에서 종속성을 설치할 수 있습니다. 예를 들어 아래 YAML은 pip 패키지 설치 프로그램과 setuptools 및 wheel 패키지를 설치하거나 업그레이드합니다.
종속성을 캐시하여 워크플로 속도를 높일 수도 있습니다. 자세한 내용은 워크플로 속도를 높이기 위한 종속성 캐싱을(를) 참조하세요.
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.x'
- name: Install dependencies
run: python -m pip install --upgrade pip setuptools wheel
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.x'
- name: Install dependencies
run: python -m pip install --upgrade pip setuptools wheel
요구 사항 파일
pip을 업데이트한 후 일반적인 다음 단계는 _requirements.txt_에서 종속성을 설치하는 것입니다. 자세한 내용은 pip를 참조하세요.
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.x'
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install -r requirements.txt
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.x'
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install -r requirements.txt
종속성 캐싱
setup-python작업을 사용하여 종속성을 캐시하고 복원할 수 있습니다.
다음 예시에서는 pip에 대한 종속성을 캐시합니다.
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.12'
cache: 'pip'
- run: pip install -r requirements.txt
- run: pip test
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.12'
cache: 'pip'
- run: pip install -r requirements.txt
- run: pip test
기본적으로 setup-python 작업은 전체 리포지토리에서 종속성 파일(pip의 경우 requirements.txt, pipenv의 경우 Pipfile.lock 또는 poetry의 경우 poetry.lock)을 검색합니다. 자세한 내용은 setup-python 추가 정보에서 패키지 종속성 캐싱을 참조하세요.
사용자 지정 요구사항이 있거나 캐싱에 대한 세부적인 제어가 필요한 경우 cache 작업을 사용할 수 있습니다. pip는 실행기의 운영 체제에 따라 다른 위치에 종속성을 캐시합니다. 캐시해야 하는 경로는 사용하는 운영 체제에 따라 위의 Ubuntu 예시와 다를 수 있습니다. 자세한 내용은 cache 작업 리포지토리에서 Python 캐싱 예시를 참조하세요.
코드 테스트
코드를 빌드하고 테스트하기 위해 로컬에서 사용하는 것과 동일한 명령을 사용할 수 있습니다.
pytest 및 pytest-cov를 사용하여 테스트
제에서pytest``pytest-cov 그런 다음 테스트가 실행되어 JUnit 형식으로 출력되고 코드 검사 결과는 Cobertura로 출력됩니다. 자세한 내용은 JUnit 및 Cobertura를 참조하세요.
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.x'
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install -r requirements.txt
- name: Test with pytest
run: |
pip install pytest pytest-cov
pytest tests.py --doctest-modules --junitxml=junit/test-results.xml --cov=com --cov-report=xml --cov-report=html
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.x'
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install -r requirements.txt
- name: Test with pytest
run: |
pip install pytest pytest-cov
pytest tests.py --doctest-modules --junitxml=junit/test-results.xml --cov=com --cov-report=xml --cov-report=html
Ruff를 사용하여 코드 린팅 및/또는 서식 지정
다음 예시에서는 ruff을(를) 설치하거나 업그레이드하고 이를 사용하여 모든 파일을 린트합니다. 자세한 내용은 Ruff를 참조하세요.
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.x'
- name: Install the code linting and formatting tool Ruff
run: pipx install ruff
- name: Lint code with Ruff
run: ruff check --output-format=github --target-version=py39
- name: Check code formatting with Ruff
run: ruff format --diff --target-version=py39
continue-on-error: true
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.x'
- name: Install the code linting and formatting tool Ruff
run: pipx install ruff
- name: Lint code with Ruff
run: ruff check --output-format=github --target-version=py39
- name: Check code formatting with Ruff
run: ruff format --diff --target-version=py39
continue-on-error: true
서식 지정 단계가 continue-on-error: true 설정되었습니다. 이렇게 하면 서식 지정 단계가 성공하지 못한 경우 워크플로가 실패하지 않습니다. 모든 서식 지정 오류를 해결했으면 워크플로가 새 문제를 catch할 수 있도록 해당 옵션을 제거할 수 있습니다.
tox를 사용하여 테스트 실행
GitHub Actions를 사용하면 tox로 테스트를 실행하고 여러 작업에 작업을 분산할 수 있습니다. 특정 버전을 지정하는 대신 PATH에서 Python 버전을 선택하려면 -e py 옵션을 사용하여 tox를 호출해야 합니다. 자세한 내용은 tox를 참조하세요.
name: Python package
on: [push]
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
python: ["3.9", "3.11", "3.13"]
steps:
- uses: actions/checkout@v4
- name: Setup Python
uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python }}
- name: Install tox and any other packages
run: pip install tox
- name: Run tox
# Run tox using the version of Python in `PATH`
run: tox -e py
name: Python package
on: [push]
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
python: ["3.9", "3.11", "3.13"]
steps:
- uses: actions/checkout@v4
- name: Setup Python
uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python }}
- name: Install tox and any other packages
run: pip install tox
- name: Run tox
# Run tox using the version of Python in `PATH`
run: tox -e py
워크플로 데이터를 아티팩트로 패키지
워크플로가 완료된 후 볼 아티팩트를 업로드할 수 있습니다. 예를 들어 로그 파일, 코어 덤프, 테스트 결과 또는 스크린샷을 저장해야 할 수 있습니다. 자세한 내용은 워크플로에서 데이터 저장 및 공유을(를) 참조하세요.
다음 예시는 upload-artifact 작업을 사용하여 pytest 실행의 테스트 결과를 보관하는 방법을 보여 줍니다. 자세한 내용은 upload-artifact 작업을 참조하세요.
name: Python package
on: [push]
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
steps:
- uses: actions/checkout@v4
- name: Setup Python # Set Python version
uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python-version }}
# Install pip and pytest
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install pytest
- name: Test with pytest
run: pytest tests.py --doctest-modules --junitxml=junit/test-results-${{ matrix.python-version }}.xml
- name: Upload pytest test results
uses: actions/upload-artifact@v4
with:
name: pytest-results-${{ matrix.python-version }}
path: junit/test-results-${{ matrix.python-version }}.xml
# Use always() to always run this step to publish test results when there are test failures
if: ${{ always() }}
name: Python package
on: [push]
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
steps:
- uses: actions/checkout@v4
- name: Setup Python # Set Python version
uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python-version }}
# Install pip and pytest
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install pytest
- name: Test with pytest
run: pytest tests.py --doctest-modules --junitxml=junit/test-results-${{ matrix.python-version }}.xml
- name: Upload pytest test results
uses: actions/upload-artifact@v4
with:
name: pytest-results-${{ matrix.python-version }}
path: junit/test-results-${{ matrix.python-version }}.xml
# Use always() to always run this step to publish test results when there are test failures
if: ${{ always() }}
PyPI에 게시
CI 테스트를 통과하면 Python 패키지를 PyPI에 게시하도록 워크플로를 구성할 수 있습니다. 이 섹션에서는 릴리스를 게시할 때마다 GitHub Actions를 사용하여 PyPI에 패키지를 업로드하는 방법을 보여 줍니다. 자세한 내용은 리포지토리에서 릴리스 관리을(를) 참조하세요.
아래 예시 워크플로에서는 신뢰할 수 있는 게시를 사용하여 PyPI를 인증하므로 수동으로 구성된 API 토큰이 필요하지 않습니다.
# 이 워크플로는 GitHub에서 인증되지 않은 작업을 사용합니다.
# 작업은 타사에서 제공하며
# 별도의 서비스 약관, 개인정보처리방침, 지원 설명서에서 규정됩니다.
# 참조하세요.
# 커밋 SHA에 작업을 고정하는 것이 좋습니다.
# 최신 버전을 얻으려면 SHA를 업데이트해야 합니다.
# 태그 또는 분기를 참조할 수도 있지만 경고 없이 작업이 변경될 수 있습니다.
name: Upload Python Package
on:
release:
types: [published]
permissions:
contents: read
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 distributions
uses: actions/upload-artifact@v4
with:
name: release-dists
path: dist/
pypi-publish:
runs-on: ubuntu-latest
needs:
- release-build
permissions:
# IMPORTANT: this permission is mandatory for trusted publishing
id-token: write
# Dedicated environments with protections for publishing are strongly recommended.
environment:
name: pypi
# OPTIONAL: uncomment and update to include your PyPI project URL in the deployment status:
# url: https://pypi.org/p/YOURPROJECT
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@6f7e8d9c0b1a2c3d4e5f6a7b8c9d0e1f2a3b4c5d
# 이 워크플로는 GitHub에서 인증되지 않은 작업을 사용합니다.
# 작업은 타사에서 제공하며
# 별도의 서비스 약관, 개인정보처리방침, 지원 설명서에서 규정됩니다.
# 참조하세요.
# 커밋 SHA에 작업을 고정하는 것이 좋습니다.
# 최신 버전을 얻으려면 SHA를 업데이트해야 합니다.
# 태그 또는 분기를 참조할 수도 있지만 경고 없이 작업이 변경될 수 있습니다.
name: Upload Python Package
on:
release:
types: [published]
permissions:
contents: read
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 distributions
uses: actions/upload-artifact@v4
with:
name: release-dists
path: dist/
pypi-publish:
runs-on: ubuntu-latest
needs:
- release-build
permissions:
# IMPORTANT: this permission is mandatory for trusted publishing
id-token: write
# Dedicated environments with protections for publishing are strongly recommended.
environment:
name: pypi
# OPTIONAL: uncomment and update to include your PyPI project URL in the deployment status:
# url: https://pypi.org/p/YOURPROJECT
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@6f7e8d9c0b1a2c3d4e5f6a7b8c9d0e1f2a3b4c5d
필요한 PyPI 설정을 포함하여 이 워크플로에 대한 자세한 내용은 PyPI에서 OpenID Connect 구성하기 항목을 참조하세요.