Figma CLI（Code Connect）の設定とGitHub連携｜PAT発行からActionsでの自動publishまで

「Figma CLI」と呼ばれているのは、npm パッケージ @figma/code-connect が入れる figma コマンドのことです。Figma のコンポーネントと GitHub 上の実装コードを対応づけ、Dev Mode の Inspect パネルや Figma MCP サーバーに自社のコードを出す Code Connect を、ターミナルから操作します。この記事では、CLI のインストール、個人アクセストークン（PAT）と CI 用トークンの発行、figma.config.json の書き方、GitHub Actions での自動 publish、Figma 側からの GitHub 接続までを、2026年10月14日公開の CLI 2.0.2 で実行した結果とあわせて説明します。Code Connect の位置づけや Dev Mode での見え方はFigma Code Connectの使い方｜UIとCLIの始め方とDev Mode表示・CLI v2移行で扱っているので、本記事は設定と運用に絞ります。

まとめ：Figma CLIとGitHub連携の要点

• CLI は npm install --save-dev @figma/code-connect でリポジトリに入れ、npx figma connect publish で公開します。最新は 2.0.2（2026年10月14日）、Node.js 18 以上が要件です。
• 使えるのは Professional・Organization・Enterprise・Government プランの Dev または Full シートです。Professional は有効なライブラリとフレームワークが1つずつに限られます。
• PAT のスコープは「Code Connect」を Write、「File content」を Read にします。有効期限は最長90日です。
• CI には Organization 以上なら「Figma CLI」タブで発行するプランアクセストークン（最長365日）を使います。REST API タブのトークンでは公開できません。Professional は PAT を使います。
• 2026年8月18日の CLI 2.0.0 から、React・SwiftUI などのフレームワーク別パーサーで書いた .figma.tsx 等は migrate と unpublish 以外で終了コード1になります。figma connect migrate でテンプレートファイル（.figma.ts）へ移すか、v1 に留まります。
• 公式の GitHub Actions 例をそのまま使うと、リポジトリの取得と依存のインストールが無いため npx が別の npm パッケージを引いて失敗します。actions/checkout と npm ci を足してください。
• Figma 側から GitHub リポジトリを接続する Code Connect UI は GitHub Enterprise Server に対応していません。

Figma CLI（Code Connect CLI）の導入要件とインストール

利用できるプランとシート

公式のGetting started with Code Connect CLIが挙げる要件は、Node.js 18 以上、Code Connect を Write・File content を Read にした PAT、Professional・Organization・Enterprise いずれかのプランの Dev または Full シートの3つです。ヘルプセンターの Code Connect のページは、これに Government プランを加えた4プランを対象としています。以前の公式案内は Organization と Enterprise に限っていたため、古い解説で「Professional では使えない」と書かれていても現在は当てはまりません。

ただし Professional には上限があります。有効なライブラリとフレームワークは1つずつで、フレームワークはチームで最初に publish したものに決まります。変更はチーム管理者が Admin の Settings、Resources、Code Connect の順に開いて行い、切り替える前のフレームワークの対応づけは Dev Mode で Deactivated と表示され、MCP サーバーにも返らなくなります（Code Connect UI のセットアップ）。React と SwiftUI の両方を出したいデザインシステムなら Organization 以上が前提です。2.0.2 では、Professional でこの上限を超える publish をすると CLI が制限内容と変更方法を表示するようになりました。

Code Connect CLIの導入とnpxのパッケージ解決

公式の導入例はグローバルインストールです。

npm install --global @figma/code-connect@latest

継続運用するリポジトリでは devDependencies に入れて版を固定します。npm は既定で ^2.0.2 のような範囲指定で保存するので、--save-exact を付け、package.json と package-lock.json の両方をコミットします。

npm install --save-dev --save-exact @figma/[email protected]
npx figma --version

ここで注意が1つあります。npx figma は、プロジェクトに @figma/code-connect が入っていないと npm レジストリの figma という別パッケージ（0.0.1・実行ファイルなし）を取りに行き、npm error could not determine executable to run で終了コード1になります。依存を入れていない場所で一度だけ実行したいときは、パッケージを明示して npx -p @figma/[email protected] figma connect publish と書きます。2.0.2 で確認すると、空のディレクトリでも npx -p を付ければ起動し、終了コードは0でした。

