GitHub Actions入門｜初心者向けに自動テストの始め方を実例で解説

2025.04.07
この記事は約12分で読めます。

GitHubへコードをpushするたびに、毎回自分でテストを実行するのは意外と手間がかかります。

「テストするのを忘れたまま変更を反映してしまった」
「自分のPCでは動いたのに、別の環境では失敗した」

こうしたミスを減らすために使えるのが GitHub Actions です。

GitHub Actionsを使うと、GitHub上でコードが変更されたタイミングに合わせて、テストやビルドなどの処理を自動実行できます。

この記事では、GitHub Actionsを初めて触る人向けに、次の内容を実際に動かせる最小構成で解説します。

  • GitHub Actionsで何ができるのか
  • ワークフローをどこに作るのか
  • Pythonのテストを自動実行する方法
  • 成功・失敗をどこで確認するのか
  • 動かないときに何から確認すればよいのか

複雑なCI/CD環境を最初から作るのではなく、まずは「コードをpushしたらテストが自動で実行される」ところまでを目標にします。

GitHub Actionsとは

GitHub Actionsは、GitHub上の操作をきっかけに処理を自動実行できる仕組みです。

たとえば、次のような処理を自動化できます。

  • コードをpushしたら自動でテストする
  • Pull Requestを作ったら自動でチェックする
  • アプリケーションをビルドする
  • 条件を満たしたらデプロイする
  • 決められた日時に処理を実行する

GitHubでは、この一連の自動処理をワークフロー（workflow）として定義します。

初心者の段階では、いきなり本番環境へのデプロイまで自動化する必要はありません。

まずは、

コードをpushしたらテストが自動で実行される

という仕組みを作ると、GitHub Actionsの基本を理解しやすくなります。

GitHub Actionsの基本構造

GitHub Actionsを使うには、リポジトリ内に次のようなフォルダを作ります。

.github/
└─ workflows/
   └─ python-test.yml

重要なのは、次の場所です。

.github/workflows/

この配下に .yml または .yaml ファイルを置くと、GitHubがワークフローとして認識します。

ファイル名自体は自由なので、たとえば次のような名前で構いません。

ci.yml
test.yml
python-test.yml

何をするワークフローなのか分かる名前にしておくと、後から管理しやすくなります。

まずはPythonの簡単なテストを用意する

今回は、できるだけ小さい構成でGitHub Actionsを動かしてみます。

まず main.py を作ります。

def add(x, y):
    return x + y

次に test_main.py を作ります。

from main import add


def test_add():
    assert add(2, 3) == 5

ここでは、

add(2, 3)

の結果が 5 になるかをpytestで確認します。

この時点でファイル構成は次のようになります。

リポジトリ
├─ main.py
├─ test_main.py
└─ .github
   └─ workflows
      └─ python-test.yml

GitHub Actionsのワークフローを作る

次に、.github/workflows/python-test.yml を作成して、次の内容を書きます。

name: Python Tests

on:
  push:
  pull_request:

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v6

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.13"

      - name: Install pytest
        run: |
          python -m pip install --upgrade pip
          python -m pip install pytest

      - name: Run tests
        run: pytest -q

このファイルをGitHubへpushすると、GitHub Actionsがワークフローを読み込みます。

最初はYAML全体を理解する必要はありません。

重要な部分を順番に見ていきます。

name：ワークフローの名前

name: Python Tests

GitHubのActions画面に表示されるワークフロー名です。

今回はPythonのテストを実行するので、Python Tests としています。

on：いつ実行するか

on:
  push:
  pull_request:

on では、どの操作をきっかけにワークフローを実行するかを指定します。

今回の設定では、

  • pushされたとき
  • Pull Requestに変更が入ったとき

にワークフローが実行されます。

たとえばpush時だけ実行したければ、次のようにできます。

on:
  push:

GitHub Actionsが動かない場合は、この on の条件と実際に行った操作が一致しているかを確認することが重要です。

permissions：ワークフローの権限

permissions:
  contents: read

GitHub Actionsがリポジトリに対して持つ権限を指定しています。

今回必要なのはコードを読み取ることだけなので、contents: read としています。

