Bulk clone and synchronize all accessible repositories from GitHub or GitLab into a structured worktree-friendly local layout.
- GitHub stars
- 32
- Files
- 2
- Last commit
- Nov 10, 2026
- License
- Apache-2.0
- Allowed tools
- —
What does the ghsync skill do?
ghsync is an agent skill. Bulk clone and synchronize all accessible repositories from GitHub or GitLab into a structured worktree-friendly local layout.
Summary generated from the skill's SKILL.md.
About the ghsync skill
Developers onboarding into new organizations or managing large numbers of repositories can use this skill to automate the discovery and synchronization of their entire codebase. It identifies every accessible repository across GitHub or GitLab and mirrors them into a structured local directory. The tool is designed to maintain a clean development environment by using a specific layout where the default branch remains untouched in a main directory while providing a sibling directory for worktrees.
When an agent loads this skill, it can perform bulk operations such as cloning new repositories, fast-forwarding existing ones, and updating worktrees. It relies on the gh, glab, and jq command-line tools to interact with APIs and manage git operations. The process is safe because it only performs fast-forward updates and will not pull changes if it detects uncommitted work or if the repository is not on its default branch. Users can target specific GitHub organizations, personal accounts, or GitLab groups and subgroups using various flags to control the scope and destination of the sync.
What an agent can do with it
- 1Onboard to a new enterpriseAutomatically find and clone every repository you have access to when joining a new company.
- 2Synchronize GitLab group projectsMirror all projects within a specific GitLab group and its nested subgroups into a local path.
- 3Sync repositories from a listUpdate only a specific set of repositories using a machine-readable file to bypass API discovery.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the ghsync skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the ghsync skill in Plugin
/plugin marketplace add bjcoombs/ai-native-toolkit /plugin install ai-native-toolkit@ai-native-toolkit
Install the ghsync skill in Claude Code
~/.claude/skills/ghsync/SKILL.md
$ npx degit bjcoombs/ai-native-toolkit/skills/ghsync ~/.claude/skills/ghsyncInstall the ghsync skill in Claude Code (project)
.claude/skills/ghsync/SKILL.md
$ npx degit bjcoombs/ai-native-toolkit/skills/ghsync .claude/skills/ghsyncInstall the ghsync skill in Codex
~/.agents/skills/ghsync/SKILL.md
$ npx degit bjcoombs/ai-native-toolkit/skills/ghsync ~/.agents/skills/ghsyncInstall the ghsync skill in Gemini CLI
~/.gemini/skills/ghsync/SKILL.md
$ npx degit bjcoombs/ai-native-toolkit/skills/ghsync ~/.gemini/skills/ghsyncInstall the ghsync skill in Claude.ai
npx degit bjcoombs/ai-native-toolkit/skills/ghsync ghsync && zip -r ghsync.zip ghsync # claude.ai → Customize → Skills → + → Create skill → Upload a skill → ghsync.zip
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablebjcoombs/ai-native-toolkit/skills/ghsync is public and reachablegithub.com/bjcoombs/ai-native-toolkit/tree/HEAD/skills/ghsyn ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-10github.com/bjcoombs/ai-native-toolkit/commits ↗Pass
- No download-and-run or credential theft in scripts1 script read; no download-and-run, remote eval, base64 execution or credential uploadPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/bjcoombs/ai-native-toolkit/blob/HEAD/skills/ghsyn ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/bjcoombs/ai-native-toolkit/blob/HEAD/skills/ghsyn ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 196 linesgithub.com/bjcoombs/ai-native-toolkit/blob/HEAD/skills/ghsyn ↗Pass
SKILL.md
View on GitHubghsync: mirror and sync every repo you can access on GitHub or GitLab
Onboarding into a new enterprise means finding and cloning dozens of repos by hand, then drifting out of date. This skill does both halves: it discovers everything you can reach and keeps it in sync.
- First run — clones every accessible repo into a worktree-friendly layout.
- Every run after — fast-forward updates repos already on their default branch, updates their worktrees, and clones anything new. It never clobbers local work: repos with uncommitted changes or on a non-default branch are fetched but not pulled, and reported in the summary.
It is org-agnostic: point it at any GitHub org, GitHub Enterprise host,
personal account, or a GitLab host (gitlab.com or self-managed) with
--provider gitlab; see GitLab below. On GitHub: the script detects the account type itself. For an
organization it unions the teams you belong to with the org's repo list (so
direct-collaborator and public repos are included even with no team
membership); for a personal account it uses the account's repo list (private
repos included when it's your own account).
How to run it
The script lives next to this file. Claude Code writes this skill's directory into the script paths below when it loads the skill, so each path is already absolute:
# Org is derived from the directory you run in. To mirror the "meridianhub"
# org, run from a directory named meridianhub:
cd ~/dev/github.com/meridianhub
bash "${CLAUDE_SKILL_DIR}/scripts/ghsync.sh"
The org defaults to the basename of the directory you launch from. So
running inside ~/dev/github.com/meridianhub syncs the meridianhub org into
that directory. Override the org name or target directory explicitly when they
differ:
bash "${CLAUDE_SKILL_DIR}/scripts/ghsync.sh" --org meridianhub --root ~/dev/github.com/meridianhub
What to do when invoked
- Confirm the target. Run with
--list-reposfirst (or--list-teamsfor an org) so the user sees which account and how many repos before any cloning. This doubles as a check that the derived account name is correct. - Dry run on first use against a new org (
--dry-run) to preview clones and updates without touching disk. - Run the real sync. Stream the output; the run ends with a summary (up-to-date / updated / failed / uncommitted / branch issues / worktrees).
- Surface the exceptions. Call out anything under Failed, Uncommitted changes, or Not on default branch — these are the repos the user may need to deal with manually.
Flags
| Flag | Effect |
|---|---|
--provider github|gitlab |
Which host type to sync (default: github) |
--root DIR |
Directory to clone into; an explicit --root must already exist, in every mode (GitHub default: current directory; GitLab default: ~/dev/<host> with any :port dropped, created on the first real sync) |
--list-repos |
List the deduplicated accessible repos and exit |
--porcelain |
Machine-readable repo list: one path per line to stdout (GitHub: the repo name; GitLab: path_with_namespace), all chatter to stderr; implies --list-repos. Consumed by /ghreport and by --from-list. |
--dry-run |
Show what would be cloned/updated without making changes. On GitLab it creates no directory and writes no .gh_archived_repos; on GitHub it still refreshes .gh_archived_repos in the root |
--limit N |
Process only the first N repos (useful for a quick test) |
--quiet |
Suppress per-repository chatter; keep the final summary |
--org NAME |
GitHub only. Org or personal account to sync (default: basename of --root / cwd) |
--list-teams |
GitHub only. List your teams in the org (with repo counts) and exit; orgs only |
--host HOST |
GitLab only. Host to sync (default: gitlab.com); https:// and a trailing / are accepted, and so is a web port (host:8443) |
--group PATH |
GitLab only. Sync one group and its subgroups instead of every group you belong to. Covers every project the group shows you, including when you belong only to a subgroup of it (projects directly in the group and in sibling subgroups count). If the group itself cannot be read, the run syncs your subgroups under it and prints one stderr warning naming them and what was skipped; it fails only when nothing under the group is reachable |
--from-list FILE |
GitLab only. Sync the paths in FILE (the --porcelain format; blank lines and # comments ignored) with no discovery and no glab |
A flag that belongs to the other provider is rejected with an error, not ignored.
GitLab
# Every project in every group you belong to on gitlab.com, into ~/dev/gitlab.com/
bash "${CLAUDE_SKILL_DIR}/scripts/ghsync.sh" --provider gitlab --list-repos
bash "${CLAUDE_SKILL_DIR}/scripts/ghsync.sh" --provider gitlab
# One group subtree on a self-managed host, into ~/dev/gitlab.example.com/
bash "${CLAUDE_SKILL_DIR}/scripts/ghsync.sh" --provider gitlab --host gitlab.example.com --group platform/infra
- Discovery runs through
glab api --paginate: the groups you belong to (groups?min_access_level=10), each group'sdescendant_groups, and each group'sprojectsandprojects/shared. Dedupe is onpath_with_namespace, so a project reachable directly and through sharing, or shared into two groups, is cloned once. - Layout: each project lands under its own
path_with_namespace, so nested subgroups become nested directories and a shared project from another namespace sits under that namespace, not under the group it was shared into:~/dev/<host>/<group>/<subgroup>/<repo>/<repo>-mainplus a siblingworktree/. - Archived and empty projects are skipped, as on GitHub.
- Clone URLs are built from the host:
https://<host>/<path>.git, orgit@<host>:<path>.gitwithGHSYNC_GIT_PROTOCOL=ssh. For HTTPS on a private project, letglab auth loginset up git credentials. A port on--hostis the web and API port: it stays in the HTTPS URL and is dropped from the SSH URL. Set a non-standard SSH port for the host in~/.ssh/config. - Default root:
~/dev/<host>, with any port dropped, so--host gitlab.example.com:8443syncs into~/dev/gitlab.example.com/. Two instances on one host name but different ports would share that root: give one an explicit--root. - Preview runs (
--list-repos,--porcelain,--dry-run) create no directory and write no.gh_archived_repos, so the list can be produced on a machine that will never hold the checkouts. An explicit--rootmust still exist. - Path rules follow GitLab's (
lib/gitlab/path_regex.rb): a segment starts with a letter, digit,_or.(sogrp/.dotfilessyncs), then letters, digits,_,-and.. Segments.and.., any segment ending in.gitor.atom, and.gitin any case are skipped with a warning. So is a first segment, in any case, that names one of ghsync's own root entries (.gh_archived_repos, or.gh_sync_tmp, which older versions delete on every run); deeper segments may use those names. - Fail fast: before any discovery call, the script checks that
glabandjqare installed and thatglab auth status --hostname <host>passes. A failure prints one line naming the host and the check (installed, authentication or reachability) and exits non-zero. It does not retry, and it never tunnels or works around network controls.
Hosts reachable only from another network
Discovery needs the GitLab API; cloning needs only git. When the two are reachable from different places, split the run:
# 1. Where the API answers: save the project list.
bash "${CLAUDE_SKILL_DIR}/scripts/ghsync.sh" --provider gitlab --host gitlab.example.com --porcelain > projects.txt
# 2. Where git reaches the host: clone and sync from the list. No glab needed.
bash "${CLAUDE_SKILL_DIR}/scripts/ghsync.sh" --provider gitlab --host gitlab.example.com --from-list projects.txt
Step 2 builds the same layout as a discovery run and makes no API call.
Edit the list to drop projects; --limit applies to it too.
Layout produced
<root>/<path>/ # GitHub: the repo name; GitLab: path_with_namespace
├── <repo>-main/ # default-branch checkout, kept clean and up to date
└── worktree/ # ready for `git worktree add ...`
This matches the worktree convention the rest of the toolkit assumes:
<repo>-main stays on the default branch and clean, and feature work happens in
sibling worktrees.
Sync safety rules
- Repos with uncommitted changes (staged or unstaged edits to tracked files; untracked files do not count) are fetched but not pulled (reported under Uncommitted changes).
- Repos not on their default branch are fetched but not pulled (reported under Not on default branch).
- Updates are fast-forward only (
git pull --ff-only) — no merge commits, no rebases, never a force. - Worktrees on the default branch with no local changes are fast-forwarded too.
- A repo that exists locally without the
<repo>-mainstructure is flagged (Wrong structure) rather than touched.
Requirements & configuration
- GitHub:
ghandjqonPATH, andgh auth statusmust be authenticated. The script checks both up front. - GitLab:
glabandjqonPATH, andglab auth status --hostname <host>must pass (--from-listneeds onlygitandjq). - GitHub Enterprise:
ghuses its configured host. Target a GHE instance by settingGH_HOST=github.example.comor runninggh auth login --hostname github.example.comfirst. - Access model: for an organization, repos are discovered by unioning
two sources and deduplicating: the teams you belong to (
gh api user/teams) and the org repo list (gh repo list <org>), which also surfaces public repos and repos reachable via direct collaborator grants outside any team. Team membership is not a precondition — a user on no team still syncs every repo they can otherwise access. For a personal account, repos come fromgh repo list <account>(includes private repos when authenticated as that account). Empty repos with no default branch are skipped in both cases. - Blacklist: export
GHSYNC_BLACKLIST="repo-a repo-b"to skip oversized or problematic repos. Entries are repository paths (group/sub/repoon GitLab). timeout: optional but recommended (brew install coreutils) — caps each repo at 5 minutes so one hung clone can't stall the run.- Archived repos are skipped from cloning and cached to
<root>/.gh_archived_reposfor reference.
Files in this skill
2ghsync skill questions
How do I install the ghsync skill in Claude Code?
Run npx degit bjcoombs/ai-native-toolkit/skills/ghsync ~/.claude/skills/ghsync. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the ghsync skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
How does ghsync handle repositories with uncommitted changes?
Repos with uncommitted changes are fetched but not pulled to prevent clobbering local work, and they are reported in the final summary.
What is the directory structure created by this tool?
It creates a layout where each repository has a main branch directory and a sibling worktree directory: <path>/<repo>-main + <path>/worktree.
Can I sync GitLab repositories if the API is only reachable from a specific network?
Yes, you can use --porcelain to save a machine-readable list of projects from a network with API access, then use --from-list to clone them from a network that only has git access.