他の導入ガイド(全7件)
ci/cd / 導入ガイド
@ciderjs/clasp-auth
CI/CDで @google/clasp を利用するための認証ブリッジ
npm install -D @ciderjs/clasp-authこのページの内容
@ciderjs/clasp-auth は、Google Apps Script (GAS) プロジェクトを GitHub Actions 上で CI/CD デプロイするための認証情報管理ツールです。ローカル環境で生成された @google/clasp の認証情報を安全に GitHub Secrets へ同期する CLI と、ワークフロー実行時に認証ファイルを一時復元・自動クリーンアップする GitHub Action を提供します。
概要と特徴
@google/clasp を用いた GAS プロジェクトの自動デプロイでは、ローカルで発行した OAuth トークン(~/.clasprc.json)やプロジェクト設定(.clasp.json)を CI 環境へ安全に受け渡す必要があります。@ciderjs/clasp-auth は、JSON の検証・正規化・Base64 エンコードから GitHub CLI (gh) を介した Secret 登録、および GitHub Actions ランナー上でのファイル復元・削除までを一貫して自動化します。
- CLI によるワンストップ Secret 管理: ローカルの
~/.clasprc.jsonと.clasp.jsonを検証・正規化し、Base64 エンコードした状態で対象リポジトリの GitHub Secrets(CLASPRC_JSON,CLASP_JSON)へ一括登録・一覧確認・削除できます。 - GitHub Action による安全な一時復元: ジョブ実行時(Main ステップ)に Secrets から認証ファイルをパーミッション
0600で復元し、ジョブ終了時(Post ステップ)にfs.unlinkSyncで自動削除します。 - 事前フォーマット検証: アップロード前や任意のタイミングで、
~/.clasprc.jsonおよび.clasp.jsonの必須プロパティ(OAuth トークン、クライアント情報、scriptId)が揃っているかを検査できます。 - リポジトリ権限の事前チェック: GitHub CLI を通じて対象リポジトリの存在と実行ユーザーの Push 権限(
permissions.push)を事前に検証し、設定ミスを防止します。
動作要件
- Node.js: ローカル CLI 実行環境(GitHub Action ランタイムは
node24で動作) - GitHub CLI (
gh): インストール済みであり、gh auth loginによって対象リポジトリへの書き込み権限(Push 権限)を持つアカウントで認証済みであること - Google Apps Script CLI (
@google/clasp): インストール済みであり、clasp loginによってホームディレクトリ直下に~/.clasprc.jsonが生成済みであること
インストール
プロジェクトの開発依存関係(devDependencies)としてインストールするか、pnpm dlx / npx で直接実行します。
# pnpm
pnpm add -D @ciderjs/clasp-auth
# npm
npm install -D @ciderjs/clasp-auth
# グローバルインストールする場合
pnpm add -g @ciderjs/clasp-auth
クイックスタート
1. ローカルでの認証状態と設定ファイルの検証
事前に clasp login と gh auth login を完了させた状態で、ローカルの ~/.clasprc.json と .clasp.json の形式を検証します。
pnpm dlx @ciderjs/clasp-auth verify
2. GitHub Secrets への認証情報のアップロード
対象リポジトリ(owner/repo 形式)を指定して、認証情報を GitHub Secrets に登録します。
pnpm dlx @ciderjs/clasp-auth upload owner/repo
3. GitHub Actions ワークフローの作成
リポジトリにワークフロー定義ファイルを作成し、ciderjs/clasp-auth アクションを呼び出して clasp push を実行します。
name: Deploy GAS
on:
push:
branches:
- main
permissions:
contents: read
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: 20
- name: Setup clasp auth
uses: ciderjs/clasp-auth@v0.3.0
with:
clasprc_json: ${{ secrets.CLASPRC_JSON }}
clasp_json: ${{ secrets.CLASP_JSON }}
- name: Install clasp
run: npm install -g @google/clasp
- name: Push to Google Apps Script
run: clasp push
CLI リファレンス
実行コマンド名は clasp-auth です。
コマンド構文
# GitHub Secrets へのアップロード(<repo> は owner/repo 形式で必須)
clasp-auth upload <repo> [options]
# GitHub Secrets からの削除(CLASPRC_JSON, CLASP_JSON)
clasp-auth delete <repo> [options]
# 登録済み clasp 関連 Secrets の一覧表示
clasp-auth list <repo>
# ローカルの .clasprc.json / .clasp.json の構造検証
clasp-auth verify [options]
オプション一覧
| オプション | エイリアス | 型 / 指定値 | デフォルト | 説明 |
|---|---|---|---|---|
--yes |
-y |
boolean |
false |
upload / delete 実行前の対話的な確認プロンプトをスキップします。 |
--project-dir <path> |
-p |
string |
カレントディレクトリ (process.cwd()) |
upload / verify 時に .clasp.json を探索するディレクトリパスを指定します。 |
--version |
-v |
- | - | パッケージのバージョンを表示します。 |
--help |
-h |
- | - | ヘルプ情報を表示します。 |
GitHub Action リファレンス
GitHub Actions ワークフロー内で ciderjs/clasp-auth を呼び出すことで、CLI で登録した GitHub Secrets から認証ファイルとプロジェクト設定ファイルをランナー上に復元できます。
- ランタイム:
node24 - メイン処理:
dist/action/main.mjs - ポスト処理:
dist/action/post.mjs
入力パラメータ (Inputs)
| パラメータ | 必須 | デフォルト | 説明 |
|---|---|---|---|
clasprc_json |
Yes | - | Base64 エンコードされた .clasprc.json の文字列。通常は ${{ secrets.CLASPRC_JSON }} を指定します。 |
clasp_json |
No | "" |
Base64 エンコードされた .clasp.json の文字列。通常は ${{ secrets.CLASP_JSON }} を指定します。 |
ワークフロー設定例
ビルドスクリプト(pnpm run build)と組み合わせた実践的なデプロイワークフローの例です。
name: Deploy to Google Apps Script
on:
push:
tags:
- 'v*'
permissions:
contents: read
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Setup pnpm
uses: pnpm/action-setup@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: 22
cache: 'pnpm'
- name: Install dependencies
run: pnpm install --frozen-lockfile
- name: Build project
run: pnpm run build
- name: Setup clasp auth
uses: ciderjs/clasp-auth@v0.3.0
with:
clasprc_json: ${{ secrets.CLASPRC_JSON }}
clasp_json: ${{ secrets.CLASP_JSON }}
- name: Push to GAS
run: pnpm dlx @google/clasp push -f
API リファレンス
パッケージ内部で定義されている定数、データ構造(型定義)、およびモジュール関数の一覧です。
定数と型定義
export const SECRET_KEY = 'CLASPRC_JSON';
export const CLASP_JSON_SECRET_KEY = 'CLASP_JSON';
// ~/.clasprc.json のデータ構造
export interface ClaspConfig {
token: {
access_token: string;
refresh_token: string;
scope: string;
token_type: string;
expiry_date: number;
};
oauth2ClientSettings: {
clientId: string;
clientSecret: string;
redirectUri: string;
};
}
// .clasp.json のデータ構造
export interface ClaspProjectConfig {
scriptId: string;
rootDir?: string;
projectId?: string;
parentId?: string[];
}
// uploadSecrets 関数のオプション
export interface UploadOptions {
projectDir?: string | undefined;
}
uploadSecrets(repo, options?) ほか (src/uploadSecrets.ts)
| プロパティ / 引数 | 型 | デフォルト | 説明 |
|---|---|---|---|
repo |
string |
- | 対象の GitHub リポジトリ名(owner/repo 形式)。 |
options.projectDir |
string | undefined |
process.cwd() |
.clasp.json を探索するディレクトリパス。 |
checkRepoAccess(repo: string): { exists: boolean; canPush: boolean; error?: string }
gh api repos/<repo>を実行し、リポジトリの存在と Push 権限の有無を返します。404 エラー時はRepository not found、403 エラー時はPermission denied、gh未検出時はgh command missingをerrorに格納します。validateRepoAccess(repo: string): boolean
checkRepoAccessを呼び出し、リポジトリが存在しない場合または Push 権限がない場合に標準エラー出力へメッセージを出力してfalseを返します。uploadSecrets(repo: string, options?: UploadOptions): void
.clasprc.jsonと.clasp.jsonを読み込み、正規化・Base64 エンコードを行って GitHub Secrets に登録します。deleteSecrets(repo: string): void
指定リポジトリからCLASPRC_JSONとCLASP_JSONを削除します。
バリデーション・ユーティリティ関数 (src/validation.ts / src/utils.ts)
validateClaspConfig(content: string): boolean
JSON 文字列をパースし、token.access_token、token.refresh_token、oauth2ClientSettings.clientId、oauth2ClientSettings.clientSecretがすべて存在するかを検証します。validateClaspProjectConfig(content: string): boolean
JSON 文字列をパースし、scriptIdが存在するかを検証します。getClasprcPath(): string
実行プラットフォームがwin32の場合はprocess.env.USERPROFILE、それ以外の場合はprocess.env.HOMEを基点として.clasprc.jsonのパスを返します。getClaspJsonPath(projectDir?: string): string
projectDir(未指定時はprocess.cwd())直下の.clasp.jsonのパスを返します。encodeToBase64(content: string): string/decodeFromBase64(encoded: string): string
UTF-8 文字列と Base64 文字列の相互変換を行います。runGhCommand(args: string[], input?: string): string
node:child_processのspawnSyncを使用してghコマンドを実行し、標準出力をトリムして返します。inputが指定された場合は標準入力として渡します。ghコマンドが存在しない場合(ENOENT)や終了ステータスが0以外の場合は例外をスローします。
アーキテクチャと動作仕様
CLI コマンドの動作仕様
upload <repo>:gh api repos/<owner/repo>を実行し、リポジトリの存在および実行ユーザーのpermissions.push権限を検証します(失敗時は終了コード1)。--yes未指定時は実行確認プロンプトを表示します(拒否時は終了コード0)。- ホームディレクトリ(Linux/macOS は
HOME、Windows はUSERPROFILE)直下の.clasprc.jsonを読み込みます(未存在時は終了コード1)。 .clasprc.jsonをJSON.parseおよびJSON.stringifyで正規化した後、UTF-8 から Base64 文字列へエンコードし、gh secret set CLASPRC_JSON -R <repo>で登録します。- 指定プロジェクトディレクトリ(未指定時は
process.cwd())に.clasp.jsonが存在する場合、同様に正規化・Base64 エンコードを行い、gh secret set CLASP_JSON -R <repo>で登録します。存在しない場合はスキップします。
delete <repo>:- リポジトリの存在と Push 権限を検証し、
--yes未指定時は削除確認プロンプトを表示します。 gh secret delete CLASPRC_JSON -R <repo>とgh secret delete CLASP_JSON -R <repo>を順次実行します。未登録などの理由で削除に失敗した場合は標準エラー出力に警告を表示し、処理を継続します。
- リポジトリの存在と Push 権限を検証し、
list <repo>:- リポジトリの存在と Push 権限を検証します。
gh secret list -R <repo> --json nameを実行し、取得した一覧からCLASPRC_JSONとCLASP_JSONを抽出して出力します。エラー発生時に環境変数DEBUGが設定されている場合はエラー詳細を標準エラー出力に表示します。
verify:~/.clasprc.jsonの存在と必須プロパティ(token.access_token,token.refresh_token,oauth2ClientSettings.clientId,oauth2ClientSettings.clientSecret)を検証します(失敗時は終了コード1)。.clasp.jsonが存在する場合は必須プロパティscriptIdを検証します(存在しない場合はスキップして正常終了、検証失敗時は終了コード1)。
GitHub Action のライフサイクル
- Main ステップ(ジョブ実行時):
clasprc_json入力値を Base64 デコードし、ランナーのホームディレクトリ(os.homedir())直下の.clasprc.jsonに UTF-8 で書き出します。- 書き出した
.clasprc.jsonのパーミッションを0600(所有者のみ読み書き可能)に設定し、ファイルパスを Action の State(clasprc_path)に保存します。 clasp_json入力値が指定されている場合、Base64 デコードした内容を環境変数GITHUB_WORKSPACE(未設定時はprocess.cwd())直下の.clasp.jsonに UTF-8 で書き出し、パーミッションを0600に設定して State(clasp_json_path)に保存します。
- Post ステップ(ジョブ終了時):
- ジョブ完了後、Action の State から
clasprc_pathとclasp_json_pathを取得します。 - 各ファイルが存在する場合、
fs.unlinkSyncにより自動削除します。ワークフロー定義側でクリーンアップ用のステップを手動記述する必要はありません。
- ジョブ完了後、Action の State から
制限事項と注意点
- ファイルのアクセス制御とログ出力の抑止: GitHub Action によって復元された
.clasprc.jsonおよび.clasp.jsonはパーミッション0600で保護されジョブ終了時に削除されますが、CI ジョブ内でこれらのファイル内容を標準出力に表示するコマンド(cat等)を実行しないでください。 - リポジトリの公開範囲と権限設定: 登録される Secret には実行ユーザーの Google アカウントの OAuth トークンが含まれます。アップロード先のリポジトリを誤らないよう注意し、ワークフローの
permissionsは必要最小限(contents: readなど)に設定してください。 - トークンのローテーション: OAuth トークンの失効やセキュリティ維持のため、定期的にローカルで
clasp loginとclasp-auth verifyを実行し、clasp-auth uploadで GitHub Secrets を更新してください。
トラブルシューティング
| エラーメッセージ | 原因 | 対処方法 |
|---|---|---|
GitHub CLI (gh) not found. Please install it first. |
GitHub CLI (gh) が未インストール、または PATH が通っていません。 |
GitHub CLI をインストールし、gh auth login を実行してください。 |
No .clasprc.json found. Run clasp login first. |
ホームディレクトリ直下に .clasprc.json が存在しません。 |
clasp login を実行して認証を行い、OS の環境変数(HOME または USERPROFILE)を確認してください。 |
Invalid .clasprc.json format |
.clasprc.json が破損しているか、必須フィールド(access_token, refresh_token, clientId, clientSecret)が不足しています。 |
clasp login を再実行して .clasprc.json を再生成してください。 |
Invalid .clasp.json format (scriptId is required) |
.clasp.json に scriptId プロパティが含まれていません。 |
clasp create または clasp clone を実行して正しいプロジェクト設定ファイルを生成してください。 |
リポジトリ "<repo>" は存在しません。 |
指定したリポジトリ名が誤っているか、プライベートリポジトリへのアクセス権がありません。 | リポジトリ名が owner/repo 形式になっているか、および gh auth status で認証アカウントを確認してください。 |
リポジトリ "<repo>" に対する編集権限がありません。 |
認証中の GitHub アカウントに対象リポジトリの Push 権限がありません。 | リポジトリの Collaborators または Organization の権限設定を確認してください。 |
ライセンス
MIT License