GitHub

Follow Sync with Git for the order of setup and the everyday review workflow.

For other supported repository connections, see Git Providers.

Connect the repository

You need permission to manage workspace settings in Querio and permission to install the GitHub app for your repository.

1. In Querio, open Settings > Git and select Connect GitHub.
2. In GitHub, grant the Querio app access to exactly one selected repository.
3. Return to Querio and confirm the repository name and Connected status.

One GitHub installation connects to one Querio workspace. Connecting sets File mode to Branches, which Git sync requires. Existing running environments keep their current files.

Before enabling CI, copy the existing Querio context into the repository. The first sync must use those files unchanged.

Set up CI sync

1. Add a Querio token

Follow Create a key to create a Querio API key. Its owner needs workspace file read, write and delete permissions; the key inherits those permissions. Store the key as the GitHub Actions repository secret QUERIO_ACCESS_TOKEN.

2. Add the workflow

Save the following as .github/workflows/querio-sync.yml in your repository.

Replace WORKSPACE_ID with your Querio workspace ID and example/analytics-context with your GitHub owner/repository. If your default branch is not main, update both branch checks.

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

The Querio sync Action installs its CLI on the Linux x64 runner. The workflow runs on pushes to main; Run workflow also lets you start it manually from GitHub Actions.

3. Check the first run

Commit the workflow with the unchanged files copied from Querio and push it to main. Open Actions in GitHub and wait for the sync to succeed.

The Action reports source-version and canonical-version, which identify Querio file versions. After a successful run, start a new analysis in Explore and check the answer.

Later merges into main run the same workflow automatically. Connecting the GitHub app alone does not set up this workflow.

Connection and sync problems

• The installation has more than one repository: change the GitHub app installation to select exactly one repository, then reconnect.
• PR creation fails or access is suspended: check the GitHub app's repository access. A failed PR does not publish changes into Querio.
• The first sync rejects an existing file: follow First-sync conflicts.
• A successful sync is missing files: check the include/exclude selection in querio.toml. After the corrected sync succeeds, start a new analysis in Explore.

For manual Git operations, see the CLI reference. For file ownership and publication rules, see Files and versions.