Check! GitHub Actions: ちょっとしたスクリプトをかきたいときは GitHub Script が便利

Prologue

GitHub アクションをちょっとずつ試しています。今回は GitHub Script をご紹介します。

GitHub Actions で標準で用意されている Functions は最低限過ぎてできることが少ないので、ちょっとした文字列の加工なんかは JavaScript が使えると便利です。

そこで利用できるのが GitHub Script です。

GitHub Script

GitHub Script は、スクリプト処理として JavasScript を利用できます。

スクリプトの中では、下記が利用できます。

• github インスタンス: 認証済みの octokit/core.js クライアントで、REST API のエンドポイントの利用と、pagination プラグインを利用できる
• contextオブジェクト: github.event などを含むコンテキスト
• core: @actions/core パッケージへのリファレンス
• io: @actions/io パッケージのリファレンス

スクリプト内でデータを参照するには

スクリプト内にデータを渡すには、 context を使うか、環境変数を作成して渡します。 context では、 context.payload に github.event の情報が含まれているなど、大体の処理に必要なコンテキストが含まれています。下記のように表示すると、意図したコンテキストが含まれるか確認することができるでしょう。

- name: Return context
  uses: actions/github-script@v2
  id: return_context
  with:
    script: |
      return context

- name: Show steps.return_context
  env:
    RETURN_CONTEXT: ${{ toJson(steps.return_context.outputs) }}
  run: echo "$RETURN_CONTEXT"

@octokit/core.js を利用するには

@octokit/core.js を利用するには、 github インスタンスを用います。様々なAPIがあり、利用する際は アクションの README と、 octokit/rest.js のAPIを参照するとよさそうです。例えば、リポジトリの issues 一覧を取得する場合は List issues for a repository | octokit/rest.js を参考に、下記のように記述できます。

- name: Return issues
  uses: actions/github-script@v2
  id: return_github_issues
  with:
    script: |
      return github.issues.listForRepo({
        owner: context.repo.owner,
        repo: context.repo.repo
      })

文字列を返却したい

actions/github-script@v2 の戻り値は、JSONオブジェクトで返却されます。何もせずに文字列を返すと、不要な " (ダブルクオート) が付与されてしまい、後続の処理の邪魔になる場合があります。こういう時は、 result-encoding を利用しましょう。result-encoding: string と指定することで、文字列として返却することができます。

実際に見てみましょう。

- name: Return value as object
  uses: actions/github-script@v2
  id: return_value_as_object
  with:
    script: |
      return "This is string"

- name: Show steps.return_value_as_object
  env:
    RETURN_VALUE_AS_OBJECT: ${{ toJson(steps.return_value_as_object.outputs.result) }}
  run: echo "$RETURN_VALUE_AS_OBJECT"

結果はこのように、ダブルクオートがエスケープされた状態になっています。

"\"This is string\""

これでは扱いにくいので、string が返るように指定します。

- name: Return value as string
  uses: actions/github-script@v2
  id: return_value_as_string
  with:
    result-encoding: string
    script: |
      return "This is string"

- name: Show steps.return_value_as_string
  env:
    RETURN_VALUE_AS_STRING: ${{ toJson(steps.return_value_as_string.outputs.result) }}
  run: echo "$RETURN_VALUE_AS_STRING"

このように、意図した文字列として出力されました。

"This is string"

Epilogue

以上、触ってみてちょっと躓いたところを中心にいくつかサンプルを添えてみました。お役に立てれば幸いです。