初心者のうちは、GitHub Actionsが動かないからといって、必要以上に強い書き込み権限を付けるのは避けた方が安全です。

まずは必要な権限だけを設定します。

runs-on：どの環境で実行するか

runs-on: ubuntu-latest

GitHub Actionsを実行する環境を指定しています。

今回はGitHubが用意しているUbuntu環境を使用します。

処理はGitHub側の実行環境で行われるため、GitHub Actionsを動かすために自分のPCを起動したままにしておく必要はありません。

checkout：リポジトリのコードを取得する

- name: Checkout repository
  uses: actions/checkout@v6

GitHub Actionsの実行環境へ、リポジトリに保存されているコードを取得しています。

これがないと、後続のテスト処理から main.py や test_main.py を利用できません。

uses: は、あらかじめ用意されているActionを利用するときに使います。

setup-python：Python環境を準備する

- name: Set up Python
  uses: actions/setup-python@v5
  with:
    python-version: "3.13"

GitHub Actionsの実行環境でPythonを利用できるようにしています。

今回使用するPythonのバージョンは、

python-version: "3.13"

で指定しています。

自分のPCで使っているPythonとGitHub Actions側のPythonが違うと、環境差による問題が発生することがあります。

そのため、ワークフロー側でも使用するPythonバージョンを明示しておくと管理しやすくなります。

pytestをインストールする

- name: Install pytest
  run: |
    python -m pip install --upgrade pip
    python -m pip install pytest

テストで使用するpytestをインストールしています。

ここで注意したいのは、自分のPCとGitHub Actionsの実行環境は別物だという点です。

自分のPCにpytestがインストールされていても、GitHub Actions側で自動的に使えるとは限りません。

GitHub Actionsで必要になるライブラリは、ワークフロー内で準備します。

テストを実行する

最後にpytestを実行します。

- name: Run tests
  run: pytest -q

ここまで正常に動けば、

コードをpushする
↓
GitHub Actionsが起動する
↓
Python環境が準備される
↓
pytestがインストールされる
↓
テストが実行される

という流れが自動化されます。

実際にpushして結果を確認する

ワークフローファイルを作成したら、GitHubへpushします。

その後、対象リポジトリを開いて上部にある Actions タブを確認します。

GitHub Actionsが正常に開始されていれば、実行履歴が表示されます。

テストが成功すると、正常終了したことを示す表示になります。

失敗した場合は、実行されたワークフローを開いてください。

さらにジョブを開くと、

Checkout repository
Set up Python
Install pytest
Run tests

といったStepごとの結果を確認できます。

GitHub Actionsで問題が起きたときは、まずどのStepで失敗したかを見ることが重要です。

GitHub Actionsが動かないときの確認順

GitHub Actionsでエラーが発生すると、YAMLを全部書き直したくなるかもしれません。

しかし、最初にやるべきなのは原因の切り分けです。

次の順番で確認すると、問題を絞り込みやすくなります。

1．Actionsに実行履歴自体がない

まず次の3点を確認します。

ワークフローファイルが、

.github/workflows/

に保存されているか確認してください。

次に、ファイルの拡張子が、

.yml

または、

.yaml

になっているか確認します。

さらに、on: に実際に行った操作が指定されているか確認します。

たとえば、

on:
  push:

と設定している場合、pushが発生しなければワークフローは実行されません。

実行履歴が存在しない場合は、テスト内容より先に「GitHub Actionsが起動する条件」を確認するのがポイントです。

2．ワークフローは動くが途中で失敗する

Actions画面で、失敗しているStepを確認します。

たとえば、

Install pytest

で止まっているなら、ライブラリのインストールやPython環境に問題がある可能性があります。

一方、

Run tests

で止まっているなら、pytest自体は起動していて、テストコードや対象コードに問題がある可能性があります。

単に、

「GitHub Actionsが失敗した」

と考えるのではなく、

「どのStepまで成功して、どこから失敗したか」

を確認してください。

これだけでも原因をかなり絞り込めます。

3．pytest: command not found が表示される

pytestがGitHub Actionsの実行環境へインストールされているか確認します。

たとえば、次のStepがテスト実行より前に必要です。

- name: Install pytest
  run: python -m pip install pytest

