Use Git and CI sync

Keep Querio context alongside dbt and the rest of your data project. This workflow does not import dbt models or metrics into Querio automatically.

The steps below use one file, memory/MEMORY.md, and repository identity example/analytics-context. Replace them with your own paths and identity. For file states, limits and permissions, see Files and versions.

Before you start

• Get Querio CLI, connect it to your workspace using the CLI reference, and use an existing local Git repository.
• Have permission to manage workspace settings for the GitHub connection. The file workflow needs workspace file read/write permission; CI publication also needs delete permission. These permissions do not grant database query access.
• Choose a small context change you can check against a known analysis. Keep credentials and unrelated private data out of the selected files.

1. Connect the GitHub repository

Open Settings > Git, select Connect GitHub, and grant the Querio app access to exactly one selected repository. Confirm the repository and Connected status. One GitHub installation connects to one workspace and enables Branches file mode. If the workspace already uses that mode without a GitHub connection, an administrator should confirm File mode under Settings > Git before you begin.

Connecting GitHub does not install a CI workflow. Set up CI after you have reviewed and merged the context change. Changing file mode also does not switch files in running environments.

2. Commit and upload selected context

Add the selection to querio.toml in your local repository:

[context]
repository = "example/analytics-context"
include = ["memory/**", "skills/**", "datasources/**"]
exclude = ["datasources/*/kb/drafts/**"]

These patterns select committed, repository-relative paths; exclusions win. [context].root locates context in Querio but does not restrict the Git upload selection. If your workspace uses another context root, align the paths with it. The CLI reads querio.toml from the commit; the file itself is uploaded only if an include pattern selects it.

Commit the intended context and configuration. From the repository, preview the selection, then upload it:

querio git upload --dry-run --json
querio git upload --json

The dry run lists selected paths without contacting Querio. Check that list before uploading. Uncommitted file edits and TOML changes are ignored. Upload returns a version for an immutable source snapshot; it does not change canonical workspace files.

Create a Querio working copy from that version:

querio git checkout SOURCE_VERSION --json

Replace SOURCE_VERSION with the upload's version. Record the returned working-copy ID as CHANGESET_ID. Checkout here creates a Querio working copy; it does not switch your local Git branch.

3. Make and review a context change

In Context, select the branch for working copy CHANGESET_ID. Edit memory/MEMORY.md and wait for Saved. To run analysis against that copy, create an environment with querio execution-environment create --changeset CHANGESET_ID. An existing environment keeps its original files; see File targets and execution.

Inspect what changed:

querio git status CHANGESET_ID --json

Check the changed paths, imported source and current canonical version. For a selected live session, querio changes status and querio changes diff inspect its bound working copy. Large or binary changes can appear without an inline diff, so inspect the file itself when needed.

4. Return changes through a patch or pull request

For a selected file, save edits and pause other writers before exporting. Select the exact changed path:

querio git patch CHANGESET_ID --path memory/MEMORY.md > querio-changes.patch

Check that export succeeded. The patch captures a checkpoint against the imported source; it does not approve or publish anything. Inspect it, then check and apply it in the original repository:

git apply --check querio-changes.patch
git apply querio-changes.patch
git diff -- memory/MEMORY.md

If git apply --check fails, reconcile the local branch with the imported source before applying. Commit the reviewed change on your branch, open a pull request through your team's process, and review and merge it. Keep the repository identity consistent in later uploads.

You can also open a PR from Context with an active GitHub connection. Wait for Saved, open Changes, and inspect the complete changed-file list and diffs. Select Open PR when those files are ready. Opening a PR does not publish canonical files; review and merge it before CI sync.

Without a GitHub connection, the same Publish action attempts to publish the whole checkpoint to canonical files. It is not a selected-path export. For this Git review workflow, use the patch route unless you have confirmed the connected PR path. Version and source-ownership checks can still reject publication. See Patch, pull request and publication.

5. Publish the merged commit through CI

Run CI against the merged commit on main. The Querio-App/sync Action uploads its selected files, reads canonicalVersion, and promotes that uploaded source using the expected canonical version. Your Git and CI checks provide the review gate; Querio does not verify PR approval or test results.

The Action runs on Linux x64 and needs a Querio access token with workspace file read/write/delete permissions. Its bundled CLI setup is separate from the GitHub connection. Add a workflow like this, replacing the workspace ID, repository identity and branch where needed:

name: Sync Querio context
on:
  push:
    branches: [main]
  workflow_dispatch:
permissions:
  contents: read
concurrency:
  group: querio-context-sync
  cancel-in-progress: false
jobs:
  sync:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Querio-App/sync@4e266fbbe047ca0a944bb9e6ff9cc4f9511a222c
        with:
          token: ${{ secrets.QUERIO_ACCESS_TOKEN }}
          workspace-id: WORKSPACE_ID
          repository: example/analytics-context

Store the token in the QUERIO_ACCESS_TOKEN repository secret. The Action reports source-version and canonical-version, which are Querio version IDs, not Git commit IDs. If CI uses an already provisioned compatible CLI directly, the corresponding operations are:

querio git upload --json
querio git status --json
querio git promote SOURCE_VERSION --expected-canonical CANONICAL_VERSION --json

Use the version returned by this CI upload and the canonicalVersion read for this attempt. A working-copy checkpoint is not an imported Git commit and cannot be promoted through this command.

Promotion replaces previously Git-managed files and removes managed files missing from the incoming selection. It preserves unrelated outputs, while conflicting unmanaged files can block publication. Treat include/exclude changes as deployment changes because they can remove files. Publication applies files one by one; if it fails or the response is lost, inspect canonical files before retrying.

6. Verify the new analysis uses it

Check that CI recorded the intended source and canonical versions. Compare the affected canonical file with the merged commit's selected contents. Then create a new working copy from the promoted source for the next analysis. Existing working copies and running environments keep their current files. /reload rebuilds context from a session's current directory; it does not switch that session to the promoted source.

Run one known question using the intended files and query identity. Compare its result with a trusted answer using Check and correct an answer. A successful upload or publication alone does not validate the analysis.

If a step fails

For file kinds and transfer limits, see Files and versions. For exact request and response shapes, see API reference.