About custom actions

About custom actions

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

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

アクションの種類

DockerコンテナのアクションとJavaScriptのアクションをビルドできます。 アクションには、アクションの入力、出力、およびメインのエントリポイントを定義するメタデータファイルが必要です。 このメタデータのファイル名はaction.ymlもしくはaction.yamlでなければなりません。 詳しい情報については、「GitHub Actions のメタデータ構文」を参照してください。

Docker コンテナアクション

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

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

Docker コンテナアクションは、Linux オペレーティングシステムのランナーでのみ実行できます。 セルフホストランナーでDockerコンテナアクションを実行するためには、Linuxオペレーティングシステムを使い、Dockerがインストールされていなければなりません。 セルフホストランナーに対する要求に関する詳しい情報については「セルフホストランナーについて」を参照してください。

JavaScriptアクション

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

JavaScriptのアクションがGitHubがホストするすべてのランナー（Ubuntu、Windows、macOS）と互換性があることを保証するためには、作成するパッケージ化されたJacScriptのコードは純粋なJavaScriptであり、他のバイナリに依存していてはなりません。 JavaScriptのアクションはランナー上で直接実行され、仮想環境内にすでに存在するバイナリを利用します。

Node.jsプロジェクトの開発では、GitHub Actions Toolkitで提供するパッケージを使って、開発の速度を上げることができます。 詳しい情報については、actions/toolkit リポジトリ以下を参照してください。

Composite Actions

A composite action allows you to combine multiple workflow steps within one action. For example, you can use this feature to bundle together multiple run commands into an action, and then have a workflow that executes the bundled commands as a single step using that action. To see an example, check out "Creating a composite action".

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

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

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

GitHub Enterprise Server との互換性

アクションが GitHub Enterprise Server と互換性があることを確認するには、GitHub API URL へのハードコードされた参照を使用しないようにする必要があります。 代わりに、環境変数を使用して GitHub APIを参照する必要があります。

• REST API の場合は、 GITHUB_API_URL 環境変数を使用します。
• GraphQL の場合は、 GITHUB_GRAPHQL_URL 環境変数を使用します。

詳しい情報については、「デフォルトの環境変数」を参照してください。

アクションにリリース管理を使用する

このセクションでは、リリース管理を使用してアクションへの更新を予測可能な方法で配布する方法について説明します。

リリース管理の良い方法

他のユーザが使用するアクションを開発している場合は、リリース管理を使用して、更新の配布方法を管理することをお勧めします。 既存のワークフローとの互換性を維持しつつ、アクションのメジャーバージョンに必要な重要な修正およびセキュリティパッチも含まれます。 変更が互換性に影響する場合は、新しいメジャーバージョンのリリースを検討する必要があります。

このリリース管理アプローチでは、アクションが最新のコードを含む可能性が高く、結果として不安定になる可能性があるため、ユーザはアクションのデフォルトブランチを参照しないでください。 代わりに、ユーザにアクションの使用時にメジャーバージョンを指定するように勧めて、問題が発生した場合にのみ、特定のバージョンを指定するようにすることができます。

特定のアクションのバージョンを使用するために、ユーザは GitHub Actions ワークフローを設定して、タグ、コミットの SHA、またはリリースの名前が付けられたブランチをターゲットにすることができます。

タグを使用したリリース管理

アクションのリリース管理にはタグを使用することをお勧めします。 この方法を使用すると、ユーザはメジャーバージョンとマイナーバージョンを簡単に区別できます。

• リリースタグ（v1.0.2 など）を作成する前に、リリースブランチ（release/v1 など）でリリースを作成して検証します。
• セマンティックバージョニングを使用してリリースを作成します。 詳細は「リリースを作成する」を参照してください。
• 現在のリリースの Git ref を指すようにメジャーバージョンタグ（v1、v2 など）を移動します。 詳細については、「Gitの基本 - タグ」を参照してください。
• 既存のワークフローを破壊する破壊的変更のための新しいメジャーバージョンタグ（v2）を導入します。 たとえば、アクションの入力の変更は破壊的変更です。
• メジャーバージョンは、最初のリリース時にそのステータスを示す beta タグ（v2-beta など）を付けることができます 。 その後、準備ができたら -beta タグを削除できます。

次の例は、ユーザがメジャーリリースタグを参照する方法を示しています。

steps:
    - uses: actions/javascript-action@v1

次の例は、ユーザが特定のパッチリリースタグを参照する方法を示しています。

steps:
    - uses: actions/javascript-action@v1.0.1

ブランチを使用したリリース管理

リリース管理にブランチ名を使用する場合、次の例では名前付きブランチを参照する方法を示しています。

steps:
    - uses: actions/javascript-action@v1-beta

コミットの SHA を使用したリリース管理

各 Git コミットは、計算された SHA 値を受け取ります。これは一意で不変のものです。 アクションのユーザは、コミットの SHA 値に依存することを好む場合があります。削除や移動ができるタグを指定するよりこの方法のほうが信頼できるためです。 ただし、これは、ユーザがアクションに対して行われた更新をそれ以上受け取らないことを意味しています。 コミットのSHA値として短縮値でなく完全な値を使うことで、同じ短縮値を使う悪意あるコミットを使ってしまうことを回避しやすくなります、

steps:
    - uses: actions/javascript-action@172239021f7ba04fe7327647b213799853a9eb89

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

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

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

GitHub Appsに対するGitHub Actionsの比較

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

GitHub ActionsとGitHub Appsの強み

While both GitHub Actions and GitHub Apps provide ways to build automation and workflow tools, they each have strengths that make them useful in different ways.

GitHub Appsは：

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

GitHub Actionsは：

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

参考リンク

• "GitHub Actionsの開発ツール"