Zenn
📦

GitHub Actions で kintone プラグインをパッケージング＆Releases にリリースする

2024/02/24に公開
GitHub Actions
kintone
tech

GitHub で管理する kintone プラグインを GitHub の Releases にリリースする方法を紹介します。
リリースには、GitHub Actions の workflow_dispach イベントを使います。

前提

リリース対象のプラグインのソースコードが GitHub リポジトリで管理されていることを前提とします。

この記事では、リリースするプラグインのサンプルとして、@kintone/create-plugin（以下、create-plugin）で作成したプラグインを使っています。
create-plugin によるプラグインの作成方法は、次のページを参考にしてください。
cybozu developer network - create-plugin

なお、create-plugin で作成したプラグインのディレクトリ構成は次のとおりです。

sample_plugin_project
├── node_modules # Git 管理の対象外
├── package-lock.json
├── package.json
├── private.ppk # Git 管理の対象外
├── scripts
│   └── npm-start.js
└── src
    ├── css
    │   ├── 51-modern-default.css
    │   ├── config.css
    │   ├── desktop.css
    │   └── mobile.css
    ├── html
    │   └── config.html
    ├── image
    │   └── icon.png
    ├── js
    │   ├── config.js
    │   ├── desktop.js
    │   └── mobile.js
    └── manifest.json

手順

STEP1：@kintone/plugin-packer のインストール

プラグインをパッケージングするために、@kintone/plugin-packer（以下、plugin-packer）をインストールします。

npm install --save-dev @kintone/plugin-packer

次に、パッケージのためのコマンドを npm scripts に定義します。
package.json の scripts に次のコマンドを追加します。
src の部分は manifest.json が存在するディレクトリ名までの相対パスを指定してください。

package.json
  "scripts": {
    // ...
    "upload": "kintone-plugin-uploader dist/plugin.zip --watch --waiting-dialog-ms 3000",
+    "pkg": "kintone-plugin-packer src"
  }

STEP2：リポジトリシークレットの設定

ワークフロー内で秘密鍵ファイルを利用するために、リポジトリのシークレットに秘密鍵ファイルの内容を登録します。

  1. リポジトリの[Settings]を開きます。
  2. 左メニューから[Secrets and variables]>[Actions]の順に選択します。
  3. [New repository secret]をクリックします。
  4. 名前に PPK_SECRET、値に秘密鍵ファイルの内容を入力します。
    スクリーンショット：Run workflow をクリックするシークレットを設定している
  5. [Add secret]をクリックします。

STEP3：GitHub Actions のワークフローの作成

workflow_dispach をトリガーにして、パッケージングとリリースを実施するワークフローを作成します。
GitHub のリリース機能ではタグを作成する必要があるため、ワークフロー内でリリースするバージョンのタグを作成しています。

ファイルの作成

ファイルを作成します。

mkdir -p .github/workflows
touch .github/workflows/release.yml

まずはベース部分を追記します。
plugin-packer を使うために、Node.js の環境をセットアップします。

.github/workflows/release.yml
name: Release

on:
  workflow_dispatch:

jobs:
  release:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version-file: ./.node-version
          cache: "npm"

      - name: Install dependencies
        run: npm ci
        env:
          CI: true

Node.js のバージョンは .node-version を参照しています。
.node-version は使用する Node.js のバージョンが記述されたファイルで、リポジトリのルートに配置します。

.node-version
20.11.1

パッケージングのステップを追加

次に、パッケージングするステップを追記します。
MANIFEST_FILE に定義したファイルのパスは、ディレクトリ構成に合わせて修正してください。

.github/workflows/release.yml
      - name: Install dependencies
        run: npm ci
        env:
          CI: true

+     - name: Run package
+        id: package
+        run: |
+          MANIFEST_FILE=src/manifest.json
+          PLUGIN_NAME=$(jq -r '.name.en' "$MANIFEST_FILE")
+          PLUGIN_VERSION=$(jq -r '.version' "$MANIFEST_FILE")
+          PLUGIN_NAME=$(jq -r '.name.en' src/manifest.json)
+          PLUGIN_VERSION=$(jq -r '.version' src/manifest.json)
+          PLUGIN_FILE_NAME="$PLUGIN_NAME"_v"$PLUGIN_VERSION".zip
+          # generate ppk file
+          cat << EOF > ./"$PLUGIN_NAME".ppk
+          ${{ secrets.PPK_SECRET }}
+          EOF
+          # package
+          npm run pkg -- --ppk "$PLUGIN_NAME".ppk --out "$PLUGIN_FILE_NAME"
+          rm -f ./"$PLUGIN_NAME".ppk
+          # export output variables
+          echo "TAG_NAME=v${PLUGIN_VERSION}" >> "$GITHUB_OUTPUT"
+          echo "PLUGIN_FILE_NAME=${PLUGIN_FILE_NAME}" >> "$GITHUB_OUTPUT"
+        env:
+          PPK_SECRET: ${{ secrets.PPK_SECRET }}

