emdash-github-actions

EmDash Plugin GitHub Actions

このスキルを使うと、GitHub Actions で EmDash プラグイン向けの包括的な CI/CD パイプラインを設定できます。EmDash は Astro をベースとするフルスタックの TypeScript CMS であるため、そのプラグインエコシステムはすべて TypeScript で構成されています。

このスキルで扱う内容

健全な EmDash プラグインには、いくつかのカテゴリのワークフローが必要です。すべてのプラグインで全部が必要なわけではなく、適切な組み合わせはプラグインの複雑さ、React 管理 UI の有無、テストの有無などによって異なります。どれが該当するかを判断し、設定してください。

ワークフローは次のカテゴリに分かれます。

1. 型チェック — emdash ピア依存関係を使用した TypeScript strict モード
2. コード品質 — TypeScript をサポートする ESLint
3. テスト — Vitest など、TypeScript ネイティブのテストランナー
4. セキュリティ — 依存関係の脆弱性を検出する npm audit
5. デプロイ — タグまたはリリース時の npm publish の自動実行

各ワークフローの詳しい設定と、そのまま使える YAML テンプレートおよび設定ファイルについては、references/workflows.md をお読みください。

リクエストへの対応方法

ステップ 1：プラグインを把握する

ワークフローファイルを作成する前に、対象となるプラグインについて確認してください。

• プラグインの機能は何ですか？ package.json の説明と src/index.ts のエクスポートを確認します。EmDash プラグインは通常、page:metadata、page:fragment、コンテンツフックに接続するか、管理 UI を提供します。
• React 管理 UI がありますか？ .tsx ファイルまたは admin.tsx を確認します。ある場合、型チェックには @types/react と --jsx react-jsx が必要です。
• テストがありますか？ tests/ または __tests__/ ディレクトリ、あるいは vitest.config.ts があるか確認します。ある場合はテストワークフローを設定します。ない場合は、テストの追加が有益であることを伝えますが、無理に追加する必要はありません。
• ピア依存関係は何ですか？ package.json の peerDependencies を確認します。EmDash プラグインは必ず emdash に依存し、react、astro などにも依存する場合があります。
• 追加の npm 依存関係を使用していますか？ package.json に dependencies があるか確認します。ある場合、CI に npm install のステップが必要です。
• npm に公開されていますか？ パッケージ名にスコープがあるか（例：@org/emdash-plugin-foo）、また publishConfig が設定されているか確認します。該当する場合は、デプロイワークフローが適しています。

ステップ 2：ワークフローの組み合わせを提案する

確認した内容に基づいて、設定するワークフローを提案します。ほとんどのプラグインに適した基本の組み合わせは次のとおりです。

• TypeScript の型チェック（ほぼ常に必要で、最も有益なチェックです）
• ESLint（プラグインに数個以上のファイルがある場合）
• npm audit（手軽なセキュリティチェックで、ほぼ常に実施する価値があります）

条件に応じて、次のワークフローも追加します。

• Vitest テスト（テストがある場合）
• npm publish（プラグインが npm に公開されている場合）

ステップ 3：ワークフローファイルを作成する

各ワークフローは、.github/workflows/ に個別の YAML ファイルとして作成します。1 つの大きなワークフローにまとめるよりも、ファイルを分けることで PR でのフィードバックが明確になり（各チェックの結果が個別に表示されます）、個々のチェックを有効化・無効化しやすくなります。

references/workflows.md のテンプレートを出発点として使い、対象のプラグインに合わせて調整してください。よくある調整は次のとおりです。

• プラグインに .tsx ファイルがある場合は @types/react を追加する
• 型を提供する追加のピア依存関係を追加する
• 型チェックコマンドと lint コマンドのファイルパスを調整する
• npm publish のスコープとアクセスレベルを設定する

ステップ 4：補助設定ファイルを作成する

設定するワークフローによっては、次のファイルも必要です。

• tsconfig.json — TypeScript の設定（まだ存在しない場合）
• eslint.config.js — TypeScript をサポートする ESLint のフラット設定
• vitest.config.ts — Vitest の設定

ステップ 5：シークレットの設定を促す

npm 公開ワークフローを追加する場合は、GitHub でリポジトリシークレットを設定する必要があることをユーザーに伝えてください。

• NPM_TOKEN — 公開権限を持つ npm アクセストークン

次の手順を案内してください：Repository Settings > Secrets and variables > Actions > New repository secret。

スコープ付きパッケージ（@org/package-name）の場合、トークンには組織へのアクセス権が必要です。

命名規則

各ワークフローの役割が明確にわかる、説明的なワークフローファイル名を使用してください。

• ci.yml — TypeScript の型チェック（主要な CI チェック）
• lint.yml — ESLint
• test.yml — Vitest／テストランナー
• security.yml — npm audit
• publish.yml — リリース時の npm 公開

重要な詳細

Node.js のバージョン：デフォルトでは Node.js 22 を使用してください。EmDash は最新の TypeScript と Astro を基盤としているため、古い Node.js のバージョンをサポートする必要はありません。actions/checkout@v5 と actions/setup-node@v5 を使用してください（v5 は Node.js 24 のランナーで実行されるため、Node.js 20 の非推奨化を回避できます）。

ピア依存関係のインストール：EmDash プラグインでは、emdash をピア依存関係として宣言します。CI で型チェックを行うには、スタンドアロンのプラグインリポジトリではピア依存関係が自動インストールされないため、emdash（およびプラグインに .tsx ファイルがある場合は @types/react）を明示的にインストールする必要があります。

--skipLibCheck フラグ：CI で tsc を実行するときは、--skipLibCheck を使用してください。EmDash とその推移的依存関係には、プラグインの作者には関係のない内部的な型の問題が含まれている場合があります。--skipLibCheck は .d.ts ファイルのチェックをスキップしつつ、プラグイン独自のソースコードは完全にチェックします。

ファイル検索での find コマンドの使用：CI コマンドでは、src/**/*.ts のようなシェルのグロブを使用しないでください。指定した階層で一致するファイルがない場合に失敗します。代わりに $(find src -name '*.ts' -o -name '*.tsx') を使用してください。

ブランチ名：ほとんどの EmDash プラグインリポジトリでは、デフォルトブランチに main を使用しています。ワークフローのトリガーには、必ず実際のリポジトリを確認して正しいブランチ名を使用してください。