GitHub Actionsで簡単なワークフローを作ろう

このハンズオンでは、GitHub Actionsで簡単なワークフローを作成する方法について実際にハンズオン形式で手を動かしながら体験します。

  • GitとGitHubの事前準備
  • リポジトリの作成とクローン
  • ワークフローファイル（.github/workflows）の作成
  • 手動トリガー（workflow_dispatch）の設定
  • ワークフローの実行と結果確認

1. 事前準備

Gitの基礎知識を習得していることを前提とします。自信のない方は先に以下の講座を実施してください。

また、以下のツールやアカウントが必要です。まだ準備できていない場合は、リンク先の手順に沿って準備をお願いします。

2. ハンズオンの概要

GitHub Actionsの基本操作を理解するために、簡単なハンズオンを行います。

今回は、GitHub Actionsを使ってリポジトリに存在するファイルの一覧を表示するワークフローを、手動で実行して結果を確認します。

3. リポジトリの作成

まずは、GitHubのリポジトリを作成します。リポジトリとは、GitHub上でソースコードや設定ファイルなどをまとめて管理する単位のことです。GitHub Actionsは、基本的にこのリポジトリごとに動作します。

まず、GitHubにログインし、右上にあるプラスのボタンをクリックします。表示されたメニューの中から New repository を選びます。

すると、Create a new repository という画面が表示されます。ここで必要な情報を入力します。リポジトリ名は任意で構いませんが、今回は例として github-actions-test とします。

💡 ポイント
複数のOrganizationに所属している場合は、Ownerのドロップダウンからご自身の個人アカウントを選択してください。

続いて、公開範囲の設定を行います。Choose visibility の項目では、今回は Public を選びます。GitHubの無料プランでは、Private リポジトリでの GitHub Actions の実行時間に月単位の制限があるためです。

そのほかの項目はデフォルトのままで問題ありません。入力が終わったら、Create repository ボタンをクリックします。

これでリポジトリの作成が完了です。作成完了の画面が表示されれば、ここまでの手順は成功です。

4. ワークフローの作成

4.1 GitHubのコードをclone

GitHubで作成した github-actions-test のリポジトリをローカル環境にcloneします。ここからはGitコマンドを使って進めます。

まず、Windowsの場合はコマンドプロンプトを、Macの場合はターミナルを開きます。

次に、以下のコマンドを実行してGitHubのリポジトリをダウンロードします。フォルダの場所を指定したい場合は、事前に cd コマンドで移動してから実行してください。また、＜your-github-account-name＞ の部分はご自身のGitHubアカウント名に置き換えます。

git clone https://github.com/＜your-github-account-name＞/github-actions-test.git

コマンドが成功すると、以下のように正常終了のメッセージが表示されます。

なお、You appear to have cloned an empty repository. という警告が出る場合がありますが、これは「リポジトリにまだ何も入っていない」という意味です。今回はまだファイルを作成していないため、想定どおりの状態です。

Cloning into 'github-actions-test'...
warning: You appear to have cloned an empty repository.

4.2 ワークフローのファイルを作成

ここからはVisual Studio Codeを使って、ワークフローのファイルを作成します。

Visual Studio Codeを起動すると、最初に[ようこそ]の画面が表示されます。左上にあるファイルのアイコンをクリックし、フォルダを開くを選びます。フォルダの選択画面が表示されるので、先ほどgit cloneしたgithub-actions-testのフォルダを選択します。

github-actions-testのフォルダが開きました。

ここに、GitHub Actionsのワークフローを記述するためのgithub-actions-test.ymlファイルを作成します。GitHub Actionsでは、.github/workflowsフォルダの中に配置したymlファイルがワークフローとして認識されます。

左側のエクスプローラでファイルのアイコンをクリックします。

ファイル名として .github/workflows/github-actions-test.yml と入力します。これにより、.githubフォルダとworkflowsフォルダ、そしてgithub-actions-test.ymlファイルが順に作成されます。

github-actions-test
└── .github
    └── workflows
        └── github-actions-test.yml  ← このファイルを作成

github-actions-test.ymlファイルが作成されました。

なお、Visual Studio Codeの設定によっては、ファイル名が赤く表示されることがあります。これは、YAMLファイルの中身がまだ空であることを示す警告です。ファイルを作成した直後に表示されるものなので、問題ありません。

4.3 コードの記載

作成したファイルに以下の内容を記述して保存します。

