keboola-git

Data Apps 向け Keboola 管理 Git（Forgejo）

Keboola の python-js データアプリでは、GitHub ではなく Keboola 管理の Git リポジトリ（Forgejo）にソースをホストできます。このスキルでは、kbagent CLI を使ってこれらのリポジトリにアクセスする方法を説明します。リポジトリのプロビジョニング、プッシュ用認証情報の発行、raw git によるソースのプッシュ、デプロイを行います。kbagent にはリポジトリのコピーを補助する機能はありません。git clone／git remote add／git push は自分で実行します。

このスキルでできること／対象外

次の場合に使用します： python-js データアプリの管理対象 Forgejo リポジトリを読み書きする場合、アプリのソースを GitHub と Keboola git の間で移行する場合、管理対象リポジトリからソースをプッシュしてデプロイする場合。

対象外： keboola-config/ の内容（nginx、supervisord、setup.sh）の作成。これは dataapp-developer:dataapp-development スキルで扱います。このスキルでは Streamlit アプリの開発も扱います。このスキルは、アプリのソースがすでにどこかにあることを前提とし、Keboola に取り込んでデプロイするための git の操作 を扱います。

作業ディレクトリのコンテキスト

すべての git および kbagent 操作は、ユーザーのプロジェクトルートまたはユーザーの CWD 配下に作成した一時クローンから実行します。このスキル／プラグインのディレクトリからは実行しないでください。

• クローンやコピーの作業は、ユーザーの CWD 配下にある ./.keboola-git-work/<app>/ で行います。一時クローンがコミットされないよう、プロジェクトの .gitignore に .keboola-git-work/ を追加してください。
• 既存のリポジトリでその場で git 操作を行う前に、git rev-parse --is-inside-work-tree を実行して、ワークツリーであることを確認してください。
• プラグインのインストールディレクトリに対して git コマンドを実行しないでください。

前提条件

1. kbagent がインストール済みで、PATH に含まれていること（kbagent --version）。このマーケットプレイスから kbagent プラグインを /plugin install kbagent@keboola-claude-kit でインストールし、次に /kbagent:setup を実行して CLI をインストールしてください。使い方については、kbagent:kbagent スキルを参照してください。
2. プロジェクトを kbagent に登録済みであること（プロジェクトごとに一度だけ）：

   kbagent --json project add --project <alias> --url <stack-url> --token-env KBC_TOKEN
   

3. 会話 ID をシェルセッションごとに一度だけエクスポートすること：

   export KBAGENT_CONVERSATION_ID=$(uuidgen)
   

4. configuration_id、repo_url、git_clone_url を確実に解析できるよう、ツール呼び出しには必ず --json を渡してください。

1. 管理対象リポジトリにアクセスする

既存アプリ — リポジトリと設定を確認します：

kbagent --json tool call get_data_apps --project <alias> --input '{}'

configuration_id、data_app_id、repo_url （https://git.<stack>/keboola/app-<data_app_id>.git）を控えてください。

本番アプリとリポジトリを作成 — 上記の get_data_apps が python-js アプリを返さなかった場合のみ：

kbagent --json tool call modify_python_js_data_app --project <alias> \
  --input '{"name":"<Display Name>","slug":"<slug>","description":"<desc>"}'

configuration_id、data_app_id、repo_url を返します。

configuration_id が空の場合、実行するたびに新規作成されます。 新しい本番アプリと新しい管理対象リポジトリの両方が作成されます。作成後にそのリポジトリを既存アプリに紐付けることはできないため、意図せず作成した本番アプリは、意図せず作成したリポジトリになります。作成前に確認してください。また、コンテキストですでにアプリが特定されている場合（開いていたページやリクエスト内の ID など）は、その ID を使用してください。

以下の手順は、本番アプリの main を対象とします。プレビュー用にブランチ上で変更を準備する場合は、ドラフトの手順（parent_configuration_id、開発モードでの deploy_data_app）を plugins/dataapp-developer/skills/dataapp-development/references/python-js-prod-and-drafts.md で確認してください。

2. プッシュ用認証情報を発行する（一度だけ使用するシークレット）

kbagent --json tool call create_python_js_data_app_git_credential --project <alias> \
  --input '{"configuration_id":"<cfg>"}'

git_clone_url = https://kai:<secret>@git.<stack>/keboola/app-<data_app_id>.git が返されます。 必ず本番の設定に対して発行してください。ドラフトには専用のリポジトリがありません。

• シークレットは一度だけ表示されます。いつでも新しいものを発行できます。発行コストは低く、ローテーションで無効化できます。
• シェル変数のみに保存してください。 コミットしたり、ファイルに echo で書き込んだり、ログやメッセージに貼り付けたりしないでください。変数に読み込み、"$URL" を参照してください：

  URL='https://kai:<secret>@git.<stack>/keboola/app-<id>.git'
  

3. クローン／プッシュの手順（raw git）

mkdir -p ./.keboola-git-work && cd ./.keboola-git-work
git clone --single-branch --branch <branch> <source-repo> app && cd app
git remote add keboola "$URL"
git push keboola HEAD:main

• リポジトリのデフォルトブランチは削除できませんが、それ以外のブランチは削除できます。空のリポジトリに最初にプッシュされたブランチがデフォルトになるため、最初に main をプッシュしてください。
• 共有／管理対象ブランチには、強制プッシュしないでください。サーバーはそれをブロックしません。
• クローンを再利用しますか？そこから読み込んだりプッシュしたりする前に、dataapp-developer:dataapp-development スキルの既存クローンに関するリファレンスを確認してください。

4. 15MB / HTTP 413 の上限とデプロイ時のビルド（重大）

Forgejo では 約15MB を超えるプッシュは HTTP 413 で拒否されます。上限を超える単一ファイルは分割できないため、追跡してはいけません。

