[入門]GitHub Actions ~全てのエンジニアのための備忘録~

こんにちは。KOUKIです。

とある企業でWebエンジニアをしています。

どこの企業でもVersion Control Systemを使っていると思いますが、その代表的なツールとしてGitHubを知らないエンジニアはいない(と信じたい)と思っています。

本記事では、GitHub Actionsの使い方を備忘として残しておきたいと思います。

GitHub Actionsとは?

GitHub Actionsは、ソフトウェア開発におけるワークフローを自動化するためのツールです。

ワークフローとは、開発者がGitHubのリポジトリ内で、「ビルド/テスト/パッケージング/リリース/デプロイ」など様々な処理を自動で実行するための枠組みのことを指します。

開発者側では、2つの概念を組み合わせてワークフローを作成します。

  • タスク(実行したい内容)
  • アクション(どのように起動するか)

このアクションが実行されると、GitHub Server内でVirtual Machine Instance(Runner)が立ち上がります(ここからはGitHub側のお仕事です)。

そこで、タスクに定義した内容がJobとして実行されます。

Virtual Machine InstanceはLinuxはもちろん、Windows, Macも選択できるので幅広いOSでの検証にも利用できます。もちろんDocker Containerも利用可能です。

流れをまとめると以下のようになります。

  1. Event(PushやMergeなど)が発生
  2. Workflowが実行
  3. Virtual Environment立ち上げ(Runner)
  4. Job実行
  5. タスクに設定されたStepごとにActionが実行

細かいことはハンズオンを通して、お伝えできればなと思います。

ワークフローの作成

ワークフローを作成しましょう。

GitHub リポジトリの作成

GitHubのリポジトリを作成します。

作成したリポジトリをローカルに取り込んでしておきましょう。

フォルダの作成

GitHub Actionsでワークフローを作成するためには、.github/workflowsフォルダ内にyamlを設置する必要がある。

尚、yaml形式でGitHub Actionsを実装していきます。

コメントにパラメータの詳細を記載してますが、より深く知りたい人はここを参考にしてください。

Git Push

先ほどのコードでは、Git Pushを実行するとワークフローを起動するように設定しました。

実際に確認してみましょう。

GitHubのリポジトリを確認してみましょう。

Pushされたことが確認できました。

次に、「Actions」タブに移動します。

simple.ymlファイルに実装したrun-shell-commandジョブが登録されていることがわかります。

ステップの詳細も確認できます。

OKですね。

エラーになった時の挙動

誤ったコマンドなどを指定して、エラーになった時の挙動を確認してみましょう。

「eecho」という存在しないコマンドを指定しました。GitHubにPushしてみましょう。

さて、GitHub Actionsの方はどうなっているでしょうか。

エラーで止まってますね!

デバッグログの出力

GitHubの設定で、デバッグログを出力できます。

その為には、ACTIONS_RUNNER_DEBUGをGitHubに設定します。

まずは、Settings -> Secretsから「New repository secret」ボタンを押下しましょう。

遷移先に、Secret情報を入力するフォームが現れるので、下記の値を入力して、「Add secret」ボタンを押下します。

処理が問題なく完了すれば、ACTIONS_RUNNER_DEBUGは、Secret情報として登録されます。

同じ手順で、「ACTIONS_STEP_DEBUG : true」も登録しておきましょう。

ここまでの作業が完了したら、先ほどエラーになっていたワークフローを再実行します。

今度は、「debug」が出力されたことがわかりますね^^

様々なshell

デフォルトでは、スクリプトはBash上で動きます。
(ただしWindowsを除く)

jobs.<job_id>.steps[*].shellを見るとたくさんのshellを選択できることがわかります。

Supported platformshell parameterDescriptionCommand run internally
AllbashThe default shell on non-Windows platforms with a fallback to sh. When specifying a bash shell on Windows, the bash shell included with Git for Windows is used.bash --noprofile --norc -eo pipefail {0}
AllpwshThe PowerShell Core. GitHub appends the extension .ps1 to your script name.pwsh -command ". '{0}'"
AllpythonExecutes the python command.python {0}
Linux / macOSshThe fallback behavior for non-Windows platforms if no shell is provided and bash is not found in the path.sh -e {0}
WindowscmdGitHub appends the extension .cmd to your script name and substitutes for {0}.%ComSpec% /D /E:ON /V:OFF /S /C "CALL "{0}"".
WindowspwshThis is the default shell used on Windows. The PowerShell Core. GitHub appends the extension .ps1 to your script name. If your self-hosted Windows runner does not have PowerShell Core installed, then PowerShell Desktop is used instead.pwsh -command ". '{0}'".
WindowspowershellThe PowerShell Desktop. GitHub appends the extension .ps1 to your script name.powershell -command ". '{0}'".

例えば、pythonを指定する場合は、以下のようにします。

stepsの2番目の「python Command」に注目してほしいです。ここでPythonのコマンドを実行しています。

shellとして、「python」を選択していることもわかると思います。

GitHubにPushします。

GitHubページに飛ぶとPythonコードの実行結果が確認できます。

もう一個、Windowsも試してみましょうか。

新しく「run-windows-commands」を作成し、そこにスクリプトを実行しました。

runs-onに「windows-latest」を指定しているので、WindowsのPoserShellが動くはずです。それを確認するために「Get-Location」コマンドを使っています。

GitHubにPushをしましょう。

ご覧の通り、Jobが二つに増えました。これらのJobはパラレルで動きます。

