ドキュメントには頻繁に更新が加えられ、その都度公開されています。本ページの翻訳はまだ未完成な部分があることをご了承ください。最新の情報については、英語のドキュメンテーションをご参照ください。本ページの翻訳に問題がある場合はこちらまでご連絡ください。

GitHub ActionsでのPythonの利用

Pythonプロジェクトのビルドとテストのための継続的インテグレーション(CI)ワークフローを作成できます。

ここには以下の内容があります:

はじめに

このガイドは、Pythonパッケージのビルド、テスト、公開の方法を紹介します。

GitHubホストランナーは、Python及びPyPyを含むプリインストールされたソフトウェアを伴うツールキャッシュを持ちます。 自分では何もインストールする必要がありません! 最新のソフトウェアとプリインストールされたバージョンのPython及びPyPyの完全なリストについては、GitHubホストランナー上にインストールされているソフトウェアを参照してください。

必要な環境

YAMLとGitHub Actionsの構文に馴染んでいる必要があります。 詳細については、「GitHub Actionsのワークフロー構文」を参照してください。

Python、PyPy、pipの基本的な理解をしておくことをおすすめします。 詳しい情報については、以下を参照してください。

Pythonワークフローテンプレートでの開始

GitHubは、ほとんどのPythonプロジェクトで使えるPythonのワークフローテンプレートを提供しています。 このガイドには、テンプレートのカスタマイズに利用できる例が含まれます。 詳しい情報についてはPythonのワークフローテンプレートを参照してください。

手早く始めるために、テンプレートをリポジトリの.github/workflowsディレクトリに追加してください。

name: Python package

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: [2.7, 3.5, 3.6, 3.7, 3.8]

    steps:
    - uses: actions/checkout@v2
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v2
      with:
        python-version: ${{ matrix.python-version }}
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install flake8 pytest
        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
    - name: Lint with flake8
      run: |
        # stop the build if there are Python syntax errors or undefined names
        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
        # exit-zeroはすべてのエラーを警告として扱う。 GitHubのエディタの幅は127文字
        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
    - name: Test with pytest
      run: |
        pytest

Pythonのバージョンの指定

GitHubホストランナー上でPythonもしくはPyPyのプリインストールされたバージョンを使うには、setup-pythonアクションを使ってください。 このアクションは各ランナーのツールキャッシュから指定されたバージョンのPythonもしくはPyPyを見つけ、必要なバイナリをPATHに追加します。設定されたバイナリは、ジョブでそれ以降永続化されます。 If a specific version of Python is not pre-installed in the tools cache, the setup-python action will download and set up the appropriate version from the python-versions repository.

setup-actionの利用は、GitHub ActionsでPythonを使うための推奨される方法です。これは、そうすることで様々なランナーや様々なバージョンのPythonで一貫した振る舞いが保証されるためです。 セルフホストランナーを使っている場合は、PythonをインストールしてPATHに追加しなければなりません。 詳細については、setup-pythonアクションを参照してください。

以下の表は、各GitHubホストランナー内でのツールキャッシュの場所です。

UbuntuMacWindows
ツールキャッシュディレクトリ/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\*

If you are using a self-hosted runner, you can configure the runner to use the setup-python action to manage your dependencies. For more information, see using setup-python with a self-hosted runner in the setup-python README.

GitHubは、セマンティックバージョン構文をサポートしています。 詳しい情報については「セマンティックバージョンの利用」及び「セマンティックバージョンの仕様」を参照してください。

Pythonの複数バージョンの利用

name: Python package

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest
    strategy:
      # python-version内のPyPyのバージョンが利用できる。
      # For example, pypy2 and pypy3
      matrix:
        python-version: [2.7, 3.5, 3.6, 3.7, 3.8]

    steps:
    - uses: actions/checkout@v2
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v2
      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.8が利用できます。あるいは、セマンティックバージョン構文を使い、最新のマイナーリリースを使うことができます。 以下の例では、Python 3の最新のマイナーリリースを使います。

name: Python package

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - name: Set up Python 3.x
      uses: actions/setup-python@v2
      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.4 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: [2.7, 3.6, 3.7, 3.8, pypy2, pypy3]
        exclude:
          - os: macos-latest
            python-version: 3.6
          - os: windows-latest
            python-version: 3.6

デフォルトバージョンのPythonの利用

依存関係を明示的にしやすくなるので、ワークフロー中で使うPythonのバージョンの設定にはsetup-pythonを使うことをおすすめします。 setup-pythonを使わない場合、いずれかのシェルでpythonを呼ぶとPATHに設定されたデフォルトバージョンのPythonが使われます。 デフォルトバージョンのPythonは、GitHubホストランナーによって様々なので、予想外の変更が生じたり、期待しているよりも古いバージョンが使われたりするかもしれません。