このステップのポイントは、次の 3 点です。

  • プラグインの名前やプラグインのバージョンは、manifest.json から取得する
  • 秘密鍵ファイルは、リポジトリのシークレットの内容を元に生成する。
  • プラグインファイルのファイル名やバージョンを次のステップで利用するため $GITHUB_OUTPUT に出力する。

リリースのステップを追加

最後に、リリースするステップを追記します。
タグやリリースを作成するため、content: write の権限を付与します。

.github/workflows/release.yml
on:
  workflow_dispatch:

+ permissions:
+  contents: write

jobs:

最後に、リリースするステップを追記します。
タグやリリースの作成には、GitHub CLI を使います。
GitHub CLI で使用する認証情報は、環境変数の GH_TOKEN に設定します。
設定する値は、${{ secrets.GITHUB_TOKEN }} で参照できるワークフローを実行するための一時的なトークンを利用します。

.github/workflows/release.yml
        env:
          PPK_SECRET: ${{ secrets.PPK_SECRET }}

+      - name: Release
+        run: |
+          git tag "$TAG_NAME"
+          git push --tags origin "$TAG_NAME"
+          gh release create "$TAG_NAME" ${{ env.PLUGIN_FILE_NAME }} --generate-notes
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG_NAME: ${{ steps.package.outputs.TAG_NAME }}
+          PLUGIN_FILE_NAME: ${{ steps.package.outputs.PLUGIN_FILE_NAME }}

以上でワークフローは完成です。
最終的なワークフローの内容は、次のとおりです。

.github/workflows/release.yml
name: Release plugin

on:
  workflow_dispatch:

permissions:
  contents: write

jobs:
  release:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version-file: ./.node-version
          cache: "npm"

      - name: Install dependencies
        run: npm ci
        env:
          CI: true

      - name: Run package
        id: package
        run: |
          MANIFEST_FILE=src/manifest.json
          PLUGIN_NAME=$(jq -r '.name.en' "$MANIFEST_FILE")
          PLUGIN_VERSION=$(jq -r '.version' "$MANIFEST_FILE")
          PLUGIN_FILE_NAME="$PLUGIN_NAME"_v"$PLUGIN_VERSION".zip
          # generate ppk file
          cat << EOF > ./"$PLUGIN_NAME".ppk
          ${{ secrets.PPK_SECRET }}
          EOF
          # package
          npm run pkg -- --ppk "$PLUGIN_NAME".ppk --out "$PLUGIN_FILE_NAME"
          rm -f ./"$PLUGIN_NAME".ppk
          # export output variables
          echo "TAG_NAME=v${PLUGIN_VERSION}" >> "$GITHUB_OUTPUT"
          echo "PLUGIN_FILE_NAME=${PLUGIN_FILE_NAME}" >> "$GITHUB_OUTPUT"
        env:
          PPK_SECRET: ${{ secrets.PPK_SECRET }}

      - name: Release
        run: |
          git tag "$TAG_NAME"
          git push --tags origin "$TAG_NAME"
          gh release create "$TAG_NAME" ${{ env.PLUGIN_FILE_NAME }} --generate-notes
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          TAG_NAME: ${{ steps.package.outputs.TAG_NAME }}
          PLUGIN_FILE_NAME: ${{ steps.package.outputs.PLUGIN_FILE_NAME }}

動作確認

workflow_dispatch を実行して、Releases にプラグインファイルがアップロードされることを確認します。

  1. リポジトリの[Actions]を開きます。
  2. 左メニューから[Release plugin]を選択します。
  3. [Run workflow]をクリックします。
    スクリーンショット：Run workflow をクリックする
  4. [Run workflow]をクリックします。
    スクリーンショット：Run workflow をクリックする
    ワークフローが開始され、パッケージングとリリースが実行されます。
  5. ワークフローの状態が「Success」になるまで待ちます。
    スクリーンショット：ワークフローの状態が Success になっている
  6. リポジトリのトップページに移動します。
  7. リリースが作成され、「Assets」にプラグインファイルがアップロードされていれば成功です。
    スクリーンショット：リリースが作成されている

参考情報

動作を確認したバージョン

  • Node.js v20.11.1
  • @kintone/plugin-packer v8.0.4

Discussion