GitHubで管理しているコードを変更するたびに、同じテストを実行していませんか。GitHub Actionsを使うと、「変更が届いたらテストする」「毎朝決まった処理を動かす」といった作業を、条件に合わせて実行できます。

GitHub Actionsは自動化を実行する仕組み、ワークフローは実行手順、YAMLはその手順を書く形式です。この記事では、README.mdが空でないかを確認する小さなワークフローを作り、手動実行から定期実行へ進みます。

目次

1.GitHub Actionsとは?ワークフローとYAMLの関係

GitHub Actionsは、GitHubのリポジトリに関するイベント、手動操作、スケジュールなどをきっかけに処理を実行する機能です。プルリクエストのテストや公開用ファイルのビルドなどに利用できます。

ワークフローには「いつ動かすか」「どの環境で何をするか」を書きます。例えばPythonのテストを自動化するなら、YAMLに実行条件やテストコマンドを書き、テストの判定内容はPython側に用意します。

用語役割今回の例
Workflow(ワークフロー)自動化する手順の全体README.mdを確認する
Event(実行のきっかけ)どの条件で始めるかGitHub画面から手動で開始する
Job(ジョブ)ステップをまとめた作業単位ファイルを取得し、確認する
Runner(ランナー)ジョブを実行する環境GitHubが用意するUbuntuの環境
Step(ステップ)ジョブの中で順に実行する処理ファイルの取得、ファイルの確認
Action(アクション)ステップから呼び出せる再利用可能な処理公式のactions/checkoutを使ってファイルを取得する

「GitHub Actions」と、その中で呼び出す一つの「アクション」は区別すると分かりやすくなります。ワークフローの中では、既存のアクションを呼ぶことも、自分で書いたコマンドを実行することもできます。

2.手動で試せるワークフローを作る

最初は、練習用のリポジトリを用意し、直下に内容のあるREADME.mdを置きます。今回は、そのファイルが存在し、空でなければ成功にします。判定の基準が明確なので、実行結果を見ながら仕組みを理解できます。

次の内容を、リポジトリのルートを基準に.github/workflows/readme-check.ymlとして保存します。演習では、まずワークフローファイルをデフォルトブランチに反映してください。チームのリポジトリでは、普段のレビューやマージの手順に従います。

name: README check on: workflow_dispatch: permissions: contents: read jobs: check-readme: runs-on: ubuntu-latest timeout-minutes: 5 steps: – name: Check out repository uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false – name: Check README.md shell: bash run: | if [ ! -f README.md ] || [ ! -s README.md ]; then echo ‘README.md is missing or empty.’ exit 1 fi echo ‘README.md is present and non-empty.’

YAMLは「いつ」「どこで」「何をするか」に分けて読む

  • on:実行のきっかけです。workflow_dispatchを指定すると、手動で開始できるようになります。
  • runs-on:ジョブを動かすランナーを選びます。今回はGitHubが提供するUbuntuの環境を使います。
  • uses:既存のアクションを呼び出します。今回はactions/checkoutで、確認対象のブランチのファイルをランナーに取得します。
  • run:ランナー上でコマンドを実行します。今回はREADME.mdの有無とサイズを確認します。
  • permissions:ワークフローに付与されるGITHUB_TOKENの権限を指定します。今回はリポジトリの内容を取得するための読み取り権限を指定しています。

YAMLでは、行頭の空白で設定のまとまりを表します。この例では1段ごとに半角スペース2つを使っています。stepsの下にある「-」はリストの1項目を表し、runの後の「|」は複数行のコマンドをまとめて書くための記号です。

usesの後ろにある長い文字列は、actions/checkout v7.0.1に対応するコミットの識別子です。このように固定すると、同じコードを参照できます。利用を続ける場合は、更新情報を確認し、必要に応じて固定先も見直しましょう。

Actionsタブで実行し、成功と失敗の両方を見る

  1. リポジトリのActionsタブを開きます。
  2. 左側からREADME checkを選び、Run workflowを押します。
  3. 対象ブランチを確認して開始し、作成された実行履歴を開きます。
  4. ジョブの中にあるCheck README.mdのログを開きます。

README.mdに内容があれば、ログに「README.md is present and non-empty.」と表示されます。練習用のブランチでREADME.mdを空にして実行すると、「README.md is missing or empty.」と表示され、ステップが失敗します。このサンプルが確認するのは、ファイルの有無とサイズまでです。

Run workflowが見つからない場合は、ファイルがデフォルトブランチにあるか、workflow_dispatchが設定されているか、自分にリポジトリへの書き込み権限があるかを確認してください。Actionsの利用を制限している組織では、リポジトリや組織の設定も関係します。

