カスタム GitHub アクションを公開する

  • 6 分

ここでは、アクションに適した公開方法の選択、アクションをドキュメント化およびバージョン管理するためのベストプラクティス、アクションを GitHub Marketplace に公開する方法などについて説明します。

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

アクションの 2 つの表示オプション (パブリックまたはプライベート) を表示する図。

アクションを作成する際には、最初にそのアクションをライブにする場所と、そのアクションの公開方法 (public または private) を決定することが重要です。 アクションの公開方法によって、推奨事項とそのアクションをリリースするために必要な要件が決まります。 これら 2 つの公開オプションについて詳しく見ていきましょう。

パブリック

任意のリポジトリ内のワークフローでパブリック アクションを使用できます。 オープンソースにすること、または GitHub Marketplace を通じて公開することを目的としてアクションを開発している場合、他のアプリケーション コードとバンドルするのではなく、アクションに独自のリポジトリを設定することをお勧めします (要件の場合がほとんどです)。 こうすることで、他のソフトウェアと同じように、アクションのバージョン管理、追跡、リリースなどを行うことができます。 これで、GitHub コミュニティでアクションが簡単に見つかるようになります。また、開発者が問題の修正やアクションの拡張を行う際に、コード ベースの範囲を絞り込んだり、アクションのバージョン管理を他のアプリケーション コードのバージョン管理から切り離したりすることができます。

プライベート

アクションがプライベート リポジトリ内にある場合、そのアクションは同じリポジトリ内のワークフローでのみ使用できます。 プライベート アクションでは、リポジトリ内の任意の場所にアクションのファイルを格納できます。 アクション、ワークフロー、アプリケーション コードを 1 つのリポジトリにまとめる予定の場合は、アクションを .github ディレクトリに格納することをお勧めします。 たとえば、.github/actions/action-a と.github/actions/action-b です。

アクションをドキュメント化する

ドキュメントがあいまいな場合、または存在しない場合、新しいツールやアプリケーションを使用するのは困難です。 アクションをパブリックにするかプライベートにするかに関係なく、他のユーザーがその動作を確認できるように、アクションには適切なドキュメントを含めることが重要です。 最初に、アクションに適した README.md ファイルを作成します。

多くの場合、開発者は最初にこの README.md ファイルを見て、アクションの動作を確認します。 これは、アクションに関する重要な情報をすべて含めるのに最適な場所です。 以下に、含める項目の一部を示します。

  • アクションの動作に関する詳細な説明。
  • 必須の入力および出力の引数。
  • 省略可能な入力および出力の引数。
  • アクションで使用されるシークレット。
  • アクションで使用される環境変数。
  • ワークフローでのアクションの使用方法の例。

一般的な規則として、この README.md ファイルには、ユーザーがアクションを使用するうえで必要な情報がすべて含まれている必要があります。 役に立つと考えられる情報は README.md に含めます。

アクションをリリースしてバージョン管理する

他のユーザーが使用するアクションを開発している場合は、それがパブリックであるかプライベートであるかに関係なく、更新プログラムの配布方法を制御するリリース管理戦略を定義する必要があります。 互換性に影響を与える必須の重要修正プログラムやセキュリティ パッチを含むメジャー バージョンの更新プログラムは、明確に文書化する必要があります。

リリースおよびバージョン管理のベスト プラクティス

適切なリリース管理戦略には、バージョン管理の推奨事項が含まれているものです。 ユーザーは、アクションを使用してアクションの既定のブランチを参照しないでください。 これは、最新のコードを含む可能性が高い既定のブランチ (安定している場合もあれば、安定していない場合もあります) によって、ワークフローが中断される可能性があるためです。 代わりに、アクションの使用時にはユーザーがメジャー バージョンを指定するようにし、問題が発生した場合にのみ、より具体的なバージョンを案内することをお勧めします。 これは、タグ、コミットの SHA、またはリリースに指定されている特定のブランチを対象とするように GitHub Actions ワークフローを構成することで行うことができます。 これらのリリース オプションについて詳しく見ていきましょう。

タグ

タグは、アクションのリリースを管理するための優れた方法です。 タグを使用すると、ユーザーはメジャー バージョンとマイナー バージョンを簡単に区別できます。 リリースを作成する際に考慮すべき便利な方法のリストを以下に示します。

  • リリース タグ (release/v1 など) を作成する前に、リリース ブランチ (v1.0.2 など) でリリースを作成して検証する。
  • セマンティック バージョニングを使用する。
  • メジャー バージョン タグ (v1、v2 など) を移動して、現在のリリースの Git 参照をポイントする。
  • 既存のワークフローを中断させる変更に対して、新しいメジャー バージョン タグ (v2) を導入する。
  • ベータ版タグ (v2-beta など) でメジャー バージョンをリリースし、その状態を示す。 リリースの準備ができたら、-beta タグを削除できます。

次に、各オプションの例をいくつか示します。

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

コミットの SHA を使用する

タグは便利で広く使用されていますが、タグには削除または移動の可能性があるという欠点があります。 Git では、各コミットは計算された SHA 値を受け取ります。これは一意であり、変更することはできません。 バージョン管理にコミットの SHA を使用すると、最も信頼性の高い安全な方法でバージョンを管理でき、アクションを使用することができます。 ただし、多くの場合、Git では SHA ハッシュを最初の数文字に省略でき、Git では参照が認識されます。 リリース管理にコミットの SHA を使用している場合は、省略された値ではなく、完全な SHA 値を使用する必要があります。

steps:
    - uses: actions/javascript-action@2522385f6f7ba04fe7327647b213799853a8f55c

GitHub Marketplace にアクションを公開する

GitHub Marketplace を示すレンダリング。ワークフローを構築して改善するためのツールです。

アクションを GitHub コミュニティと共有する準備ができたら、それを GitHub Marketplace に公開し、何百万人もの GitHub ユーザーに知らせることができます。 すべての要件が満たされている場合、GitHub Marketplace に公開したアクションは直ちに公開されます。 要件を満たしていない場合、アクションを公開するには GitHub による確認が必要です。 リポジトリには、アクションに必要なメタデータ ファイル、コード、およびファイルのみが含まれていることを確認する必要があります。 アクションのために 1 つのリポジトリを作成すれば、単一のユニットでコードのタグ付け、リリース、パッケージができます。 また、Github では、GitHub Marketplace ページでアクションのメタデータが使用されます。

次に、GitHub Marketplace にアクションを公開するための要件を示します。 これらは、Docker コンテナーベースのアクションと JavaScript ベースのアクションの両方に適用されます。

  • アクションはパブリック リポジトリ内に格納されている必要があります。
  • 各リポジトリには、1 つのアクションを含める必要があります。
  • アクションのメタデータ ファイル (action.yml または action.yaml) は、リポジトリのルート ディレクトリに存在する必要があります。
  • アクションのメタデータ ファイル内の name は、GitHub Marketplace において一意である必要があります。
    • GitHub では、ユーザーまたは組織の所有者がアクションを公開する場合を除き、名前をユーザーまたは組織と同じにすることはできません。 たとえば、github という名前のアクションを公開できるのは GitHub 組織だけです。
    • name を既存の GitHub Marketplace カテゴリと同じにすることはできません。
    • name を既存の GitHub 機能と同じにすることはできません。

作成したアクションを GitHub Marketplace に追加するには、新しいリリースとしてタグ付けしてから公開します。 GitHub には、アクションのリリースを公開できるようにするためのガイド付き手順がいくつかあります。 これらの手順の詳細については、このモジュールの最後にある「まとめ」セクションを参照してください。