A human and robot hand drawing each other

最初のカスタム GitHub アクションを構築

Bekah Whittle
Bekah Whittle // Director, Field Services // GitHub

このモジュールの最後で、カスタム GitHub Action を作成する理由と作成手順を説明します。

まず、action.yml と index.jsの設定の概要を説明します。それぞれ、基本的な「Hello World」アクションの構成ブループリントとアクション ロジックです。さらに、セマンティック バージョニングなど、GitHub Marketplace にアクションをリリースするためのベスト プラクティスも取り上げ、プロセス中に顧客の声に耳を傾けることの重要性についてのインサイトを Datadog で示します。これらを組み合わせることにより、シンプルなアプローチでGitHub プロジェクトのワークフローを自動化できます。

このガイドの学習内容

  • カスタム アクションを構築するタイミングを決定する

  • シンプルかつ効果的な actions.yml ファイルを作成し、入力と出力を含むアクションのメタデータを概説する

  • JavaScript コードの特定の部分を使用して入力をフェッチし、出力を設定して、アクションをランタイム ロジックに接続する

  • リリースの下書きとセマンティックバージョニングの採用により、GitHub Marketplace にアクションを公開するためのベストプラクティスを実行します。

カスタム アクションを構築するタイミングを決定する

カスタム アクションの開発に取り掛かる前に、GitHub Marketplace の既存のアクションを使用するか、カスタムアクションを構築するかを検討します。どちらを選ぶかによって、開発効率だけでなく、企業のガバナンスとセキュリティ態勢にも影響を及ぼします。

ガバナンス: アクションを制御する

組織が取るアクションに対して、どの程度の制御が必要であり望ましいとされるでしょうか? GitHub では、組織内のアクションの使用に特定のポリシーを設定できます。組織の設定の「アクション全般」セクションに移動すると、GitHub によって作成されたアクション、または審査プロセスを経て一般的に安全であると見なされている認証済みのクリエイターによるアクションのみの使用に制限できます。

Marketplace のアクション、特に認証済みのクリエイターによるアクションには、業界のトップクラスのセキュリティ専門家によって審査されるという重要なメリットがあります。ただし、コードに対するガバナンスと絶対的な制御が最優先事項である場合は、社内で開発されたカスタム アクションが最適な場合もあります。これらを組織のリポジトリ内の「Actions」フォルダーに保存すると、管理と監査が簡単になります。

使いやすさ vs. カスタマイゼーション

Marketplace のアクションは、一般的なタスク用の便利なプラグアンドプレイ ソリューションですが、必ずしも企業のニーズに完全に一致するとは限りません。一方、カスタム アクションでは、実行可能コードを特定の要件に合わせて柔軟にカスタマイズでき、セキュリティ上の懸念事項を考慮して開発および検証された後は、企業内のさまざまなプロジェクトで再利用できます。企業全体でにわたるアクションのインナーソーシングは、リスクを軽減しながらイノベーションを加速できる素晴らしい方法です。 

Marketplace のアクションが、目的には近いが、最適とまでは言えない場合は、これらのアクションをフォークまたはクローンしてから変更するという中間的なオプションもあります。これにより、カスタム アクションのカスタマイズ性に加えて、事前構築済みのアクションの利便性が実現します。

アクションの作成は 1 回で終わるわけではないことに注意する必要があります。他のソフトウェアと同じように、メンテナンスが必要です。 顧客がすでに使用しているプラットフォームやシステムに基づいて、作業の優先順位を付ける必要があります。Datadog では、カスタム GitHub アクションを学術的な練習として作成したわけではありません。当社の顧客は、既存の継続的インテグレーション パイプラインにシームレスに統合するツールを求めており、そのパイプラインの多くはすでに GitHub 上にありました。当社のアクションは顧客の実際のニーズに応えました。

Jake Pruitt
Jake Pruitt // Senior Engineer // Datadog

