keboola-git

面向数据应用的 Keboola 托管 Git（Forgejo）

Keboola Python-JS 数据应用可以将源代码托管在 Keboola 托管的 Git 仓库（Forgejo） 中，而不是 GitHub。本技能提供相关背景，帮助你通过 kbagent CLI 访问这些仓库：创建仓库、生成推送凭据、使用原始 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 操作都应在用户的项目根目录或在用户当前工作目录下创建的临时克隆目录中运行——绝不能在此技能/插件目录中运行。

• 在用户当前工作目录下的 ./.keboola-git-work/<app>/ 中执行克隆/复制操作。将 .keboola-git-work/ 添加到项目的 .gitignore，以免提交临时克隆。
• 对现有仓库执行任何原地 Git 操作之前，先验证它是一个工作树：git rev-parse --is-inside-work-tree。
• 绝不要对插件安装目录运行 Git 命令。

前置条件

1. 已安装 kbagent 且位于 PATH 中（kbagent --version）。使用 /plugin install kbagent@keboola-claude-kit 从此市场安装 kbagent 插件，然后运行 /kbagent:setup 安装 CLI。用法：kbagent:kbagent 技能。
2. 已在 kbagent 中注册项目（每个项目只需注册一次）：

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

3. 已在每个 shell 会话中导出一次对话 ID：

   export KBAGENT_CONVERSATION_ID=$(uuidgen)
   

4. 始终为工具调用传入 --json，以便可靠解析 configuration_id、repo_url、git_clone_url。

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。 始终针对生产配置生成凭据。草稿没有自己的仓库。

• 密钥只显示一次。可以随时生成新密钥——生成成本低，也可通过轮换撤销。
• 仅将其保存在 shell 变量中。 绝不要提交、绝不要用 echo 将其写入文件，也绝不要将其粘贴到日志或消息中。将其读入变量并引用 "$URL"：

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

3. 克隆 / 推送模式（原始 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 会以 HTTP 413 拒绝超过 约 15MB 的推送。单个超过上限的文件无法拆分——不得跟踪这类文件。

仅推送源代码。 将构建产物提交到仓库的项目（例如 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 会发送推送引用可到达的每个对象——因此，即使第 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。可通过以下两种方式处理：

   • 全新的托管仓库（最常见情况）： 推送一个全新的干净提交，让旧 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 状态 + 后端进程已启动。 后端的数据错误——例如 python-api 在启动加载数据时因 Storage 404 Not Found 而陷入崩溃循环——表示应用正在运行，并在空项目中查找不存在的表。这属于数据状况，不是 git / 部署失败。

注意事项

完整的命令目录、413 / 部署时构建方案和注意事项表见 references/managed-git.md。