name: Test Workflow

on:
  workflow_dispatch:

jobs:
  hello:
    runs-on: ubuntu-latest

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

      - name: list files
        run: ls -la

コードを解説します。

name: Test Workflow

nameは、ワークフロー全体の名前を定義しています。ここでは「Test Workflow」という名前が付けられており、GitHub上でもこの名前で実行結果を確認できます。

on:
  workflow_dispatch:

onは、ワークフローをどのタイミングで実行するかを指定する部分です。ここではworkflow_dispatchと定義しており、これは「手動実行」を意味しています。

jobs:
  hello:
    runs-on: ubuntu-latest

jobsは、ワークフロー内で実行されるジョブを定義するブロックです。ここではhelloという名前のジョブを定義しています。runs-onはランナーを表し、ジョブをどの環境で実行するかを指定します。ここではubuntu-latestとなっており、GitHubが用意している最新のUbuntu環境で実行されます。

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

stepsは、ジョブの中で実行される処理の手順を定義します。1つ目のステップでは、actions/checkout@v5というアクションを使用して、現在のブランチのコードをUbuntuの実行環境にダウンロードします。なお、手動実行の場合は、実行時にどのブランチを対象にするかを選択することができます。

      - name: list files
        run: ls -la

2つ目のステップでは、runでLinuxコマンドのls -laを実行し、カレントディレクトリのファイルを一覧表示します。今回のワークフローではランナーとしてUbuntuを指定しているため、Linuxコマンドを使用できます。

このように、このワークフローはGitHub上から手動で実行すると、Ubuntu環境上で指定ブランチのコードを取得し、そのファイル一覧を出力するだけの、非常にシンプルな処理を行います。

4.4 テスト用のファイルを記載

続いて、GitHub Actionsの本題とは直接関係ありませんが、テストとしてリポジトリ内のファイル一覧を確認するために、一つファイルを作成しておきましょう。

Visual Studio Codeを使い、README.mdという名前のファイルを作成します。このとき、.github/workflowsフォルダの中ではなく、リポジトリのトップ階層に作成してください。

github-actions-test
├── .github
│   └── workflows
│       └── github-actions-test.yml
└── README.md  ← このファイルを作成

4.5 Gitへの反映

ここまで作成したワークフローのファイルを、GitHubに反映します。 ここからは、Visual Studio Codeのターミナルを使って操作を進めます。

まず、Visual Studio Codeの上部メニューからターミナルを開き、新しいターミナルをクリックします。

画面の下にターミナルが表示されます。ここでGitのコマンドを入力します。

はじめに、git add . と入力して、変更したファイルをインデックスに追加します。

git add .

このコマンドを実行しても、特に表示はありませんが問題ありません。

次に、git commitコマンドで変更内容をコミットします。

git commit -m "github actions test"

このように実行すると、2 files changed といった結果が表示されます。

2 files changed, 12 insertions(+)
create mode 100644 .github/workflows/github-actions-test.yml
create mode 100644 README.md

続いて、git pushコマンドでGitHubに反映させます。

git push origin main

正常に完了すると、送信結果のログが表示されます。

Enumerating objects: 7, done.
Counting objects: 100% (7/7), done.
Delta compression using up to 8 threads
Compressing objects: 100% (4/4), done.
Writing objects: 100% (7/7), 620 bytes | 620.00 KiB/s, done.
Total 7 (delta 0), reused 0 (delta 0), pack-reused 0 (from 0)
To https://github.com/＜your-github-account-name＞/github-actions-test.git

[new branch] main -> main
⚠️ 「Authentication failed」エラーが出る場合
GitHubへの認証に失敗しています。HTTPSでcloneした場合、Personal Access Token（PAT）が必要です。
GitHubの「Settings」→「Developer settings」→「Personal access tokens」からトークンを作成し、パスワードの代わりに使用してください。
⚠️ 「failed to push some refs」エラーが出る場合
リモートリポジトリに変更があり、ローカルと同期がとれていません。
git pull origin mainを実行してから、再度git pushを試してください。

最後に、GitHubの画面を開いてみましょう。github-actions-testリポジトリを開くと、今コミットしたファイルが反映されていることが確認できます。

5. GitHub Actionsの動作確認

5.1 GitHub Actionsの実行

ここからは、実際に作成したGitHub Actionsのワークフローを実行します。