コマンド一覧とv2での扱い

「トークン」列は 2.0.2 で FIGMA_ACCESS_TOKEN を外して実行した結果です。parse と migrate だけは手元で完結し、preview と create は Figma からコンポーネントのプロパティを取るため、トークンが無いと Couldn't find a Figma access token で止まります。2.0.2 の create は、フレームワーク別パーサーを指定したプロジェクトでも必ずテンプレートファイルを生成します（CHANGELOG）。

アクセストークン（PAT・プランアクセストークン）の発行とスコープ

PATの発行手順と必要スコープ

PAT は、Figma のファイルブラウザ左上のアカウントメニューから Settings を開き、Security タブの Personal access tokens で Generate new token を押して作ります。有効期限とスコープを選ぶと値が一度だけ表示され、閉じると再表示できません。

Code Connect に必要なスコープは、「Code Connect」の Write と「File content」の Read です。渡し方は --token オプションか環境変数 FIGMA_ACCESS_TOKEN の2通りです。値が間違っているときは、2.0.2 では Failed to to fetch node info (403): 403 Invalid token と出て終了コード1になります（原文のまま「to to」と重複しています）。同じトークンは REST API の X-Figma-Token ヘッダーにも使えます。REST API 側のスコープやレート制限はFigma APIの使い方｜APIキー発行・レート制限の実数・Variables REST APIの条件にまとめています。

CI向けのFigma CLIトークン（プランアクセストークン）

PAT は発行した個人に紐づき、最長90日で切れます。退職や異動、期限切れのたびに CI が止まるため、公式のContinuous Integrationは、CI にはプランアクセストークン（PLANT）を勧めています。PLANT は Organization と Enterprise プランだけで発行でき、Professional では PAT を使うよう明記されています。

発行は https://www.figma.com/developers/tokens で行い、管理者は Figma の2要素認証を設定している必要があります（SSO ログインを必須にしている組織は除く）。Plan access tokensによると、Figma CLI トークンはスコープが固定でプラン全体に効き、REST API 用トークンのように対象ファイルを許可リストで絞ることはできません。漏れたときの影響範囲がプラン全体になるので、GitHub の Environment secrets に保存し、そのEnvironmentを参照するジョブをpublish用に限定します。同じEnvironmentを参照する別のジョブもSecretを利用できる点には注意してください。

期限前の更新には Refresh token を使います。新しい値が発行されても古い値は24時間有効なので、その間に GitHub の Secrets を差し替えればパイプラインを止めずに済みます。

REST APIタブのトークンでは公開できない理由

トークン発行画面の左上には REST API・npm registry・Figma CLI の3つのタブがあり、既定は REST API です。REST API 用の PLANT は file_code_connect:write スコープを要するエンドポイントを対象外としているため、ここで発行したトークンでは Code Connect を公開できません。必ず Figma CLI タブに切り替えて Generate Figma CLI token を押してください。発行後の使い方は PAT と同じで、FIGMA_ACCESS_TOKEN に入れるだけです。

figma.config.jsonの書き方

codeConnectキーを省くと起きる解析エラー

設定ファイルはプロジェクトのルート（package.json や .xcodeproj と同じ階層）に figma.config.json として置き、設定値は codeConnect キーの下に書きます。

{
  "codeConnect": {
    "include": ["src/**/*.figma.ts"],
    "exclude": ["test/**", "build/**"],
    "label": "React",
    "language": "jsx"
  }
}

公式のテンプレート移行ガイドの「Testing in Figma」にある設定例は、2026年10月時点でも codeConnect を省いた平坦な形のままです。これを 2.0.2 に読ませると、次のように止まります（終了コード1）。

Error parsing config file: TypeError: Cannot read properties of undefined (reading 'include')
    at checkForLegacyConfig (.../dist/connect/project.js:160:25)

JSON の構文ミスを疑いたくなる文言ですが、原因は階層です。CLI が設定を読まないときは、最初に codeConnect の有無を確認してください。

include・label・language・apiUrlの指定