コマンドも問題なく実行されています。

OKですね。

Jobの依存関係

ちなみに、「run-shell-commmand」Jobの後に「run-windows-commands」を実行したい場合は、needsオプションを付与します。

GitHubにPushします。

GitHubを確認すると以下のようになってました。

run-shell-command -> run-windows-commandsの順にJobが実行されています。

3rd-party Actionを利用する

これまでは、Shellコマンドなどで実行したいスクリプトを直接コードに書いてましたが、他の人が開発したActionを利用することができます。

例えば、hello -world-javascript-actionを利用してみましょう。

このアクションは挨拶を返すだけの単純なものですが、デモが簡単に行えます。

ひとまず。Action用のファイルを用意しましょう。

このファイルにGitHub Actionsを記載します。

説明はコメントに書いてあるので割愛させていただくとして、GitHubにPushしましょう。

GItHubページを見てみましょう。

OKですね。ちなみに、「Log Greeting Time」はこんな感じになってます。

GitリポジトリをCheckoutする

GitHubの「actions/checkout」にて、GitHubリポジトリのCheckoutができます。

これで自分のリポジトリがCheckoutされるはずなので、実際にPushして確認してみましょう。

GitHub Actions画面を開きます。

「List Files」と「List Files After Checkout」を比較してみましょう。

gitやtest.yamlが存在しているので、Checkoutが確認できましたね。

また、GitHub Actionsには環境変数が用意されているのでこれらを使うともっといい感じにできます。

GITHUB_SHAなどが環境変数です。下記は、公式サイトからの引用です。

Environment variableDescription
CIAlways set to true.
GITHUB_WORKFLOWThe name of the workflow.
GITHUB_RUN_IDリポジトリ内でユニークな各実行に対する番号。 この番号は、ワークフローの実行をやり直しても変化しません、
GITHUB_RUN_NUMBERリポジトリ内の特定のワークフローの各実行に対するユニークな番号。 この番号は、ワークフローの最初の実行時に1で始まり、新たな実行ごとにインクリメントされます。 この番号は、ワークフローの実行をやり直しても変化しません、
GITHUB_JOBThe job_id of the current job.
GITHUB_ACTIONThe unique identifier (id) of the action.
GITHUB_ACTION_PATHThe path where your action is located. You can use this path to access files located in the same repository as your action. This variable is only supported in composite actions.
GITHUB_ACTIONSAlways set to true when GitHub Actions is running the workflow. You can use this variable to differentiate when tests are being run locally or by GitHub Actions.
GITHUB_ACTORThe name of the person or app that initiated the workflow. For example, octocat.
GITHUB_REPOSITORYThe owner and repository name. For example, octocat/Hello-World.
GITHUB_EVENT_NAMEThe name of the webhook event that triggered the workflow.
GITHUB_EVENT_PATHThe path of the file with the complete webhook event payload. For example, /github/workflow/event.json.
GITHUB_WORKSPACEThe GitHub workspace directory path, initially empty. For example, /home/runner/work/my-repo-name/my-repo-name. The actions/checkout action will check out files, by default a copy of your repository, within this directory.
GITHUB_SHAThe commit SHA that triggered the workflow. For example, ffac537e6cbbf934b08745a378932722df287a53.
GITHUB_REFThe branch or tag ref that triggered the workflow. For example, refs/heads/feature-branch-1. If neither a branch or tag is available for the event type, the variable will not exist.
GITHUB_REF_NAMEThe branch or tag name that triggered the workflow run.
GITHUB_REF_PROTECTEDtrue if branch protections are configured for the ref that triggered the workflow run.
GITHUB_REF_TYPEThe type of ref that triggered the workflow run. Valid values are branch or tag.
GITHUB_HEAD_REFOnly set for pull request events. The name of the head branch.
GITHUB_BASE_REFOnly set for pull request events. The name of the base branch.
GITHUB_SERVER_URLReturns the URL of the GitHub server. For example: https://github.com.
GITHUB_API_URLReturns the API URL. For example: https://api.github.com.
GITHUB_GRAPHQL_URLReturns the GraphQL API URL. For example: https://api.github.com/graphql.
RUNNER_NAMEThe name of the runner executing the job.
RUNNER_OSジョブを実行しているランナーのオペレーティングシステム。 取り得る値はLinuxWindowsmacOSのいずれか。
RUNNER_ARCHThe architecture of the runner executing the job. Possible values are X86X64ARM, and ARM64.
RUNNER_TEMPランナー上の一時ディレクトリへのパス。 このディレクトリは、各ジョブの開始及び終了時点で空になります。 ランナーのユーザアカウントが削除する権限を持っていない場合、ファイルは削除されないことに注意してください。
RUNNER_TOOL_CACHEGitHubホストランナーにプレインストールされているツールを含むディレクトリへのパス。 詳しい情報については、「GitHub ホストランナーの仕様」を参照してください。

GitHubにPushしてみましょう。

GitHub Actionsを確認してみましょう。

なんかエラーになってますね。

git cloneの箇所でエラーになってますね。

Check Outを使わないとできないのかな。

下記をコメントアウトして、もう一度Pushしましょう。

GitHub Actionsを確認してみましょう。

今度は、OKですね。

環境変数も確認できますね。

次回

GitHub Actionsをマスターすればもう怖いものなしですね。

次回(があれば)は、よりアドバンスな内容をお届けしたいと思うので、ご期待くださいませ。

それでは、また!

プログラミング記事

コメントを残す