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

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

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

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

その他のプラットフォームとの互換性を維持する

多くのユーザーは、GitHub.com 以外のドメイン (GHE.com や、GitHub Enterprise Server のカスタム ドメインなど) で GitHub にアクセスします。

アクションが他のプラットフォームと確実に互換性があるようにするには、https://api.github.com などの API URL へのハードコーディングされた参照を使用しないでください。 代わりに、以下を行うことができます。

• 環境変数を使用する (「変数リファレンス」を参照してください):

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

• 適切な URL を自動的に設定できる @actions/github などのツールキットを使用する。

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

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

リリース管理の良い方法

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

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

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

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

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

• リリース タグ (v1.0.2 など) を作成する前に、リリース ブランチ (release/v1 など) でリリースを作成して検証する。
• セマンティックバージョニングを使用してリリースを作成します。 詳しくは、「リポジトリのリリースを管理する」をご覧ください。
• メジャー バージョン タグ (v1、v2 など) を移動して、現在のリリースの Git 参照をポイントする。 詳細については、「Git basics - tagging」(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@a824008085750b8e136effc585c3cd6082bd575f

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

アクションの使用方法を伝えるため、README ファイルを作成することをお勧めします。 README.md には、以下の情報を含めることができます。

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