actions/github-scriptの型補完でJob Summariesの開発をラクにしよう

Job Summariesの自前実装が辛い

GitHub Actionsのワークフローで自前のJob Summariesを実装する際に、簡単なサマリーであればワークフローのyamlにインラインでスクリプトを記述すればいいのですが、複雑になってくると実装が辛い。。。

- name: Generate list using Markdown
  run: |
    echo "This is the lead in sentence for the list" >> $GITHUB_STEP_SUMMARY
    echo "" >> $GITHUB_STEP_SUMMARY # this is a blank line
    echo "- Lets add a bullet point" >> $GITHUB_STEP_SUMMARY
    echo "- Lets add a second bullet point" >> $GITHUB_STEP_SUMMARY
    echo "- How about a third one?" >> $GITHUB_STEP_SUMMARY

actions/github-scriptを使う

actions/github-scriptを使ってJavaScriptをyaml内に記述する方法もshellよりはいいですが、ちょっとしんどいです。

- name: Generate list using Markdown
  uses: actions/github-script@v7
    with:
      script: |
        await core.summary
          .addHeading("This is the lead in sentence for the list")
          .addList([
            "Lets add a bullet point",
            "Lets add a second bullet point",
            "How about a third one?",
        ])
        .write()

スクリプトをjsファイルに切り出す

何かいい方法はないかと調べていたらactions/github-script公式リポジトリのREADMEにスクリプトをjsファイルに切り出して、ワークフローのyamlで読み込む方法が記載されていました。

https://github.com/actions/github-script?tab=readme-ov-file#run-a-separate-file-with-an-async-function

.github/scripts/my-script.js

module.exports = async ({ github, context, core }) => {
  await core.summary
    .addHeading("This is the lead in sentence for the list")
    .addList([
      "Lets add a bullet point",
      "Lets add a second bullet point",
      "How about a third one?",
    ])
    .write()
}

.github/workflows/test.yaml

on: push

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/github-script@v7
        with:
          script: |
            const script = require('./.github/scripts/my-script.js')
            await script({ github, context, core })

ワークフローで同リポジトリ内のjsファイルを読み込むため、スクリプト実行前にactions/checkout でリポジトリのクローンをお忘れなく。

JSDocを使って型補完

jsファイルにJob Summariesを作成するスクリプトを切り出すことができれば、JSDocを使って型の補完が可能です。

https://zenn.dev/azukiazusa/articles/c89d4bdc7dacf2#インポート型

とりあえずnpmで@actions/core と @actions/github をインストールします。

$ npm install --save-dev @actions/core @actions/github

そして以下のようにJSDocを記載すればVSCode上で補完が効きます 🎉

/**
 * @typedef {import("@actions/github").context } Context
 * @typedef {import("@actions/core")} Core
 * @typedef {ReturnType<import("@actions/github")["getOctokit"]>} GitHub
 */

/**
 * @param {Object} options - The options object.
 * @param {GitHub} options.github - The GitHub object.
 * @param {Context} options.context - The context object.
 * @param {Core} options.core - The core object.
 */
module.exports = async ({ github, context, core }) => {
  await core.summary
    .addHeading("This is the lead in sentence for the list")
    .addList([
      "Lets add a bullet point",
      "Lets add a second bullet point",
      "How about a third one?",
    ])
    .write()
}