まず、GitHubでgithub-actions-testリポジトリを開きます。

画面上部のActionsタブをクリックすると、左側のメニューにAll Workflowsという項目があり、その中にTest Workflowが表示されているはずです。

⚠️ ワークフローが認識されない場合
Test Workflowが表示されない場合は、フォルダ名を確認してください。フォルダ名は必ず.github/workflowsとしてください。github（ドットなし）やworkflow（単数形）にするとGitHub Actionsが認識しません。

Test Workflowをクリックすると、詳細画面が開きます。ここで、手動でワークフローを実行してみましょう。

右上にあるRun workflowボタンをクリックし、さらにもう一度Run workflowをクリックします。

ブランチを選択する項目もありますが、今回は特に変更せず、そのまま実行して問題ありません。

実行すると、履歴の部分に、Test Workflowが表示され、黄色いマークが付くと思います。これは、実行中であることを示しています。

少し待つと、マークが緑色に変わります。これで正常に完了したことを示しています。

⚠️ 「Node.js XX actions are deprecated」の警告が表示される場合
ワークフローの実行結果に「Node.js XX actions are deprecated」という警告が表示されることがあります。これは、使用しているアクションが内部で古いバージョンのNode.jsを使用していることを示す警告です。ワークフローの動作自体には影響しないため、このまま進めて問題ありません。アクションのバージョンを最新に上げることで解消できます。
⚠️ ワークフローが失敗する場合
失敗したワークフローをクリックし、詳細ログを確認してください。よくある原因として、
(1) YAMLファイルのインデントが正しくない（スペースの数が揃っていない）
(2) ワークフローファイルの保存場所が.github/workflows/でない
(3) YAMLの構文エラー（コロンの後にスペースがないなど）
があります。

履歴の一覧からTest Workflowをクリックすると、実行したジョブの一覧が表示されます。今回はhelloというジョブだけなので、このジョブをクリックします。

ジョブの詳細が開いたら、いくつかのステップの中に、Checkout repositoryとList filesの2つのステップが作成されていることが読み取れます。

Checkout repositoryを展開すると、actions/checkoutが実行された結果が表示されます。ここでは詳細なログの説明は省略しますが、問題なくコードの取得が完了していることが確認できます。

List filesを展開すると、ls -laコマンドの実行結果が表示されます。この中に、先ほど作成したREADME.mdが表示されていれば、正常に実行されています。なお、.gitというディレクトリが含まれていますが、これはGitによるバージョン管理のために自動的に作成される隠しフォルダであり、特に問題はありません。

💡 ポイント
この中には、自分で定義していないステップ（Set up job、Post Checkout repository、Complete job）がいくつか含まれています。これらはGitHub Actionsがジョブの実行環境の準備や後処理のために自動的に追加している処理です。特に意識する必要はありません。

ワークフローが正常に実行され、List filesのステップでREADME.mdが表示されていれば、ここまでの操作は完了です。

6. まとめ

このハンズオンでは、GitHub Actionsで簡単なワークフローを作成する方法を体験しました。

  • GitHub ActionsはGitHubが提供するCI/CDサービスで、リポジトリ内の.github/workflowsフォルダにYAMLファイルを配置することで動作する
  • workflow_dispatchトリガーを使用すると、ワークフローを手動で実行できる
  • actions/checkoutアクションでリポジトリのコードをランナー環境に取得できる
  • runs-onでランナー環境を指定し、stepsで実行する処理を定義する
  • ワークフローの実行結果はGitHubのActionsタブで確認できる

7. 次のステップ

🎉 おめでとうございます！GitHub Actionsで初めてのワークフローを作成し、実行するところまで体験できました。

ここまでで学んだ内容は、GitHub Actionsを扱ううえでの基本中の基本です。ここから先は、より実践的な内容に進みます。

講座名 学べること
GitHub Actionsの応用設定 環境変数・シークレット・条件分岐・OIDC・保護ブランチなどの応用設定
静的解析と自動テストを自動化しよう Pull Requestをトリガーにflake8とpytestを自動実行するCIの構築
コンテナのビルドとデプロイを自動化しよう GitHub ActionsからECS/Fargateへのコンテナイメージのビルド・デプロイ自動化
デプロイタイプ ローリング・ブルーグリーン・カナリアなどのデプロイ戦略

実務で通用するCI/CDスキルを身につけたい方は、ぜひ次のステップに進んでみてください。