他の導入ガイド(全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 で直接実行します。

.sh
# 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 の形式を検証します。

.sh
pnpm dlx @ciderjs/clasp-auth verify

2. GitHub Secrets への認証情報のアップロード

対象リポジトリ(owner/repo 形式)を指定して、認証情報を GitHub Secrets に登録します。

.sh
pnpm dlx @ciderjs/clasp-auth upload owner/repo

3. GitHub Actions ワークフローの作成

リポジトリにワークフロー定義ファイルを作成し、ciderjs/clasp-auth アクションを呼び出して clasp push を実行します。

.github/workflows/deploy.yml
.yml
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 です。

コマンド構文

.sh
# 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)と組み合わせた実践的なデプロイワークフローの例です。

.github/workflows/appsscript.yml
.yml
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 リファレンス

パッケージ内部で定義されている定数、データ構造(型定義)、およびモジュール関数の一覧です。

定数と型定義

src/types.ts
.ts
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>:
    1. gh api repos/<owner/repo> を実行し、リポジトリの存在および実行ユーザーの permissions.push 権限を検証します(失敗時は終了コード 1)。
    2. --yes 未指定時は実行確認プロンプトを表示します(拒否時は終了コード 0)。
    3. ホームディレクトリ(Linux/macOS は HOME、Windows は USERPROFILE)直下の .clasprc.json を読み込みます(未存在時は終了コード 1)。
    4. .clasprc.json を JSON.parse および JSON.stringify で正規化した後、UTF-8 から Base64 文字列へエンコードし、gh secret set CLASPRC_JSON -R <repo> で登録します。
    5. 指定プロジェクトディレクトリ(未指定時は process.cwd())に .clasp.json が存在する場合、同様に正規化・Base64 エンコードを行い、gh secret set CLASP_JSON -R <repo> で登録します。存在しない場合はスキップします。
  • delete <repo>:
    1. リポジトリの存在と Push 権限を検証し、--yes 未指定時は削除確認プロンプトを表示します。
    2. gh secret delete CLASPRC_JSON -R <repo> と gh secret delete CLASP_JSON -R <repo> を順次実行します。未登録などの理由で削除に失敗した場合は標準エラー出力に警告を表示し、処理を継続します。
  • list <repo>:
    1. リポジトリの存在と Push 権限を検証します。
    2. gh secret list -R <repo> --json name を実行し、取得した一覧から CLASPRC_JSON と CLASP_JSON を抽出して出力します。エラー発生時に環境変数 DEBUG が設定されている場合はエラー詳細を標準エラー出力に表示します。
  • verify:
    1. ~/.clasprc.json の存在と必須プロパティ(token.access_token, token.refresh_token, oauth2ClientSettings.clientId, oauth2ClientSettings.clientSecret)を検証します(失敗時は終了コード 1)。
    2. .clasp.json が存在する場合は必須プロパティ scriptId を検証します(存在しない場合はスキップして正常終了、検証失敗時は終了コード 1)。

GitHub Action のライフサイクル

  • Main ステップ(ジョブ実行時):
    1. clasprc_json 入力値を Base64 デコードし、ランナーのホームディレクトリ(os.homedir())直下の .clasprc.json に UTF-8 で書き出します。
    2. 書き出した .clasprc.json のパーミッションを 0600(所有者のみ読み書き可能)に設定し、ファイルパスを Action の State(clasprc_path)に保存します。
    3. clasp_json 入力値が指定されている場合、Base64 デコードした内容を環境変数 GITHUB_WORKSPACE(未設定時は process.cwd())直下の .clasp.json に UTF-8 で書き出し、パーミッションを 0600 に設定して State(clasp_json_path)に保存します。
  • Post ステップ(ジョブ終了時):
    1. ジョブ完了後、Action の State から clasprc_path と clasp_json_path を取得します。
    2. 各ファイルが存在する場合、fs.unlinkSync により自動削除します。ワークフロー定義側でクリーンアップ用のステップを手動記述する必要はありません。

制限事項と注意点

  • ファイルのアクセス制御とログ出力の抑止: 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