ソースのみをプッシュします。 ビルド成果物をコミットしているリポジトリ（例：frontend/.next 約55MB。15.3MBの macOS 用 sharp バイナリが含まれていることもよくありますが、これは Linux ランタイムでは使えないバイナリです）は、ビルドをデプロイ時に行うよう変更する必要があります。

1. プッシュ前にサイズを確認します。

   find . -size +15M -not -path '*/.git/*'
   

2. ビルドディレクトリが追跡されている場合は、追跡を停止して gitignore に追加します。

   git rm -r --cached frontend/.next
   printf '%s\n' 'frontend/.next/' 'node_modules/' >> .gitignore
   

3. ビルドを keboola-config/setup.sh に移し、デプロイ時に Linux コンテナで実行されるようにします。

   # in keboola-config/setup.sh, run from the app's frontend dir:
   cd frontend && npm ci && npm run build
   # Next.js output:'standalone' does NOT copy static assets — copy them so the
   # standalone server.js can serve them. The destination MIRRORS the path from the
   # Next.js workspace root, so it differs by layout — detect where server.js landed:
   #   find .next/standalone -maxdepth 3 -name server.js
   # Single-package repo (workspace root == frontend/, server.js at .next/standalone/server.js):
   cp -r .next/static .next/standalone/.next/static
   cp -r public       .next/standalone/public
   # Monorepo (workspace root above frontend/, server.js at .next/standalone/frontend/server.js):
   #   cp -r .next/static .next/standalone/frontend/.next/static
   #   cp -r public       .next/standalone/frontend/public
   

   setup.sh／nginx／supervisord の具体的な設定については、dataapp-developer:dataapp-development スキルを参照してください。

4. ソースのみのツリーをコミットしてから、サイズチェックを再実行します（追跡対象ファイルが15MBを超えていないこと）。

5. 作業ツリーだけでなく、git の履歴も確認します（重大）。 git push は、プッシュ対象の ref から到達可能なすべてのオブジェクトを送信します。そのため、以前のコミットでビルドをコミットしていた場合、手順2で HEAD から削除しても、その古いオブジェクトはプッシュされ、引き続き413エラーになります。find によるチェックでは作業ツリーしか確認できません。到達可能な blob を確認します。

   git rev-list --objects HEAD \
     | git cat-file --batch-check='%(objecttype) %(objectsize) %(rest)' \
     | awk '$1=="blob" && $2>15000000 {print $2, $3}'
   

   何か表示された場合、上限を超える blob が履歴に含まれています。対処方法は2つあります。

   • 新しいマネージドリポジトリの場合（一般的なケース）： 古い blob が到達可能にならないよう、クリーンな単一のコミットをプッシュします。

     git checkout --orphan clean-main && git add -A && git commit -m "Source-only (build at deploy)"
     git push keboola clean-main:main
     

   • 履歴を保持する必要がある場合： git filter-repo（または BFG）で blob を削除してからプッシュします。

プッシュが引き続き413エラーになる場合は、両方のチェック（作業ツリーと履歴）を再実行し、該当するファイルを報告してください。そのファイルを外部化する方法はユーザーが決める必要があります（分割はできません）。

5. デプロイと検証

kbagent --json tool call deploy_data_app --project <alias> \
  --input '{"action":"deploy","configuration_id":"<cfg>"}'

ログで検証してください。ログが信頼できる唯一の判断材料です（npm ci と next build でビルドに約90秒以上、setup_sh に合計約2分かかることがあります）。

kbagent --allow-env-manage-token data-app logs --project <alias> --app-id <data_app_id> --lines 300

順に次のログを確認します。✓ Compiled successfully と Generating static pages（next build の完了）、Completed: setup_sh（静的アセットの cp が成功。パスが誤っていれば set -e によってここで中断されます）、続いて success: node-frontend entered RUNNING state と ✓ Ready in …ms（スタンドアロンサーバーが :3000 で起動）です。Python サービスでは success: python-api entered RUNNING state が表示されます。ログの表示範囲の大半が、どちらかのサービスの再起動ループで占められている場合は、--lines の値を増やして、もう一方のサービスの起動時ログを確認してください。

HTTP プローブでフロントエンドを確認しないでください。 認証なしの GET / では Keboola プラットフォームのログイン画面が返されます（HTTP 200、<title>Login</title>、_next/static への参照なし）。これはコンテナの手前にあるプラットフォームの認証プロキシであり、アプリではありません。また、POST / はアプリの状態にかかわらず、nginx の location = / ヘルスチェックルールから200を返します。ビルド済みのフロントエンドが配信されていることを確認するには、ログの node-frontend entered RUNNING と Ready in を確認してください（必要に応じて、アプリのパスワードで認証したうえで、HTML に /_next/static/… への参照があることを確認します）。

必要に応じて、アプリのパスワードを取得／シークレットを設定して再デプロイします。

kbagent --json --allow-env-manage-token data-app password --project <alias> --app-id <data_app_id>
kbagent --allow-env-manage-token data-app secrets-set --project <alias> --app-id <data_app_id> '#KEY=VAL'

成功の条件は、Keboola git にリポジトリがあり、アプリがデプロイされ、コンテナがビルドされ、node-frontend が RUNNING になり、バックエンドプロセスが起動することです。 バックエンドのデータエラー（例：起動時のデータ読み込みで Storage が 404 Not Found を返し、python-api がクラッシュループする場合）は、アプリが稼働しており、空のプロジェクトに存在しないテーブルを探していることを意味します。これはデータの状態であり、git／デプロイの失敗ではありません。

注意点

コマンドの全一覧、413エラー／デプロイ時のビルド手順、注意点の表は references/managed-git.md にあります。