include と exclude は、設定ファイルの位置から見た相対パスの glob です。テンプレートファイルの拡張子は .figma.ts か .figma.js です。通常のテンプレートはこの拡張子を対象にしますが、バッチ形式を使う場合は include に src/**/*.figma.batch.json も加えます。旧形式の .figma.tsx が当たると v2 で止まる理由は後述します。

label は Dev Mode に出る見出し、language はシンタックスハイライトの指定で、jsx・tsx・swift・kotlin・html・dart など20種類から選びます（Configuring your project）。ほかに、ソースへのリンクに使うブランチ名を指定する defaultBranch、公開先のファイルURLを置き換える documentUrlSubstitutions、Figma for Government のように API のホストが違う環境で使う apiUrl があります。apiUrl はコマンドごとに --api-url で上書きでき、こちらが優先されます。なお Figma for Government では CLI は使えますが Code Connect UI は使えません。

複数フレームワークを1コンポーネントに並べる構成

同じ Figma コンポーネントに React 版と SwiftUI 版のスニペットを並べるには、フレームワークごとにテンプレートファイルを分け、先頭の // url= コメントに同じURLを書きます。設定ファイルもフレームワークごとに用意し、それぞれに固有の label と、そのフレームワークのファイルだけを拾う include を持たせて、--config で切り替えて公開します。前述のとおり、この構成は Professional では使えません。

GitHub Actionsでpublishを自動化する手順

npmプロジェクト向けの自動publishワークフロー

手元で publish できたら、main へのマージで自動公開するようにします。@figma/code-connect を devDependencies に入れて package-lock.json をコミットし、GitHub の Environment figma に FIGMA_ACCESS_TOKEN を登録した npm プロジェクト向けの例です。テンプレートから相対パスで読み込むヘルパーファイルがある場合は、そのパスも paths に加えてください。

name: Code Connect
on:
  push:
    branches:
      - main
    paths:
      - "src/**/*.figma.ts"
      - "src/**/*.figma.js"
      - "src/**/*.figma.batch.json"
      - "src/**/*.figma.batch.ts"
      - "src/**/*.figma.batch.js"
      - "figma.config.json"

jobs:
  publish:
    runs-on: ubuntu-latest
    environment: figma
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npx figma connect publish --exit-on-unreadable-files
        env:
          FIGMA_ACCESS_TOKEN: ${{ secrets.FIGMA_ACCESS_TOKEN }}

paths で対象を絞らないと、Code Connect と無関係な変更でも毎回ジョブが走ります。environment: figma は、前述の Environment secrets にトークンを置く場合の指定です。リポジトリの Secrets に置くなら外して構いません。

公式例のままだと終了コード1になる理由

公式のContinuous Integrationのワークフロー例は、ステップが npx figma connect publish の1行だけで、actions/checkout も依存のインストールもありません。GitHub Actions のランナーは空の作業ディレクトリで始まるので、この状態の npx figma は前述の別パッケージ figma を取りに行きます。CI 環境では npx がインストール確認を自動で承認するため、空のディレクトリで CI=true を付けて再現すると、npm error could not determine executable to run で終了コード1でした。

もう1点、公式例の paths は旧形式の拡張子 *.figma.tsx のままです。テンプレートファイルへ移した後にこのまま使うと、.figma.ts を変更してもワークフローが起動しません。上の例では *.figma.ts と figma.config.json を監視対象にしています。

プルリクエストでの事前確認

マージ前に公開対象を確かめるなら、プルリクエストのジョブで --dry-run を回します。ただし --dry-run も Figma API でノードを検証するため、トークンが要ります。トークンを外して実行すると Files that would be published: の一覧を出したあと、トークンが見つからないエラーで終了コード1になりました。フォークからのプルリクエストには Secrets が渡らないので、外部からの PR を受けるリポジトリでは dry-run を内部ブランチに限るか、parse で設定の解釈だけを確かめる形にします。

一覧のコンポーネント名は、テンプレートファイルでは 2.0.2 でも undefined と出ますが、公開には影響しません。

Code Connect UIからGitHubリポジトリを接続する手順

Code Connect UIのGitHub接続手順と管理権限