GitHubホストランナー説明
UbuntuUbuntuランナーでは/usr/bin/python及び/usr/bin/python3の下に複数バージョンのシステムPythonがあります。 GitHubがツールキャッシュにインストールしエチルバージョンに加えて、UbuntuにパッケージングされているバージョンのPythonがあります。
WindowsツールキャッシュにあるPythonのバージョンを除けば、WindowsにはシステムPythonに相当するバージョンは含まれていません。 他のランナーとの一貫した動作を保ち、setup-pythonアクションなしですぐにPythonが使えるようにするため、GitHubはツールキャッシュからいくつかのバージョンをPATHに追加します。
macOSmacOSランナーには、ツールキャッシュ内のバージョンに加えて、複数バージョンのシステムPythonがインストールされています。 システムのPythonバージョンは/usr/local/Cellar/python/*mディレクトリにあります。

依存関係のインストール

GitHubホストランナーには、パッケージマネージャーのpipがインストールされています。 コードのビルドとテストに先立って、pipを使ってパッケージレジストリのPyPIから依存関係をインストールできます。 たとえば以下のYAMLはpipパッケージインストーラーとsetuptools及びwheelパッケージのインストールやアップグレードを行います。

ワークフローの速度を上げるために、依存関係をキャッシュすることもできます。 詳しい情報については「ワークフローを高速化するための依存関係のキャッシング」を参照してください。

steps:
- uses: actions/checkout@v2
- name: Set up Python
  uses: actions/setup-python@v2
  with:
    python-version: '3.x'
- name: Install dependencies
  run: python -m pip install --upgrade pip setuptools wheel

Requirementsファイル

pipをアップデートした後、次の典型的なステップはrequirements.txtからの依存関係のインストールです。

steps:
- uses: actions/checkout@v2
- name: Set up Python
  uses: actions/setup-python@v2
  with:
    python-version: '3.x'
- name: Install dependencies
  run: |
    python -m pip install --upgrade pip
    pip install -r requirements.txt

依存関係のキャッシング

cacheアクションを使って、ユニークキーを使ってpipの依存関係をキャッシュし、将来のワークフローの実行で依存関係をリストアできます。 詳しい情報については「ワークフローを高速化するための依存関係のキャッシング」を参照してください。

ランナーのオペレーティングシステムによって、pipは依存関係を様々な場所にキャッシュします。 キャッシュする必要があるパスは、使用するオペレーティングシステムによって以下のUbuntuの例とは異なるかもしれません。 詳しい情報についてはPythonのキャッシングの例を参照してください。

steps:
- uses: actions/checkout@v2
- name: Setup Python
  uses: actions/setup-python@v2
  with:
    python-version: '3.x'
- name: Cache pip
  uses: actions/cache@v2
  with:
    # This path is specific to Ubuntu
    path: ~/.cache/pip
    # Look to see if there is a cache hit for the corresponding requirements file
    key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
    restore-keys: |
      ${{ runner.os }}-pip-
      ${{ runner.os }}-
- name: Install dependencies
  run: pip install -r requirements.txt

ノート: 依存関係の数によっては、依存関係キャッシュを使う方が高速になることがあります。 多くの大きな依存関係を持つプロジェクトでは、ダウンロードに必要な時間を節約できるので、パフォーマンスの向上が見られるでしょう。 依存関係が少ないプロジェクトでは、大きなパフォーマンスの向上は見られないかもしれず、pipがキャッシュされた依存関係をインストールする方法のために、パフォーマンスがやや低下さえするかもしれません。 パフォーマンスはプロジェクトによって異なります。

コードのテスト

ローカルで使うのと同じコマンドを、コードのビルドとテストに使えます。

pytest及びpytest-covでのテスト

以下の例では、pytest及びpytest-covをインストールあるいはアップグレードします。 そしてテストが実行され、JUnit形式で出力が行われ、一方でコードカバレッジの結果がCoberturaに出力されます。 詳しい情報についてはJUnit及びCoberturaを参照してください。

steps:
- uses: actions/checkout@v2
- name: Set up Python
  uses: actions/setup-python@v2
  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
    pip install pytest-cov
    pytest tests.py --doctest-modules --junitxml=junit/test-results.xml --cov=com --cov-report=xml --cov-report=html

Flake8を使ったコードのlint

以下の例は、flake8をインストールもしくはアップグレードし、それを使ってすべてのファイルをlintします。 詳しい情報についてはFlake8を参照してください。

steps:
- uses: actions/checkout@v2
- name: Set up Python
  uses: actions/setup-python@v2
  with:
    python-version: '3.x'
- name: Install dependencies
  run: |
    python -m pip install --upgrade pip
    pip install -r requirements.txt
- name: Lint with flake8
  run: |
    pip install flake8
    flake8 .

toxでのテストの実行

GitHub Actionsでは、toxでテストを実行し、その処理を複数のジョブに分散できます。 toxを起動する際には、特定のバージョンを指定するのではなく、-e pyオプションを使ってPATH中のPythonのバージョンを選択しなければなりません。 詳しい情報については toxを参照してください。

name: Python package

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest
    strategy:
      matrix:
        python: [2.7, 3.7, 3.8]

    steps:
      - uses: actions/checkout@v2
      - name: Setup Python
        uses: actions/setup-python@v2
        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: [2.7, 3.5, 3.6, 3.7, 3.8]

      steps:
      - uses: actions/checkout@v2
      - name: Setup Python # Set Python version
        uses: actions/setup-python@v2
        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@v2
        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() }}

パッケージレジストリへの公開

CIテストにパスしたなら、Pythonパッケージを任意のパッケージレジストリに公開するようにワークフローを設定できます。

パッケージを公開するのに必要なアクセストークンやクレデンシャルは、リポジトリシークレットを使って保存できます。 以下の例では、twinedistを使ってパッケージを作成してPyPIに公開しています。 詳しい情報については、「暗号化されたシークレットの作成と利用」を参照してください。

name: Upload Python Package

on:
  release:
    types: [created]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Set up Python
      uses: actions/setup-python@v2
      with:
        python-version: '3.x'
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install setuptools wheel twine
    - name: Build and publish
      env:
        TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }}
        TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
      run: |
        python setup.py sdist bdist_wheel
        twine upload dist/*

テンプレートワークフローに関する詳しい情報についてはpython-publishを参照してください。

担当者にお尋ねください

探しているものが見つからなかったでしょうか?

弊社にお問い合わせください