最終的にカスタム アクションを構築しないとしても、プロセスを理解しておくことが役立つため、まずは始めてみましょう。

action.yml ファイルを作成する

まずは、リポジトリに action.yml という名前のファイルを作成します。

1. 名前と説明を追加します。

最初に name と descriptionを指定します。これは、企業の内部アクションまたは Marketplace で閲覧したときに、あなたを含むユーザーに表示される内容です。

name: 'Hello World JS Action'
description: 'Greet someone and record the time'

2. 入力を宣言します。

アクションの入力を宣言します。これらは、ワークフローがアクションを使用するときにアクションに渡すことができるパラメーターになります。この例では、入力は次のようになります。who-to-greet.

inputs:
  who-to-greet:
    description: 'Who to greet'
    required: true
    default: 'World'

3. 出力を記述します。

アクションの出力内容を記述します。これは、同じジョブの後続のステップで使用できます。今回の簡単なアクションでは、挨拶の時間を出力します。

outputs:
  time:
    description: 'The time we greeted you'

4. 実行環境を定義します。

最後に、ランタイム環境を指定し、アクションのロジックを含む JavaScript ファイルを指定します。

runs:
  using: 'node16'
  main: 'index.js'

これで完了です。このアクションを実現するための JavaScript コードの準備が整いました。

ロジックを構築する

作成した action.yml ファイルの準備ができたら、次のコンポーネントはJavaScript ファイルです。この場合は index.jsです。ここでアクションの運用ロジックを埋め込みます。JavaScript コードをアクションにつなげるには、GitHub 独自のライブラリを使用します。具体的には、@actions/core と @actions/github.

const core = require('@actions/core');
const github = require('@actions/github');



try {
  // Fetch the value of the input 'who-to-greet' specified in action.yml
  const nameToGreet = core.getInput('who-to-greet');
  console.log(`Hello ${nameToGreet}!`);
  
  // Record the time of greeting as an output
  const time = (new Date()).toTimeString();
  core.setOutput("time", time);



} catch (error) {
  // Handle errors and indicate failure
  core.setFailed(error.message);
}

以下は、アクションに不可欠な部分を強調した、JavaScript コードの簡単な内訳です。

1.core.getInput('who-to-greet'): これは、action.ymlで入力として定義した値を取得し、アクション内でこのエンティティを受け入れます。

2.core.setOutput("time", time): 出力 (具体的には挨拶を作成した時刻) を設定します。これは後続のワークフロー ステップで使用できます。

3.try/catch ブロック: 例外を簡単に処理でき、必要に応じて core.setFailed(error.message) で失敗を通知できます。

以上です。お使いの index.jsにこれらの要素を組み込めばアクションが機能するようになり、Enterprise レベルの自動化の準備が整います。

アクションをリリースする

必要なファイルを GitHub リポジトリに追加したら、リポジトリのコード ページの上部に「この GitHub Actions を GitHub Marketplace に公開する」という新しいプロンプトが表示されます。これをクリックすると、GitHub Actions 向けにカスタマイズされた「新しいリリースの下書き」ページに移動します。

アクションを Marketplace にリリースするときは、次の点に注意してください。

  • セマンティック バージョニング: タグ バージョンにはセマンティック バージョニングを活用します。これはバージョン管理の簡素化に役立ち、アクションに強く推奨されます。

  • 説明とカテゴリー: アクションが何を実行するのかを明確に説明し、継続的インテグレーション、AI、チャットなど、アクションの有用性を最も適切に表すカテゴリーを選択します。

  • 公開: 詳細を確認したら、[リリースを公開] をクリックします。アクションが Marketplace で利用できるようになり、指定したセマンティック バージョンのタグが付けられます。

お疲れ様でした! MarMarketplace に参加できました。

次の内容: GitHub Actions でのオートメーション戦略上級モジュールのラップアップ

ここで、これまでに学んだことを復習し、GitHub Actions で他に何ができるかを見てみましょう。