自分のPCでpytestが動いていても、GitHub Actions側にpytestが入っているとは限りません。

ローカル環境とGitHub Actions環境は分けて考えます。

4．YAMLを変更した直後から動かなくなった

YAMLでは、インデントが構造を表します。

スペースの位置が変わるだけでも、設定が意図したものと異なることがあります。

変更前は動いていて、変更後から問題が発生した場合は、最後に変更した部分から確認するのが基本です。

一度に大量の設定を変更するより、

小さく変更
↓
push
↓
結果確認

を繰り返した方が原因を追いやすくなります。

requirements.txt がある場合

実際のPythonプロジェクトでは、pytest以外にも複数のライブラリを使うことがあります。

その場合、requirements.txt を用意していることも多いでしょう。

たとえば、次のようにインストールできます。

- name: Install dependencies
  run: |
    python -m pip install --upgrade pip
    pip install -r requirements.txt

これなら必要なライブラリを1つずつYAMLへ書く必要がありません。

プロジェクトで必要なPythonパッケージを requirements.txt にまとめて管理できます。

自動デプロイはテストが動いてからでいい

GitHub Actionsでは、本番環境へのデプロイまで自動化できます。

しかし、初心者が最初から、

push
↓
テスト
↓
本番環境へデプロイ

まで作る必要はありません。

デプロイは設定を間違えた場合の影響も大きくなります。

まずは、

push
↓
自動テスト
↓
結果を確認

まで安定して動かすことをおすすめします。

テストが安定してから、必要に応じてビルドやデプロイを追加していけば十分です。

パスワードやAPIキーをYAMLへ直接書かない

GitHub Actionsから外部サービスへ接続する場合、APIキーやパスワードなどが必要になることがあります。

こうした機密情報を次のようにYAMLへ直接書くのは避けてください。

API_KEY: abcdef123456

リポジトリに保存した情報が意図せず公開される危険があります。

機密情報をGitHub Actionsから利用する場合は、GitHubのSecretsなどを利用して管理します。

特に公開リポジトリでは、コードだけでなく設定ファイルに機密情報が含まれていないか注意が必要です。

ChatGPTなどのAIを使ってエラーを調べるときの注意点

GitHub Actionsのエラー解析では、ChatGPTなどのAIも補助として使えます。

たとえばログを渡して、

このGitHub Actionsのログについて、

1. 失敗しているStep
2. 直接のエラー
3. 原因候補
4. 最初に確認すべき設定

の順で説明してください。

と聞けば、長いログを整理しやすくなります。

ただし、AIが生成したYAMLをそのまま本番環境へ投入するのは避けた方が安全です。

GitHub Actionsでは、利用するActionやバージョン、権限設定などが更新されることがあります。

AIへ作成を依頼した場合でも、少なくとも次の項目は確認してください。

  • uses: で指定されているAction
  • Actionのバージョン
  • ワークフローへ与えている権限
  • GitHub公式ドキュメント
  • 利用するActionの公式README

また、GitHub ActionsのログをAIへ渡す場合は、APIキー、アクセストークン、パスワード、社内URLなどの機密情報が含まれていないか確認してください。

GitHub Actionsで初心者が最初に覚えること

GitHub Actionsには多くの機能がありますが、最初からすべて覚える必要はありません。

まずは、

コードをpushする
↓
GitHub Actionsが起動する
↓
テストが実行される
↓
Actions画面で結果を確認する

という流れを一度自分で動かしてみることが重要です。

失敗した場合も、いきなり設定を全部変更するのではなく、

そもそもワークフローが起動しているか
↓
どのStepまで成功しているか
↓
どのStepで失敗したか
↓
そのStepのログに何が書かれているか

の順番で確認します。

この考え方が身につけば、ワークフローが複雑になっても問題を切り分けやすくなります。

GitHub Actionsを「難しいYAMLを書く機能」と考えるより、

人が毎回行っている確認作業を、GitHubに代わりに実行してもらう仕組み

と考えると理解しやすくなります。

まずは小さな自動テストから始めて、安定して動くことを確認してから、自分のプロジェクトに必要な処理を少しずつ追加していきましょう。

タイトルとURLをコピーしました