Bitbucket

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 to create an access token for the Bitbucket repository. The repository must already have a commit and a default branch.

1. Create a Bitbucket repository token

1. In Bitbucket Cloud, open the repository's Settings > Security > Access tokens.
2. Select Create access token, give it a name and choose an expiry.
3. Enable Repositories: Read and Write and Pull requests: Read and Write.
4. Create the token and copy it. Bitbucket displays it only once.

See Bitbucket's repository token instructions for details.

2. Connect it in Querio

1. Open Settings > Git and select Connect Bitbucket.
2. In Bitbucket workspace/repository, enter the repository identity, such as example/analytics-context.
3. In Repository access token, paste the Bitbucket token.
4. Select Connect repository and confirm the repository name and Connected status.

Connecting sets File mode to Branches, which Git sync requires. If another provider is connected, disconnect it before connecting Bitbucket. If the token expires or is revoked, reconnect with a new token.

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. This is a separate credential from the Bitbucket repository token above.

Enable Pipelines for the repository. Under Repository settings > Pipelines > Repository variables, add QUERIO_ACCESS_TOKEN with the Querio token as its value and enable Secured.

2. Add the workflow

Save the following as bitbucket-pipelines.yml at the repository root. Replace WORKSPACE_ID with your Querio workspace ID. If your default branch is not main, update the branch name.

The build image must provide Linux x64, Bash, curl, Git and jq.

pipelines:
  branches:
    main:
      - step:
          name: Sync context to Querio
          max-time: 15
          script:
            - |
              set -euo pipefail
              : "${QUERIO_ACCESS_TOKEN:?Add QUERIO_ACCESS_TOKEN as a secured repository variable}"

              export QUERIO_WORKSPACE_ID=WORKSPACE_ID
              export QUERIO_API_URL=https://app.querio.ai
              export QUERIO_INSTALL_DIR=/tmp/querio-cli
              curl -fsSL https://raw.githubusercontent.com/Querio-App/cli/main/install.sh | bash
              export PATH="$QUERIO_INSTALL_DIR:$PATH"

              source_version=$(querio git upload --json \
                --repo "$BITBUCKET_CLONE_DIR" \
                --ref "$BITBUCKET_COMMIT" \
                --config querio.toml \
                --repository "$BITBUCKET_REPO_FULL_NAME" \
                | jq -er '.version | strings | select(test("^[A-Za-z0-9_-]+$"))')
              current_version=$(querio git status --json \
                | jq -er '.canonicalVersion | strings | select(test("^[A-Za-z0-9_-]+$"))')
              querio git promote "$source_version" \
                --expected-canonical "$current_version" --json

The workflow uses Bitbucket's built-in variables to select the repository and the commit that triggered the run. It installs Querio CLI and syncs the files selected by querio.toml.

3. Check the first run

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

After a successful run, start a new analysis in Explore and check the answer. Later merges into main run the same workflow automatically.

Connection and sync problems

• The repository cannot connect: check that it has a default branch and that the Bitbucket token has both sets of permissions above.
• PR creation stops working: check whether the Bitbucket token expired or was revoked, then disconnect and reconnect with a new token.
• CI cannot authenticate to Querio: check the secured QUERIO_ACCESS_TOKEN variable. It must contain a Querio token.
• 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.