「Figma と GitHub の連携」にはもう1つ、Figma 側の Code Connect UI からリポジトリを接続する経路があります。CLI の publish とは別物で、こちらは UI 上で対応づけを作る作業を補助します。接続すると、対応づけの入力欄にリポジトリ内のファイルパスとコンポーネント名が補完され、MCP サーバーに実装コードへの参照が渡り、コンポーネントごとに「Add instructions for MCP」で AI 向けの指示文を持たせられます（Connect to your GitHub repositories）。

手順は、ライブラリファイルで Code Connect UI を開き、設定アイコンから Connect to GitHub を選んで、リポジトリにアクセスできる GitHub アカウントか organization を認可する流れです。接続できるのはファイルの所有者で、Organization・Enterprise では組織管理者も接続できます。認可後にリポジトリを選び、一覧の上の + で2つ目以降を追加します。

GHES非対応とProfessionalの条件

GitHub Enterprise Server（自社ホスト版）には対応していません。オンプレミスで GitHub を運用している組織は UI 接続を使えないので、CLI と CI での publish に寄せます。

1つのライブラリファイルに複数のリポジトリを接続できるようになっており、以前の「1ライブラリ1リポジトリ」という制約は解消されています。Professional でも複数のリポジトリを接続できますが、すべて同じフレームワークである必要があります。

この接続で使う Figma GitHub app は、Figma Make のプロジェクトを GitHub へ push する機能や、Make とコードレイヤーでリポジトリを clone する機能と共通です（Manage the Figma GitHub app）。GitHub の organization へつなぐ場合は、Figma のチームか組織の管理者が始め、GitHub 側の organization 管理者の承認で完了します。Figma の管理者がアプリを外すと、Make からの push と Code Connect UI のコード接続の両方が使えなくなります。Make 側の料金や書き出しはFigma Makeの料金・AIクレジットとは？プラン別の上限と消費量・使い方・エクスポートまで解説で扱っています。

UIで作った対応づけとCLIの衝突

同じコンポーネントに UI で作った対応づけがあると、CLI の publish は警告を出し、その対応づけを上書きしません（1.4.4 より前は警告も出さずに失敗していました）。リポジトリ側の定義を正とするなら npx figma connect publish --force で上書きします。デザイナーが UI で対応づけ、エンジニアが CLI で公開する分担にしている組織では、どちらを正とするかを先に決めておかないと、CI のログに警告が出続けるだけで、Dev Mode には UI 側の対応づけが残ります。

CLI v2で旧パーサー方式が止まる変更と移行

2.0.0の破壊的変更とv1に留まる選択

Code Connect は当初、React・SwiftUI・Jetpack Compose・Web Components ごとのパーサーで figma.connect() を書く方式でした。Figma は2026年8月17日にこの方式の更新と保守を終え、翌18日の CLI 2.0.0 で、パーサー方式のファイルを扱えるのを migrate と unpublish だけにしました（CHANGELOG）。React の .figma.tsx を 2.0.2 の parse に通すと、次の案内を出して終了コード1になります。

Framework-specific parsers are no longer supported in Code Connect CLI v2.

Run `figma connect migrate` to convert parser-based Code Connect to template files:
https://developers.figma.com/docs/code-connect/templates-migration-guide/

Alternatively, if you're not able to migrate right now, continue using Code Connect v1:
npm install --save-dev @figma/code-connect@1

すぐ移せない場合は v1 系（最終は 1.5.3）に固定すれば従来どおり動きます。ただし v1 はもう更新されないので、時間稼ぎと割り切ってください。パーサー方式のまま CI で @figma/code-connect@latest を入れていたリポジトリは、2.0.0 が出た日から設定を変えていなくても止まっています。

migrateの実行結果

移行は migrate がプロジェクト全体を解析し、テンプレートファイルとして書き出します。トークンは要りません。figma.string・figma.enum・figma.boolean を使った React の Button を変換すると、次のファイルができました。

// url=https://www.figma.com/design/abc123/DS?node-id=1-2
// component=Button

import figma from "figma"

const label = figma.selectedInstance.getString("Label")
const variant = figma.selectedInstance.getEnum("Variant", {
  Primary: "primary",
  Secondary: "secondary",
})
const disabled = figma.selectedInstance.getBoolean("Disabled")

