Conversation
Deliverables 3, 4 and 5 of the Apps GA docs review, text first (screenshots follow the 25 Sep UI freeze): - What are Keboola apps: a "Two ways to run an app" section that explains the managed-repository-with-Kai path against your-own-repository, with a comparison table. Its anchor is the target for the "learn more" link the Builder will show on non-managed-git apps (AJDA-3319). - New page Operate and update an app: reading the state, shipping a change on either path, changing settings and why a redeploy is needed, sleep vs stop, the encrypted secret value, versions, copy/automate/delete. - New page Troubleshooting: where the evidence is (job log, Terminal Logs, kbagent runs/logs, Kai), start failures led by the missing keboola-config folder (AJDA-3334), runtime misbehaviour, sign-in, sleeping. - Overview links the two-paths section; both new pages sit under Run & share in the nav. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Seen on a real app in project 264 while cleaning up after the OIDC run: the menu reads Suspend app, Copy app, Automate, Debug mode, Delete app, and suspending asks for confirmation. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Both agents ran over the three new pages. Three things they found were wrong rather than unclear: - The cipher prefix KBC::ProjectSecureGKMS:: is GCP-only. Name the common stem and link extend/encryption, so a reader on AWS or Azure can still tell the save worked. - "Every app runs from a Git repository" is false for Streamlit, which the same page keeps in scope four lines earlier. Say so. - A Keboola-managed repository does not require Kai: kbagent data-app create --use-managed-git-repo provisions the same repo empty. The table's "Who writes the code" row had ruled that combination out. The rest were reachability and accuracy: - Two ways to run an app now answers "why is my builder missing" in its first two lines, because that is the question AJDA-3319 will send readers here with, and says the choice is made at creation. - validate-repo is printed with its required --git-repo, and the contract links carry the app-building skill's reference alongside build-locally, which only gains the contract when keboola#1128 lands. - Redeploy no longer claims a gapless swap; the MCP server says the app may report stopped while it restarts. - Versions gains the way back: an app is a component configuration, so rollback works, and a redeploy puts the old settings in service. - Dropped the unsourced App Info "owner" field and the unverified suspend confirmation; settled the backend-size contradiction (wizard, not page); added the Storage Access failure row, the GitHub/GitLab/ JumpCloud sign-in pointer, and terminal equivalents for each task. - Operate and Troubleshooting were orphans: publish-and-share now points at them, as do index and the end of getting-started. - The deploy wizard asks three things, not two (seen live 22.09), so getting-started says three. Its screenshot still shows two and needs reshooting after the UI freeze. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The re-check caught three things I introduced yesterday and today: - "Every task here can also be done from a terminal with kbagent" is false, and the same commit added the counterexample. There is no rollback, copy, debug-mode or draft command in the CLI reference. Say which tasks have a terminal equivalent and which don't. - App Info does have an owner field. The committed screenshot shows Backend Version, Backend Size, Auto Sleep, Last Change, Owner, App ID. Restored, with Last Change. - Suspend app isn't in the ⋯ menu screenshot, which shows a stopped app. The menu is state-dependent, so say that rather than propagating a five-item list onto a page whose picture shows four. And three that were already wrong on main: - The deploy wizard screenshot has shown three fields all along. Four places described two. getting-started's alt text, publish-and-share and reference now match the picture, so nothing needs reshooting here. - reference.md's App actions listed five of the eight actions, in casing the UI doesn't use, and claimed a suspended app's URL is no longer available while the CLI says stop preserves it. Rewritten to the current labels, with the contested URL claim dropped from both pages rather than asserted on one. - The Storage Access row needed the project-level feature toggle, which comes before the per-app setting. Also dropped an unsupported generalization about GitHub, GitLab and JumpCloud sign-in failures, replaced with the restriction fields each provider actually has. JumpCloud has only allowed roles, so the original sentence didn't even fit the provider it was attached to. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
Someone is attempting to deploy a commit to the Keboola Engineering Team on Vercel. A member of the Team first needs to authorize it. |
Iamfle4ka
added
the
apps-ga
Collaborator
Author
|
Superseded by #1139, which carries this branch in full. Verified the same way: this branch's tip The dependency travels with the content: #1128 still merges first. Three links in these pages promise the Branch |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Three of the eight deliverables on AJDA-3380 have no page to land on today.
Deliverable 4 asks for managed git and an external repository to be told apart. The section never uses the words: it splits by tool ("With Kai" / "Locally") and leaves the repository question implicit. AJDA-3319 is about to ship a line in the Builder reading "Kai builder and live preview need Keboola managed git — learn more", and that link needs somewhere to land.
Deliverable 3 asks how you edit and operate an app you already have. That is spread across the reference and the publish page today, so nobody owns it.
Deliverable 5 asks for the failure scenarios. AJDA-3334 measured a missing
keboola-config/folder behind 73 of 201 startup failures in a week on customer stacks, and the docs say nothing about it.What changes
what-are-apps.mdgains Two ways to run an app, anchored at#two-ways-to-run-an-app. It opens by answering the question the UI link will send people here with, then compares the two paths in prose and a table. It replaces a short "Where Kai fits" section; both of that section's points survive.operate.mdis new: read the app's state, ship a code change on either path, change settings, sleep versus suspend, rotate a secret, roll a configuration back, copy, automate, delete. Every task also has itskbagentequivalent.troubleshooting.mdis new: where the evidence is, then two symptom tables (won't start, misbehaves), sign-in problems and sleeping.index.md,getting-started.mdandpublish-and-share.mdgain pointers, and the Next chain runs through the new pages instead of jumping over them._data/navigation.ymland the generated sidebar put both pages under Run & share.Depends on #1128
Three links here promise a repository layout contract: two in the troubleshooting table and one in the two-paths section. On
main,/data-apps/build-locally/says nothing aboutkeboola-config, nginx, supervisord orsetup.sh, so those links resolve and deliver nothing. #1128 is what puts the contract there. This PR should merge after it. Each of those links also names the app-building skill'sreferences/python-js-apps.md, so a reader is not stranded in the meantime.Verification
npm run buildclean, judged by its exit code.node scripts/audit-phase2.mjs: 75 issues, unchanged from the branch point, none on these pages.node scripts/check-cli-reference.mjs: 0 findings.KBC::ProjectSecureGKMS::is the GCP cipher prefix only. AWS and Azure differ, and the three are not interchangeable, so a reader outside GCP had no way to tell whether saving a secret had worked. (The same sentence was in AJDA-3380: fix the Google OIDC tab after the usability test #1138 and is fixed there too.)kbagent data-app create --use-managed-git-repoprovisions the same repository empty, so the table's "Who writes the code" row had ruled out a combination that exists.validate-repois printed with its required--git-repo; redeploy no longer claims a gapless swap, because the MCP server says an app may report stopped while it restarts; the Versions section gains the way back, since an app is an ordinary component configuration and rollback works on it; the unsourced App Info "owner" field and the unverified suspend confirmation are gone; a Storage Access failure row and a GitHub / GitLab / JumpCloud sign-in pointer are in.A second, narrow fact-check pass then ran over the fixes themselves, and caught three things the first round had introduced: a blanket claim that every task on
operate.mdhas akbagentequivalent, which the page's own rollback section disproves; a removed App Info "owner" field that the committed screenshot shows is real; and a five-item ⋯ menu propagated onto a page whose screenshot shows four, because the menu is state-dependent. It also foundreference.mdlisting five of the eight app actions in casing the UI doesn't use, and a straight contradiction about whether a suspended app keeps its URL, which the reference and the CLI answer differently. That claim is now on neither page rather than asserted on one; it's worth an owner ruling.Known gaps
App must have keboola-config/nginx/ directoryandfatal: Authentication failed, come from reports rather than from a log I produced. The repository that emits the first one is private.#two-ways-to-run-an-appanchor needs agreeing with @michalsevcik before keboola/ui#9001 merges, since that PR will link to it.Part of AJDA-3380, deliverables 3, 4 and 5.
🤖 Generated with Claude Code