こんにちは！プロダクト開発の現場で、デザイナーとエンジニアの連携に頭を悩ませたことはありませんか？
「デザインが修正されたのに、エンジニアに伝わっていなくて古いUIを実装してしまった」
「仕様変更のたびに、GitHubのチケットとデザインを行き来するのが面倒……」
そんな分断されたワークフローを根底から覆し、デザインとコードをシームレスに繋ぐ魔法のような手法があります。それが、オープンソースのデザインツール「Penpot」と「GitHub Actions」を組み合わせたCI/CDパイプラインの構築です。
これをマスターすれば、デザインが更新された瞬間に自動で差分を検出し、Slackに通知したり、プレビュー環境をビルドしたりする「真のDesignOps（デザインオペレーション）」が手に入ります。毎日の開発作業が劇的に楽になりますよ。
今回は、Penpotに触れたばかりの初心者の方でも挫折しないよう、基礎のセットアップから動作確認（HelloWorld）まで、優しくロジカルに解説していきますね！
—
1. なぜ「Penpot × GitHub Actions」なのか？
従来のFigmaなどのツールでもAPIを使った連携は可能でしたが、プロプライエタリ（独自仕様）の壁があり、自社のCI/CDパイプラインへ深く組み込むには複雑なスクリプトが必要でした。
その点、Penpotは完全オープンソース（OSS）です。システム全体がオープンであるため、Webhooksの挙動も極めてクリアで、GitHubなどの開発基盤と親和性が抜群に高いのが特徴です。
描く未来のワークフロー
1. デザイナーがPenpot上でUIコンポーネントを修正する。
2. Penpotの Webhooks がそれを検知し、GitHubへシグナルを送る。
3. GitHub Actions が起動し、デザインの変更差分を解析（またはプレビューをビルド）。
4. チームのSlackチャンネルに「新しいデザイン更新があります！」と通知が飛ぶ。
この仕組みを、一緒に手を動かして作っていきましょう！
—
2. 基礎セットアップ：Penpot Webhooksの準備
まずは、Penpot側から「デザインが更新されたよ」という合図（イベント）を受け取れるように設定します。
ステップ1: PenpotでWebhookのエンドポイントを作る
実際のプロダクションではサーバーを用意しますが、今回は動作確認（HelloWorld）のために、受け取ったデータをコンソールに表示する簡単なローカルサーバーか、Webhookのテストサービス（例: `Webhook.site` など）を使用するのがおすすめです。
1. [Webhook.site](https://webhook.site/) にアクセスし、専用のユニークなURL（例: `https://webhook.site/xxxx-xxxx…`）をコピーします。
2. Penpotのプロジェクト（またはチーム設定）を開き、Webhooks設定画面に移動します。
3. コピーしたURLをペーストし、検知したいイベント（例: `file.update` など）を選択して保存します。
※Self-hosted版のPenpotをお使いの場合は、環境変数や管理画面からWebhookの設定を行います。
—
3. GitHub Actionsとの連携：パイプラインの構築
ここからがエンジニアの腕の見せ所です。Penpotのイベントをトリガーに、GitHub上で何かしらの処理を実行するワークフローを定義します。
今回は「PenpotからのWebhookを受け取る（厳密にはGitHub側でトリガーを受ける、あるいはGitHub Actionsの `repository_dispatch` を利用する）」ための第一歩として、GitHub Actionsの基本的な設定と、デザイン変更を模したワークフローの動かし方を解説します。
リポジトリの準備
GitHub上に適当なリポジトリ（例: `penpot-ci-demo`）を作成し、ローカルでクローンしてください。
ワークフローファイルの作成
プロジェクトのルートディレクトリに `.github/workflows/penpot-sync.yml` というファイルを作成し、以下のコードを記述します。
name: Penpot Design Sync CI
1. トリガーの設定
今回は手動（workflow_dispatch）および、外部からのrepository_dispatchイベントをフックします
on:
workflow_dispatch:
repository_dispatch:
types: [penpot_update]
jobs:
detect-design-change:
runs-on: ubuntu-latest
steps:
# 2. リポジトリのコードをチェックアウト
- name: Checkout Repository
uses: actions/checkout@v4
# 3. Node.js環境のセットアップ（デザイン解析スクリプト動作用）
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: ’20’
# 4. 依存関係のインストール（必要に応じて）
- name: Install Dependencies
run: npm install
# 5. HelloWorld的な動作確認スクリプトの実行
- name: Run Design Change Handler
run: |
echo “==========================================”
echo “Penpotからのデザイン更新シグナルを受信しました！”
echo “イベントトリガー: ${{ github.event_name }}”
echo “==========================================”
# ここにデザイン差分を検出する独自のNode.jsスクリプトなどを呼び出します
node scripts/notify-design-update.js
env:
PENPOT_WEBHOOK_PAYLOAD: ${{ toJson(github.event.client_payload) }}
—
4. 精度高い HelloWorld：動作確認スクリプトの実装
先ほどのGitHub Actionsから呼び出される、ささやかな動作確認用のスクリプトを作ってみましょう。
プロジェクトのルートに `scripts/notify-design-update.js` を作成します。
// scripts/notify-design-update.js
console.log(“🎨 [Penpot CI] デザイン変更の解析処理を開始します…”);
// GitHub Actionsの環境変数から、PenpotのWebhookペイロードを受け取る
const rawPayload = process.env.PENPOT_WEBHOOK_PAYLOAD;
try {
if (rawPayload && rawPayload !== “null”) {
const payload = JSON.parse(rawPayload);
console.log(“📦 受信したPenpotのペイロードデータ:”, JSON.stringify(payload, null, 2));
// ここでデザインのファイルIDや更新者などをバリデーション・解析します
console.log(“✨ 正常にデザインデータの解析を完了しました。UIプレビューのビルドを準備します。”);
} else {
console.log(“ℹ️ 手動実行（workflow_dispatch）またはペイロードなしのテスト実行です。”);
console.log(“🚀 HelloWorld: PenpotとGitHub Actionsのパイプラインは正常に稼働しています！”);
}
} catch (error) {
console.error(“❌ ペイロードのパースに失敗しました:”, error.message);
process.exit(1);
}
動作テストをしてみよう！
1. ここまでの変更をコミットして、GitHubへプッシュします。
git add .
git commit -m “feat: Add Penpot CI workflow and hello-world script”
git push origin main
2. GitHubリポジトリの [Actions] タブを開きます。
3. 左側のメニューから 「Penpot Design Sync CI」 を選択します。
4. [Run workflow] ボタンをクリックして手動実行してみましょう！
数秒後、ジョブが緑色に成功し、ログに「🚀 HelloWorld: PenpotとGitHub Actionsのパイプラインは正常に稼働しています！」というメッセージが表示されたはずです。これで、自動化の土台が完璧に組み上がりました！
—
5. 現場で使えるステップへ：次の展開
お疲れ様でした！これでPenpotとGitHub Actionsを連携させるための基礎インフラが整いました。
実務では、このパイプラインをさらに拡張して、以下のようなアプローチをとることでチームの生産性が爆発的に向上します。
- Penpot APIの活用: 更新されたイベントからFile APIを叩き、最新のアセット（SVGやトークン）を自動でリポジトリにプルリクエストとして作成する。
- デザイントークンの自動同期: Penpotの色定義やタイポグラフィの変更を検出し、CSS変数やTailwindのConfigへ自動変換してコミットする。
「デザインが変わったら、コードの世界も自動で追従する」。この体験を一度味わうと、もう手動での連携には戻れなくなりますよ。
ぜひ今回のコードをベースに、あなたのチームのワークフローに合わせたカスタムCI/CDを育ててみてくださいね。それでは、快適なデザイン＆エンジニアリングライフを！