fix-sync — Claude Code skill: diagnose and fix sync job failures
fix-sync is a Claude Code skill that diagnoses and fixes three types of “CH Inc sync” CI failures in ClickHouse PRs: merge conflicts, build errors, and test failures.
Apache-2.0 ★ 51,058 updated 2026-10-29
npx skills add ClickHouse/ClickHouse --skill fix-sync -a claude-codeWhat fix-sync does
This skill handles synchronization between the public ClickHouse repository and the private clickhouse-private. When a PR opens in ClickHouse/ClickHouse, a sync PR is created in the private repo on branch sync-upstream/pr/<number>. The “CH Inc sync” status on the public PR reflects the state of that private sync branch.
The skill identifies which of three errors occurred: merge conflicts with master of the private repo (mergeable = CONFLICTING), a build job failed in private CI, or tests failed. Each case gets its own handler — conflict resolution, code adaptation when public changes affect private-only symbols, or test investigation.
It takes a public PR number or URL, finds the corresponding private sync PR, reads the “CH Inc sync” status description, and proceeds accordingly. If it needs to work with private repo files, it asks for the path or searches common locations alongside the current directory.
What it helps with
- resolve merge conflicts when syncing a PR with master of the private repository
- find and fix a build error in private CI caused by upstream changes
- determine whether test failures are infrastructure-related or a real regression
- wait for in-progress CI instead of attempting fixes on incomplete runs
Example prompts for the agent
- diagnose and fix the failure in PR 96005
- check the sync status for https://github.com/ClickHouse/ClickHouse/pull/96005
- resolve merge conflicts in the sync PR for number 96005
How to install fix-sync
1Skills CLI (Vercel)
npx skills add ClickHouse/ClickHouse --skill fix-sync -a claude-code2Manually: put the files in place
~/.claude/skills/fix-sync/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/fix-sync/
1Skills CLI (Vercel)
npx skills add ClickHouse/ClickHouse --skill fix-sync -a codex2Manually: put the files in place
.agents/skills/fix-sync/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add ClickHouse/ClickHouse --skill fix-sync -a cursor2Manually: put the files in place
.cursor/skills/fix-sync/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install ClickHouse/ClickHouse .claude/skills/fix-sync2Manually: put the files in place
.github/skills/fix-sync/SKILL.md1Skills CLI (Vercel)
npx skills add ClickHouse/ClickHouse --skill fix-sync -a gemini-cli2Platform CLI
gemini skills install https://github.com/ClickHouse/ClickHouse --path .claude/skills/fix-syncManually: put the files in place
.devin/skills/fix-sync/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add ClickHouse/ClickHouse --skill fix-sync -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about fix-sync
How do I install fix-sync?
In Claude Code, run npx skills add ClickHouse/ClickHouse --skill fix-sync -a claude-code, then open ~/.claude/skills/fix-sync/SKILL.md. On other platforms: GitHub Copilot uses gh skill install ClickHouse/ClickHouse fix-sync; Cursor uses npx skills add ClickHouse/ClickHouse --skill fix-sync -a cursor; Codex uses npx skills add ClickHouse/ClickHouse --skill fix-sync -a codex.
What does fix-sync do?
It diagnoses a sync PR error in ClickHouse and applies the right fix: resolves merge conflicts, repairs a private CI build, or helps investigate test failures. The “CH Inc sync” status on the public PR indicates which of the three error types occurred.
What do I need for fix-sync to work?
Access to the clickhouse-private repository (or the path to it on disk), a public PR number or URL from ClickHouse/ClickHouse, and GitHub API permissions to read CI statuses via gh.
Source text
SKILL.md · Apache-2.0
---
name: fix-sync
description: Fix the "CH Inc sync" job in a pull request. Diagnoses the failure as one of three types — conflicts found, build failed, or tests failed — and handles each accordingly.
argument-hint: <pr-number-or-url>
disable-model-invocation: false
allowed-tools: Task, Bash(gh:*), Bash(cd:*), Bash(git:*), Bash(ls:*), Bash(pwd:*), Bash(mktemp:*), Read, Grep, Glob, AskUserQuestion
---
# Fix CH Inc Sync Skill
Fix the "CH Inc sync" CI job for a ClickHouse pull request. The job runs the corresponding `clickhouse-private` sync PR through merge and private CI, so it can fail in three distinct ways. This skill first **diagnoses** which type of failure occurred, then applies the matching fix.
## The three failure types
The "CH Inc sync" commit status on the public PR reports its failure as one of three descriptions (set by the private CI in `clickhouse-private`: `ci/jobs/private_sync_pr.py` for conflicts, `ci/jobs/scripts/workflow_hooks/private_sync_complete_check.py` for build/test failures):
1. **`conflicts found`** — the sync PR cannot be merged with `master` of `clickhouse-private` (`mergeable == CONFLICTING`). Resolve the merge conflicts and push.
2. **`build failed`** — the sync PR merges cleanly, but a build job in the private CI fails. Usually the upstream change needs adaptation in private-only code that references changed symbols. Fix the build and push.
3. **`tests failed`** — the sync PR merges and builds, but test jobs fail. The failure is either flaky/infra-related (rerun the failed jobs) or a genuine regression (investigate).
The `pending` description `testing` means CI is still running — wait rather than act.
## Arguments
- `$0` (required): PR number or full GitHub URL of the public ClickHouse PR (e.g., `96005` or `https://github.com/ClickHouse/ClickHouse/pull/96005`)
## Overview
When a PR is opened in `ClickHouse/ClickHouse`, a sync PR is automatically created in `ClickHouse/clickhouse-private` on a branch named `sync-upstream/pr/<PR_NUMBER>`. The "CH Inc sync" check on the public PR reflects the state of that private sync PR: it stays pending/failing if the sync PR has conflicts, fails to build, or has failing tests.
## Process
### 1. Parse the PR number
- Extract the PR number from `$ARGUMENTS`
- If a full URL is provided (e.g., `https://github.com/ClickHouse/ClickHouse/pull/96005`), extract the number from the URL
- If no argument is provided, use `AskUserQuestion` to ask for the PR number
### 2. Find the sync PR
- Search for the corresponding sync PR in the private repository:
```bash
gh pr list --repo ClickHouse/clickhouse-private --head sync-upstream/pr/<PR_NUMBER> --json number,url,state,mergeable,mergeStateStatus,headRefName,headRefOid
```
- If no sync PR is found, report this to the user and stop
- Report the sync PR number and URL to the user
### 3. Diagnose the failure type
This is the key step. Determine which of the three failure types applies before doing any work.
1. **Read the "CH Inc sync" commit status description on the public PR** — it directly states the failure type:
```bash
gh api repos/ClickHouse/ClickHouse/commits/<HEAD_SHA>/statuses --jq '.[] | select(.context == "CH Inc sync") | {state, description}'
```
(Get `<HEAD_SHA>` from `gh pr view <PR_NUMBER> --repo ClickHouse/ClickHouse --json headRefOid`.)
Map the description to a handler:
- `conflicts found` → **Conflicts found** → step 4A.
- `build failed` → **Build failed** → step 4B.
- `tests failed` → **Tests failed** → step 4C.
- `testing` (state `pending`) → CI is still running. Report this and stop — wait rather than act.
- `completed` (state `success`) → no action needed, stop.
2. **If the status description is missing or ambiguous**, fall back to inspecting the sync PR directly:
- If `mergeable` is `CONFLICTING` (or `mergeStateStatus` is `DIRTY`) → **Conflicts found** → step 4A.
- Otherwise inspect the private CI checks: `gh pr checks <SYNC_PR_NUMBER> --repo ClickHouse/clickhouse-private`. A failing job whose name starts with `Build` → **Build failed** (step 4B); only test jobs failing → **Tests failed** (step 4C).
Report the diagnosed failure type to the user before proceeding.
### 4. Locate the private repository (needed for 4A and 4B)
- Look for the `clickhouse-private` repository in common locations relative to the current working directory:
- `../ClickHouse_private`
- `../clickhouse-private`
- Check if the directory exists and contains a git repository with `ClickHouse/clickhouse-private` as a remote
- If not found, use `AskUserQuestion` to ask the user for the path
- Store the path for use in subsequent steps
---
### 4A. Handle "Conflicts found"
#### Fetch and switch to the sync branch
In the private repository directory:
```bash
cd <private_repo_path> && git fetch origin && git fetch origin sync-upstream/pr/<PR_NUMBER>
```
Then check out the sync branch:
```bash
cd <private_repo_path> && git checkout sync-upstream/pr/<PR_NUMBER>
```
If the branch has local changes, ask the user before proceeding.
#### Merge master and resolve conflicts
```bash
cd <private_repo_path> && git merge origin/master
```
This will likely produce conflicts. Handle them:
1. **List conflicted files:**
```bash
cd <private_repo_path> && git diff --name-only --diff-filter=U
```
2. **For each conflicted file**, use a Task agent with `subagent_type=general-purpose` to resolve:
- Read the conflicted file content
- Analyze the conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`)
- Determine the correct resolution:
- For most sync conflicts, the upstream (public repo) changes should take precedence
- For files that exist only in the private repo, preserve them
- For CI/workflow files, be careful to preserve private-repo-specific configurations
- Apply the resolution using Edit tool
- Stage the resolved file: `git add <file>`
**IMPORTANT:** If conflicts are complex or ambiguous, show the conflicts to the user and ask how to resolve them using `AskUserQuestion`.
3. **After resolving all conflicts**, complete the merge:
```bash
cd <private_repo_path> && git commit --no-edit
```
#### Update submodules (if needed)
```bash
cd <private_repo_path> && git submodule update --init --recursive
```
If submodule update fails, report the error but continue.
Then go to step 5 (push and verify).
---
### 4B. Handle "Build failed"
A clean merge that fails to build almost always means the upstream change renamed, moved, or changed the signature of something that **private-only** code depends on, or the merge needs a code adaptation that conflict resolution did not surface.
1. **Fetch the build log** to find the exact error. Identify the failed build run and download its log:
```bash
gh run list --repo ClickHouse/clickhouse-private --branch sync-upstream/pr/<PR_NUMBER> --json databaseId,name,conclusion,headSha
```
Use the public CI log tool when a report URL is available (see `.claude/tools/fetch_ci_report.js`), or inspect the failed job log via `gh run view --log-failed`.
2. **Locate the build error** (compile error, linker error, missing symbol). Use a Task agent with `subagent_type=general-purpose` to analyze the log and return only the relevant error excerpt and the file/symbol involved.
3. **Reproduce and fix in the private repo.** Check out the sync branch (fetch + merge `origin/master` if not already merged), then fix the offending private code to match the upstream change. Prefer adapting the private code to the new upstream API rather than reverting the upstream change.
4. **Optionally rebuild to verify** (see step 5's build verification).
Then go to step 5 (push and verify).
---
### 4C. Handle "Tests failed"
Merge and build are fine, but tests fail. First decide whether the failure is **flaky/infra** or **genuine**.
1. **Fetch the failing test details:**
```bash
gh pr checks <SYNC_PR_NUMBER> --repo ClickHouse/clickhouse-private
gh run list --repo ClickHouse/clickhouse-private --branch sync-upstream/pr/<PR_NUMBER> --json databaseId,name,conclusion
```
2. **Classify as flaky/infra if** the failures are infrastructure errors unrelated to the PR's changes, e.g. `Cannot start clickhouse-server`, `Timeout`, network/disk errors, or failing tests that touch areas the PR does not modify. (See the `pr-89842-sync-rerun` note: a PR touching only `src/IO/*` had `Cannot start clickhouse-server` / `Timeout` failures — clearly unrelated.)
- **Action:** rerun only the failed jobs, do **not** run a merge:
```bash
gh run rerun <RUN_ID> --repo ClickHouse/clickhouse-private --failed
```
- Report that a rerun was triggered and stop.
3. **Otherwise, treat as a genuine regression.** Use a Task agent to fetch and summarize the failing test logs, then report the failing tests and the likely cause to the user. Do not push speculative fixes without confirmation — use `AskUserQuestion` to decide next steps.
This path normally does not push to the sync branch (unless a genuine fix is made), so skip step 5 unless a code change was committed.
---
### 5. Push the resolved branch (for 4A / 4B, and 4C only if a fix was committed)
#### Build verification (optional)
Use `AskUserQuestion` to ask the user:
- "Do you want to build ClickHouse in the private repository to verify the merge/fix?"
- Option 1: "Yes, build" - Run ninja in the private repo build directory (redirect output to a build log; use a subagent to summarize)
- Option 2: "No, skip build" - Skip building and proceed to push
#### Push
```bash
cd <private_repo_path> && git push origin sync-upstream/pr/<PR_NUMBER>
```
### 6. Verify the sync PR
After pushing (or rerunning):
```bash
gh pr view <SYNC_PR_NUMBER> --repo ClickHouse/clickhouse-private --json mergeable,mergeStateStatus
gh pr checks <SYNC_PR_NUMBER> --repo ClickHouse/clickhouse-private
```
Report the result per failure type:
- **Conflicts found:** if `mergeable` is now `MERGEABLE`: "Sync PR is now mergeable. The CH Inc sync check should pass shortly." If still conflicting: "Sync PR still has conflicts. Additional investigation may be needed."
- **Build failed:** report whether the build job now passes (it may take a while for CI to start).
- **Tests failed:** report whether the rerun is in progress or the fix was pushed.
Provide the sync PR URL for the user to check.
## Examples
- `/fix-sync 96005` - Diagnose and fix sync for PR #96005
- `/fix-sync https://github.com/ClickHouse/ClickHouse/pull/96005` - Fix sync using full URL
## Notes
- Always diagnose the failure type (step 3) before acting. Running a merge against a sync PR that is already `MERGEABLE` does nothing useful — for build/test failures the fix is different (see the `pr-89842-sync-rerun` note: rerun failed jobs rather than `/fix-sync` when no merge conflict exists).
- The sync branch name follows the pattern: `sync-upstream/pr/<PR_NUMBER>`
- The private repository is typically located one directory level up from the public repository
- Most conflicts are straightforward and involve the upstream changes taking precedence
- Always fetch before switching branches to ensure you have the latest state
- Do not use rebase or amend - add new commits instead (per project conventions)
- After pushing, it may take a few minutes for the GitHub check to update
© ClickHouse · Apache-2.0 · ClickHouse/ClickHouse