export default {
  id: "Button",
  imports: ["import { Button } from './Button'"],
  example: figma.code`<Button${figma.helpers.react.renderProp(
    "label",
    label,
  )}${figma.helpers.react.renderProp(
    "variant",
    variant,
  )}${figma.helpers.react.renderProp("disabled", disabled)}/>`,
  metadata: { nestable: true },
}

実行時、include が .figma.tsx だけを指していたため「Import for Button could not be resolved」という警告が出ました。変換自体は成功しますが、import 文の解決に実装ファイルを使うので、include にはコンポーネント本体のパスも含めて実行するのが確実です。

--include-props が要るのは、React の .getProps() や .render() を使っている場合と、他のテンプレートから executeTemplate().metadata.__props を読んでいる場合だけです。--batch auto は Code Connect の定義を10個以上含むファイルを、テンプレート1つと部品の一覧からなるバッチファイル（.figma.batch.json）にまとめようとします。アイコンのように同じ形の部品が数百ある場合に効きます。

移行後に残った.figma.tsxで止まる落とし穴

--delete を付けずに移行すると、新しい .figma.ts の隣に元の .figma.tsx が残ります。この状態で include が両方に当たっていると、parse も publish も上の「no longer supported」で終了コード1になりました。2.0.2 で設定を変えて実行し分けると、効いていたのは parser キーの有無ではなく include の当たり方です。"parser": "react" を残していても include を src/**/*.figma.ts に絞れば通り、逆に parser を消しても src/** のままでは止まります。移行を確認したら .figma.tsx を消すか、include を新しい拡張子に絞ってください。

そのうえで、設定ファイルから parser・importPaths・paths・imports・xcodeprojPath・sourcePackagesPath・importMapping などパーサー固有の項目を消します。変換結果は getPropertyValue() の文字列比較による if 分岐で冗長になることが多いので、getBoolean()・getEnum() に書き換えると読みやすくなります。

一時ラベルでの検証公開

移行結果を Figma 上で確かめるときは、Organization・Enterpriseでは本番と区別するため、label を TEST などの一時的な値にし、include を新しいファイルだけに絞った設定ファイルを別に作ります。Professional では有効なフレームワークが1つに限られるため、まず parse と preview で手元の確認を済ませ、Figma 側に出すのは本番と同じ設定で行う方が安全です。

npx figma connect publish --config figma.test.config.json
npx figma connect unpublish --config figma.test.config.json

この検証用の設定も codeConnect キーで包んでください（前述の解析エラー）。

公開前の検証とエラー対処

previewの使い分け

figma connect preview は、Inspect パネルに出るスニペットを手元で描画します。--inspect はコンポーネントのプロパティとバリアントの一覧だけを出し、--props Variant=Primary は指定した組み合わせ1つを描画し、--all は全組み合わせを描画します。

npx figma connect preview src/components/Button.figma.ts --inspect
npx figma connect preview src/components/Button.figma.ts --props Variant=Primary
npx figma connect preview src/components/Button.figma.ts --unique --output json

--unique は 1.5.3（2026年8月12日）で入ったオプションで、--all と同じ組み合わせを描画しつつ、出力が同じものを1件にまとめて件数を添えます。Disabled のように出力を変えないプロパティが多い部品では、--all よりずっと短くなります。組み合わせの上限は --max-combinations で指定し、既定値も上限も500です。preview は Figma からプロパティ定義を取るので、トークンが必要です。

Code Connect CLIの認証・設定・起動エラー

トークン未設定のエラーは、対象ファイルのパスと Using label "React" まで表示してから出ます。設定は通っているように見えますが、認証の手前で止まっています。ここまで出れば設定ファイルの読み込みには成功していると切り分けられますが、全ファイルを解析できた証拠にはなりません。それを確かめるには npx figma connect parse --exit-on-unreadable-files を使います。2.0.2 からは、通信エラーの表示にもタイムアウトなどの理由が付くようになりました。--verbose を付けるとスタックトレースまで出ます。

CIでexit-on-unreadable-filesを付ける理由

--exit-on-unreadable-files は、解析できないファイルが1つでもあれば異常終了させるフラグです。付けないと読めないファイルを飛ばして成功扱いで終わり、Dev Mode に古いスニペットが残ります。公式も CI での使用を推奨しています。なお 2.0.2 の publish は、公開前の検証で失敗した件数を Figma へ送るようになりました。送信を止めたい場合は環境変数 DO_NOT_TRACK=1 を設定します。

Figma MCPサーバーとの役割分担

Code Connect は「この Figma コンポーネントは実装ではこのコード」という対応づけそのもので、Figma MCP サーバーはその対応づけを含むデザインのデータを AI エージェントへ渡す経路です。対応づけが無い場合、Code Connectによる実装コードへの参照は追加されませんが、エージェントはデザイン情報や手元のコードベースを使って実装できます。MCP サーバーの料金や呼び出し回数の上限はFigma MCPサーバーの料金と上限｜無料枠・プラン別の呼び出し回数・接続手順、キャンバスへの書き込みはuse_figmaとは？Figma MCPでAIがキャンバスに書き込む仕組みと使い方・制限で扱っています。

テンプレートファイルを書く作業自体も、エージェントに任せられます。Figma MCP サーバーに接続したエージェントで figma-code-connect スキルを使い、コンポーネントのURLを渡すと、プロパティ定義の取得、リポジトリ内の該当コンポーネントの特定、.figma.ts の書き出しまで進みます。スキルは IDE 向けの Figma プラグインに同梱されています。チームライブラリに公開済みのコンポーネントでないと対象を特定できない点と、Figma 側のプロパティとコード側の props の対応は人が確かめる必要がある点に注意してください。デザインと実装の対応づけをどこから整えるか迷っている場合は、UI/UXデザインの支援の中で、デザインシステムの棚卸しから相談を受けています。

よくある質問

Figma CLIとCode Connect CLIは別物ですか？

同じものです。@figma/code-connect を入れると figma コマンドが使えるようになり、その connect サブコマンドが Code Connect を操作します。プランアクセストークンの発行画面にある「Figma CLI」タブも、このコマンド用のトークンを指しています。npm には figma-cli など名前の似た第三者製パッケージがありますが、Figma 社のものではありません。

Figma PATの有効期限が切れたらどうなりますか？

publish が認証エラー（403）で失敗します。PAT は最長90日なので、CI で使うなら期限前に作り直して Secrets を差し替えます。Organization 以上なら最長365日の Figma CLI トークンに切り替え、Refresh で更新すれば古い値が24時間使えるので切り替えの隙間ができません。

Professionalプランでも GitHub Actions で自動公開できますか？

できます。ただしプランアクセストークンは発行できないため、PAT を Secrets に入れて使います。また有効なフレームワークは1つなので、React と SwiftUI のように複数の label で公開する構成は組めません。

GitLabやBitbucketのリポジトリでも使えますか？

CLI での publish は使えます。CLI は手元や CI のファイルを読んで Figma に送るだけなので、GitLab CI など GitHub 以外の CI からでも、同じく npm ci の後に npx figma connect publish を実行すれば動きます。Figma 側からリポジトリを接続する Code Connect UI の連携先として案内されているのは GitHub だけです。

SwiftUIやJetpack Composeでもテンプレートファイルへ移行できますか？

できます。テンプレートファイルはフレームワークに依存しない形式なので、SwiftUI や Compose のプロジェクトでも figma connect migrate の対象になります。移行後は xcodeprojPath・sourcePackagesPath・importMapping などの項目を設定ファイルから消してください。1.4.9 以降は、プロジェクト内の Code Connect ファイルがすべてテンプレートなら Swift や Compose のパーサーをビルドしなくなったので、CI の時間も短くなります。

関連記事

• Figma Code Connectの使い方｜UIとCLIの始め方とDev Mode表示・CLI v2移行
• Figma MCPサーバーの料金と上限｜無料枠・プラン別の呼び出し回数・接続手順
• Figma APIの使い方｜APIキー発行・レート制限の実数・Variables REST APIの条件【2026年10月】
• use_figmaとは？Figma MCPでAIがキャンバスに書き込む仕組みと使い方・制限
• Figma Makeの料金・AIクレジットとは？プラン別の上限と消費量・使い方・エクスポートまで解説