Docs: own and sync ClickHouse documentation - #958
Open
Blargian wants to merge 2 commits into
Open
Conversation
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
| @@ -0,0 +1,50 @@ | |||
| name: 'Verify Docs' | |||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - name: Checkout docs source | ||
| uses: actions/checkout@v5 |
|
|
||
| - name: Generate token for target repo | ||
| id: app-token | ||
| uses: actions/create-github-app-token@v3 |
| image: clickhouse/docs-builder | ||
| steps: | ||
| - name: Checkout docs source | ||
| uses: actions/checkout@v5 |
Blargian
changed the title
Blargian
changed the title
Contributor
There was a problem hiding this comment.
Pull request overview
This PR makes ClickHouse/clickhouse-js the source of truth for the public “JavaScript client” ClickHouse documentation by adding the canonical MDX page to this repo and introducing CI/workflows to validate and one-way sync that page into ClickHouse/ClickHouse.
Changes:
- Added the ClickHouse JavaScript client documentation page under
docs/clickhouse-docs/index.mdx. - Added a Mintlify-scoped verification workflow for PRs/pushes touching the docs slice.
- Added a cross-repo sync workflow that opens/refreshes a PR in
ClickHouse/ClickHouseon release, manual dispatch, or a merged PR with async-docslabel.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
| docs/clickhouse-docs/index.mdx | Adds the canonical JS client documentation content to be published via the aggregator. |
| .github/workflows/docs_verify.yml | Runs Mintlify validation checks for the docs slice using the upstream check driver. |
| .github/workflows/docs_sync.yml | Automates syncing the canonical docs into ClickHouse/ClickHouse via a bot PR. |
| | **session_id**?: string | Optional ClickHouse Session ID to send with every request. | - | - | | ||
| | **keep_alive**?: `{ **enabled**?: boolean }` | Enabled by default in both Node.js and Web versions. | - | - | | ||
| | **http_headers**?: `Record<string, string>` | Additional HTTP headers for outgoing ClickHouse requests. | - | [Reverse proxy with authentication docs](/integrations/language-clients/js#reverse-proxy-with-authentication) | | ||
| | **roles**?: string \| string[] | ClickHouse role names to attach to the outgoing requests. | - | [Using roles with the HTTP interface](/concepts/features/interfaces/http#setting-role-with-query-parameters) | |
|
|
||
| ### Query ID {#query-id} | ||
|
|
||
| Every method that sends a query or a statement (`command`, `exec`, `insert`, `select`) will provide `query_id` in the result. This unique identifier is assigned by the client per query, and might be useful to fetch the data from `system.query_log`, |
Comment on lines
+255
to
+258
| // credentials override; if not specified, the client's credentials will be used. | ||
| auth?: { username: string, password: string } | ||
| // A specific list of roles to use for this query. Overrides the roles set in the client configuration. | ||
| role?: string | Array<string> |
Comment on lines
+26
to
+28
| - name: Checkout docs source | ||
| uses: actions/checkout@v5 | ||
|
|
Comment on lines
+115
to
+121
| - name: Checkout docs source | ||
| uses: actions/checkout@v5 | ||
| with: | ||
| # On a release, take the docs as of the released tag; otherwise take | ||
| # the default checkout (post-merge default branch / dispatched ref). | ||
| ref: ${{ github.event_name == 'release' && github.event.release.tag_name || '' }} | ||
|
|
Comment on lines
+129
to
+132
| - name: Generate token for target repo | ||
| id: app-token | ||
| uses: actions/create-github-app-token@v3 | ||
| with: |
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.
Comments suppressed due to low confidence (3)
.github/workflows/docs_verify.yml:28
- This repo pins GitHub Actions to immutable commit SHAs elsewhere (e.g. tests workflows). Using
actions/checkout@v5is a mutable tag and breaks that supply-chain hardening.
- name: Checkout docs source
uses: actions/checkout@v5
.github/workflows/docs_sync.yml:120
- This repo pins GitHub Actions to immutable commit SHAs elsewhere (e.g.
.github/workflows/tests-node.yml). Usingactions/checkout@v5is a mutable tag and weakens supply-chain hardening.
- name: Checkout docs source
uses: actions/checkout@v5
with:
# On a release, take the docs as of the released tag; otherwise take
# the default checkout (post-merge default branch / dispatched ref).
ref: ${{ github.event_name == 'release' && github.event.release.tag_name || '' }}
.github/workflows/docs_sync.yml:132
actions/create-github-app-token@v3is referenced via a mutable tag. To match the repo’s workflow hardening, pin this action to a full commit SHA (as done foractions/checkout,actions/setup-node, etc.) so the workflow behavior can’t change unexpectedly.
- name: Generate token for target repo
id: app-token
uses: actions/create-github-app-token@v3
with:
Comment on lines
+3
to
+5
| keywords: ['clickhouse', 'js', 'JavaScript', 'NodeJS', 'web', 'browser', 'Cloudflare', 'workers', 'client', 'connect', 'integrate'] | ||
| slug: /integrations/javascript | ||
| description: 'The official JS client for connecting to ClickHouse.' |
|
|
||
| NB: request compression is currently not available in the Web version. Response compression works as normal. Node.js version supports both. | ||
|
|
||
| Data applications operating with large datasets over the wire can benefit from enabling compression. Currently, only `GZIP` is supported using [zlib](https://nodejs.org/docs/latest-v14.x/api/zlib.html). |
Comment on lines
+32
to
+35
| - name: Fetch the docs check driver | ||
| run: | | ||
| curl -fsSL -o /tmp/mintlify_docs_check.py \ | ||
| https://raw.githubusercontent.com/ClickHouse/ClickHouse/master/ci/jobs/scripts/docs/mintlify_docs_check.py |
peter-leonov-ch
approved these changes
Jul 22, 2026
peter-leonov-ch
left a comment
peter-leonov-ch
left a comment
Collaborator
There was a problem hiding this comment.
Address the code review comments please, most of them make sense. Otherwise, awesome, thanks a mil for owning this!
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
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.
Summary
Make
ClickHouse/clickhouse-jsthe source of truth for its public ClickHouse documentation.ClickHouse/ClickHouse@21ed77718a5f454680497924d68e9f60a41e026cintodocs/clickhouse-docs/, with trailing whitespace normalized and a client-ownednavigation.json. The dedicated subdirectory keeps repository-only troubleshooting docs out of the published slice.ClickHouse/ClickHouseafter a release, manual dispatch, or merge carrying thesync-docslabel.The published URL remains unchanged. Folder ownership allows future pages to be reviewed alongside the client implementation and synchronized automatically. Fragment links use explicit
/index#...targets so offline anchor validation resolves the folder index correctly.No package behavior changes, so package changelogs are unaffected.
Related: ClickHouse/ClickHouse#111223
After merge, maintainers should confirm the
sync-docslabel exists and the Workflow Auth GitHub App credentials are available to this repository.Validation
actionlintv1.7.7 and YAML parsing.navigation.jsonpasses JSON parsing.git diff --checkpasses.