アクションについて

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

• アクションについて
• アクションの種類
• アクションの場所を選択する
• アクションのバージョニング
• アクションのREADMEファイルを作成する
• GitHub Appsに対するGitHub Actionsの比較
• 参考リンク

アクションについて

GitHubの API やパブリックに利用可能なサードパーティAPIとのインテグレーションなど、好きな方法でリポジトリを操作するカスタムコードを書いて、アクションを作成することができます。 たとえば、アクションでnpmモジュールを公開する、緊急の問題が発生したときにSMSアラートを送信する、本番対応のコードをデプロイすることなどが可能です。

ワークフローで使用する独自のアクションを作成したり、ビルドしたアクションをGitHubコミュニティと共有したりできます。 ビルドしたアクションをシェアするには、リポジトリをパブリックにする必要があります。

アクションはマシン上で直接実行することも、Dockerコンテナで実行することもできます。 アクションの入力、出力、環境変数を定義できます。

アクションの種類

DockerコンテナのアクションとJavaScriptのアクションをビルドできます。 アクションには、アクションの入力、出力、およびメインのエントリポイントを定義するメタデータファイルが必要です。 このメタデータのファイル名はaction.ymlもしくはaction.yamlでなければなりません。

Dockerコンテナのアクション

Dockerコンテナは、GitHub Actionsコードで環境をパッケージ化します。 アクションの利用者がツールや依存関係を考慮しなくて済むため、作業単位の一貫性と信頼性が向上します。 Dockerコンテナのアクションは、GitHubにホストされたLinux環境でみ実行できます。

Dockerコンテナを使用すると、Osのバージョン、依存関係、ツール、コードを限定することができます。 特定の環境設定で実行しなければならないアクションの場合、オペレーティングシステムとツールを選択できるので、Dockerは理想的な選択肢です。 コンテナのビルドおよび取得のレイテンシにより、DockerコンテナのアクションはJavaScriptアクションより遅くなります。

アクションに関するメタデータを提供するには、GitHub Actions設定ファイルを含める必要があります。

JavaScriptのアクション

JavaScriptアクションはランナーマシン上で直接実行でき、アクションのコードはそのコードを実行するのに使われた環境から分離できます。 JavaScriptのアクションを使うと、アクションコードが単純になり、実行も Dockerコンテナのアクションより速くなります。

JavaScriptのアクションでは、アクションに関するメタデータを提供するためにGitHub Actions設定ファイルが必要です。

アクションの場所を選択する

他のユーザーが使うアクションを開発する場合には、他のアプリケーションコードにバンドルするのではなく、アクションをそれ自体のリポジトリに保持しておくことをお勧めします。 こうすると、他のソフトウェアと同様にアクションのバージョニング、追跡、リリースが可能になるからです。

アクションをそれ自体のリポジトリに保存すると、GitHubコミュニティがアクションを見つけやすくなります。また、開発者がアクションの問題を解決したり機能を拡張したりするとき、コードベースのスコープが限定され、アクションのバージョニングが他のアプリケーションコードのバージョニングから切り離されます。

ビルドしているアクションをパブリックに公開する予定がない場合、アクションのファイルはリポジトリのどの場所に保存してもかまいません。 アクション、ワークフロー、アプリケーションコードを 1 つのリポジトリで組み合わせる予定の場合、アクションは .github ディレクトリに保存することをお勧めします。 たとえば、.github/actions/action-aや.github/actions/action-bに保存します。

アクションのバージョニング

ワークフローは、コミットSHA、ブランチまたはタグを使用して特定バージョンのアクションを参照できます。

steps:    
  - uses: actions/setup-node@74bc508 # Reference a specific commit
  - uses: actions/setup-node@v1.0    # Reference the major version of a release   
  - uses: actions/setup-node@master  # Reference a branch

GitHubに安定した体験を提供するアクションを作成するときは、セマンティクスバージョニングを使用することをお勧めします。 詳細については、「セマンティクスバージョニング」を参照してください。

1. セマンティクスバージョニング (v1.0.9) を使用してリリースを作成します。 詳細については、「リリースの作成」を参照してください。
2. メジャーバージョンのタグ (v1、v2など) を、現在のリリースのGit refに移動します。 詳細については、「Gitの基本 - タグ」を参照してください。
3. 既存のワークフローを破壊する破壊的変更について、新しいメジャーバージョンのタグ (v2) を導入します。 たとえば、アクションの入力の変更は破壊的変更です。

アクションのREADMEファイルを作成する

アクションをパブリックに共有する予定がある場合には、アクションの使用方法を伝えるため README ファイルを作成することをお勧めします。 README.md には、以下の情報を含めることができます:

• アクションが実行する内容の説明
• 必須の入力引数と出力引数
• オプションの入力引数と出力引数
• アクションが使用するシークレット
• アクションが使用する環境変数
• ワークフローにおけるアクションの使用例

GitHub Appsに対するGitHub Actionsの比較

GitHub Marketplaceは、ワークフローを改善するツールを提供します。 それぞれのツールの違いや利点を理解すれば、自分の作業に最も適したツールを選択できるようになります。 アクションやアプリケーションの構築に関する詳しい情報についてはGitHub 開発者ドキュメンテーション内の「GitHub Actionsについて」及び「アプリケーションについて」を参照してください。

GitHub ActionsとGitHub Appsの強み

GitHub ActionsとGitHub Appはどちらもビルドの自動化の方法とワークフローツールを提供しますが、これらはそれぞれ異なる強みを持っており、違ったやり方で役立ちます。

GitHub Appsは：

• 永続的に動作し、イベントに素早く反応できます。
• 永続化されたデータが必要な場合にうまく動作します。
• 時間のかからないAPIリクエストとうまく働きます。
• ユーザが提供するサーバーあるいはコンピューティングインフラストラクチャ上で動作します。

GitHub Actionsは：

• 継続的インテグレーションや継続的デプロイメントを実行する自動化を提供します。
• ランナーマシン上でもDockerコンテナ内でも直接実行できます。
• リポジトリのクローンへのアクセスを含めて、コードにアクセスするツール、コードフォーマッタ、コマンドラインツールをデプロイしたり公開したりできます。
• コードのデプロイやアプリケーションの提供が必要ありません。
• シークレットの生成と利用のためのシンプルなインターフェースを持っており、アクションを利用する人の認証情報を保存せずにサードパーティのサービスとアクションを連携できます。

参考リンク

• GitHub Actionsでワークフローを自動化する
• "GitHub Actionsの開発ツール"
• "GitHub Actionsのメタデータ構文"