💡 あわせて読みたい関連記事

デフォルトブランチと作業用ブランチの違いが曖昧な方へ。変更を分けて記録し、マージする流れを解説しています。

GitHub開発の基本!ブランチ運用からマージ、コンフリクト解決まで完全解説 記事を読む →

3.手動で動いたら、作業に合う実行条件を選ぶ

実行条件は、作業が必要になるタイミングから決めます。例えば、変更内容をマージ前に確かめるテストと、毎朝のデータ集計では、実行するきっかけが違います。

設定実行のきっかけ使い道
workflow_dispatch人が手動で開始する初回の試行、内容確認後の処理
push指定した条件に合う変更がプッシュされるブランチへの反映後にテストやビルドを行う
pull_requestプルリクエストが作成・更新されるなど、対象のイベントが起きるマージ前に変更内容をテストする
schedule設定した時刻になる日次集計、定期的なデータ更新

毎朝8時17分に実行する設定例

先ほどのYAMLにあるonの部分だけを、以下に置き換えます。workflow_dispatchを残しているので、定期実行を設定した後も手動で確認できます。

on: workflow_dispatch: schedule: – cron: ’17 8 * * *’ timezone: ‘Asia/Tokyo’

cronの5項目は、左から「分・時・日・月・曜日」です。この例ではtimezoneで日本時間を指定しているので、毎日8時17分が実行予定になります。timezoneを省略すると、GitHub ActionsではUTCが基準です。

定期実行は、デフォルトブランチの最新コミットを使います。混雑時には遅れたり、実行が見送られたりする場合もあります。公開リポジトリでは、リポジトリに60日間活動がないと定期ワークフローが無効になるため、重要な処理では最終成功日時も確認しましょう。

4.動かないときは、どの段階で止まったかを見る

症状最初に確かめること
ワークフローが見つからない.github/workflows/の場所、拡張子、デフォルトブランチへの反映、YAMLのエラー
実行履歴が作られないイベントの設定、対象ブランチ、Actionsの有効・無効、実行する人の権限
実行されたが途中で失敗する失敗したステップのログ、ファイルの位置、必要な依存関係
緑の成功表示なのに結果が見つからない対象データがあったか、どこに結果を保存する設計か、外部処理まで確認できているか

手元のパソコンとランナーは別の環境です。手元だけにあるファイルやインストール済みのライブラリを前提にすると、ローカルでは動いてもActionsでは失敗します。ログに出たファイル名と、実行されたブランチを確認すると、原因を絞り込めます。

また、緑の成功表示は、ワークフローが設定上の成功条件を満たしたことを示します。ファイル生成なら保存先に結果があるか、外部サービスへの送信なら向こう側で受け付けられたかまで確かめると、実際の成果を判断できます。

5.テスト・集計・SNS投稿へ広げるときの考え方

README.mdの確認ができたら、次は普段手で動かしているコマンドを一つ選びます。たとえば、Pythonのテストなら、ランナーに必要なPythonとライブラリを用意し、すでに手元で動くテストコマンドをrunから呼び出します。

一方、SNS投稿やデータ更新は、再実行すると同じ操作が二重に行われる場合があります。最初は外部に送信せず、何を処理する予定かを表示する段階まで作りましょう。実際の送信へ進むなら、処理済みの記録を残し、再実行前に結果を確かめられるようにします。

APIキーなどが必要な場合は、YAMLやプログラムに直接書かず、GitHubのSecretsから必要なステップに渡します。ログに値を表示しないこと、使うアクションと権限を確認することも大切です。

💡 あわせて読みたい関連記事

手動で動かせたら、次はSNS投稿への応用です。実際の投稿前に試す方法や、投稿済みの記録を使った重複対策を紹介しています。

GitHub ActionsでSNS自動投稿する方法|定期実行・Secrets・重複投稿対策 記事を読む →

6.まずは「手動で1回実行して、ログを読む」

最初に作るワークフローは、README.mdの確認のような小さな処理で十分です。成功と失敗の両方を試し、どのステップが何をしたかをログで確かめると、YAMLの設定と実際の動きが結びつきます。

そこまでできたら、いつも繰り返している作業を一つ選び、「いつ実行するか」「何を成功とするか」「失敗したらどう気づくか」を決めてみてください。定期実行や外部連携を加えるときも、この3点が自動化を見直す手がかりになります。

参考資料

Learning Tools

記事を検索したい方はここから!

辞書から探す

本文中で気になった概念やキーワードを、辞書ページで一覧から確認できます。

辞書を見る