docs: clarify github integration repo creation and sync behavior - #11401
docs: clarify github integration repo creation and sync behavior#11401MikeNitsenko wants to merge 1 commit into
Conversation
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
|
Claude finished @MikeNitsenko's task in 2m 9s —— View job Docs review — 1 medium-high, 3 medium, 2 low. Content is accurate and well-sourced; main asks are one heading-nesting fix and one webhook-scope correction.Full review
What's good
Findings
Naming convention
Not applicableSecurity, performance, and testing are all N/A — docs-only change, no code, no new pages, no One thing I could not verifyThe |
github-actions
Bot
added
the
pr:community
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
| ### Creating a new repository | ||
|
|
||
| From the **Connect to GitHub** dialog you can either connect an existing | ||
| repository or choose **Create new repository** to have Cube Cloud create one for | ||
| you. | ||
|
|
||
| <Warning> | ||
|
|
||
| When Cube Cloud creates a repository in a **GitHub organization**, it is created | ||
| through the GitHub App installation. Depending on your organization's settings, | ||
| the person who initiated the creation is **not** automatically added as a | ||
| collaborator, and the new repository may not appear under your personal | ||
| repositories — look for it under the organization's repositories and add the | ||
| required collaborators or teams in GitHub afterwards. | ||
|
|
||
| A newly created repository also starts **empty**. Before a deployment can use a | ||
| project path inside it, the repository must contain a Cube project — that is, a | ||
| `model/` folder (the legacy `schema/` folder is also accepted). Connecting to an | ||
| empty repository, or to a path that has no `model/` folder, fails with a **"data | ||
| model not found"** error. Push an initial data model — or generate one from the | ||
| Cube Cloud UI — before pointing a deployment at it. | ||
|
|
||
| </Warning> | ||
|
|
||
| What happens after connecting depends on the deploy mode: |
There was a problem hiding this comment.
Structure: the "What happens after connecting" list is now orphaned under an H3.
Before this PR, the What happens after connecting depends on the deploy mode: list (line 131) sat directly under ## Deploy with GitHub, which is where it belongs — it describes the outcome of connecting a repository, not of creating one. Inserting ### GitHub App permissions and ### Creating a new repository above it means the list now renders inside the Creating a new repository subsection, so a reader scanning headings will read "in Deploy with Git mode, Cube Cloud will automatically deploy…" as a property of newly-created repositories.
Move the two new H3s below that list (they're detail/edge-case material anyway, so trailing the main flow reads better), or promote the list into its own ### After connecting subsection so it isn't captured by the preceding H3.
| If your data model already lives in a hosted Git provider (GitHub, GitLab, or | ||
| Bitbucket), **connect that repository directly** — see [Deploy with | ||
| GitHub](#deploy-with-github) below, or [import via SSH][ref-import-ssh] for | ||
| GitLab and Bitbucket. You then push only to your own repository and Cube Cloud | ||
| stays in sync automatically through a webhook, with no need to also push to the | ||
| `cubecloud` remote. |
There was a problem hiding this comment.
Accuracy: webhook sync isn't automatic for the SSH path.
The sentence lumps GitLab/Bitbucket in with GitHub and says Cube "stays in sync automatically through a webhook". For the GitHub App path that's true — the app registers the webhook for you (as the new GitHub App permissions section says). For the SSH path it isn't: import-git-repository-via-ssh.mdx:64-74 instructs the user to copy the webhook URL out of the UI and add it to their repository's webhooks themselves. A reader who follows this Tip for GitLab will connect via SSH, never add the webhook, and then find that pushes don't sync — with this page telling them it should be automatic.
Suggest splitting the clause, e.g. "…automatically through a webhook (registered for you with the GitHub App; [configured manually][ref-import-ssh] for GitLab and Bitbucket)".
| <Note> | ||
|
|
||
| Install the Cube Cloud GitHub app on the **organization** that owns the | ||
| repository, and grant it access to that repository (or to all repositories). If | ||
| your organization restricts third-party apps, an **organization owner must | ||
| approve the installation** before the repository will appear in the list. For | ||
| the full list of permissions the app requests, and guidance on creating a new | ||
| repository from Cube Cloud, see [Continuous deployment][ref-continuous-deployment]. | ||
|
|
||
| </Note> |
There was a problem hiding this comment.
The preceding sentence ends "…you should see the following screen in Cube Cloud:" and this <Note> now sits between it and the screenshot, so "the following screen" no longer points at anything adjacent. Move the callout above the paragraph at line 35 (it's a prerequisite — it should be read before clicking Import from a GitHub repository), or below the <div> that holds the image.
Two smaller things while you're here:
- The link target could deep-link to the new subsection:
[ref-continuous-deployment]: /admin/deployment/continuous-deployment#github-app-permissions. - Line 157 still has no trailing newline (pre-existing, but this PR is already touching that line — easy to fix).
| - **Read repository contents** — to clone your data model and pick up new | ||
| commits. | ||
| - **Administer repositories** — to create a repository on your behalf when you | ||
| choose *Create new repository* (see below). |
There was a problem hiding this comment.
Nit: UI labels are bolded everywhere else on this page (Connect to GitHub, Build & Deploy, Generate Git credentials) — including in the section you add right below, which uses **Create new repository**. Use bold here too for consistency.
| choose *Create new repository* (see below). | |
| choose **Create new repository** (see below). |
| ## Keeping your repository in sync | ||
|
|
||
| Once a repository is connected, Cube Cloud is notified of new commits through a | ||
| webhook — it does **not** poll your provider on a timer. In steady state a push | ||
| to a connected branch is picked up within seconds, and the Cube Cloud UI | ||
| reflects build and sync status within about ten seconds. A short (~30 second) | ||
| per-branch cooldown between webhook events means rapid consecutive pushes to the | ||
| same branch may be briefly coalesced. | ||
|
|
||
| The **first connection** behaves differently. When you first connect a | ||
| repository, Cube Cloud performs a one-time full clone of it, registers the | ||
| webhook, and — for a newly provisioned or previously suspended deployment — | ||
| starts the staging, [development mode][ref-dev-mode], and IDE instances from a | ||
| cold state. Because of this, the first time a branch or commit appears in a | ||
| [staging environment][ref-environments-staging], development mode, the IDE, or | ||
| **Cubes & Views** in Explore can take noticeably longer (and longer still for | ||
| large repositories). This is a one-time warm-up: after the initial clone | ||
| completes and the instances are running, later pushes sync within seconds. |
There was a problem hiding this comment.
Two notes on this section:
-
Overlap with the page intro. Lines 20–25 already state that "Non-production branches pushed to GitHub are then auto-synced into Cube Cloud", and lines 131–138 repeat it per deploy mode. This section says it a third time.
docs-mintlify/CLAUDE.mdexplicitly asks for "say it once" / no padding — consider trimming to the two facts that are genuinely new here (webhook-not-polling, and the first-connection cold start) and dropping the restatement. -
The
~30 secondcooldown and the 10-minute suspension are already documented elsewhere (import-git-repository-via-ssh.mdx:109andenvironments.mdx:58) — so the numbers check out, but they're now stated in three places and will drift. Prefer linking ([staging environment][ref-environments-staging]already exists here) over restating the 10-minute figure.
The about ten seconds UI-refresh figure (line 145) is the one claim I can't corroborate anywhere in the docs; consider "within a few seconds" unless that number is something support genuinely quotes.
1 participant
No description provided.