Multi-Repository Management with AI
Manage changes across multiple repositories simultaneously using AI — cross-repo refactoring, dependency updates, and coordinated releases.
Why multi-repo management matters
Most organisations split their code across multiple repositories: a frontend repo, a backend API repo, a shared library repo, a mobile app repo, infrastructure-as-code, and documentation. This separation is good for autonomy — teams can deploy independently — but creates coordination challenges. When you need to update a shared API contract, you change the API repo, update the shared types library, update the frontend, update the mobile app, and update the documentation. Without tooling, this means opening 5 PRs manually, keeping them in sync, and deploying in the right order. AI can automate the repetitive parts while you focus on the decisions. Ask Claude Code: Create a Node.js project with TypeScript for a multi-repo management toolkit. Define the configuration at src/config.ts. A Workspace type has: name, repos as an array of RepoConfig (name, path on disk, githubUrl, defaultBranch, dependencies as array of other repo names in this workspace), and conventions (branch naming pattern, commit message format, PR template path). Create a sample workspace configuration for a typical setup: an api repo, a web-frontend repo, a mobile-app repo, a shared-types repo, and a docs repo. The dependencies field captures which repos depend on which: web-frontend depends on shared-types and api, mobile-app depends on shared-types and api, and docs depends on all other repos. Ask Claude Code: Create a workspace initialisation command that clones all repos in the workspace to a local directory, checks out the default branch for each, and runs git pull to ensure they are up to date. Show the status of all repos: branch, last commit, and whether there are uncommitted changes. Common error: different repos may use different Node.js versions, package managers (npm vs yarn vs pnpm), or build tools. Your toolkit should detect and handle these differences, not assume uniformity.
Cross-repository code changes
The most common multi-repo task is making a change that spans multiple repositories. Ask Claude Code: Create a cross-repo change system at src/lib/cross-change.ts. A CrossRepoChange has: an id, a description of the change, a list of RepoChange objects (each with the repo name, branch name, file changes, commit message), a status (planning, in_progress, reviewing, merged), and a dependency order (which repo changes must be merged first). Build the workflow for a common scenario: renaming a field in the shared API. Ask Claude Code: I want to rename the user.fullName field to user.displayName across all repos. Analyse each repo to find: all files that reference fullName (in TypeScript types, API calls, database queries, UI components, tests, and documentation), the exact changes needed in each file, the order in which repos should be updated (shared-types first, then API, then frontend and mobile simultaneously, then docs), and the branch name following the workspace convention. For each repo, create a branch, make the changes, and prepare a commit. Ask Claude Code: Implement the change execution. For each repo in dependency order: checkout the default branch and pull, create a feature branch (rename-fullname-to-displayname), apply the file changes, run the repo's linter and tests to verify nothing is broken, and commit with a descriptive message referencing the cross-repo change ID. After all repos are updated, show a summary: 5 repos changed, 23 files modified, all tests passing. Ask Claude Code: Add a dry-run mode. Before making any changes, show a detailed plan: every file that will be changed, the exact diff for each file, and any potential issues (for example, a test file references fullName in a mock that the search did not catch). Review the plan before executing. Common error: running tests in each repo after changes requires the dependencies to be updated first. If web-frontend depends on shared-types and you have changed both, the web-frontend tests will fail until the new shared-types is published or linked. Use npm link or workspace protocols to temporarily link local repos during the change process.
Dependency tracking and update propagation
When a shared library releases a new version, every repo that depends on it needs to update. Manually tracking these dependencies across many repos is error-prone. Ask Claude Code: Create a dependency tracker at src/lib/dependencies.ts. Scan each repo in the workspace for: npm dependencies in package.json (both dependencies and devDependencies), internal workspace dependencies (references to other repos, like @myorg/shared-types), and version constraints (exact versions, caret ranges, tilde ranges). Build a dependency graph visualisation. Ask Claude Code: Generate a text-based dependency graph showing which repos depend on which packages and which internal repos. Identify: circular dependencies (repo A depends on B which depends on A — these are problematic), outdated internal dependencies (web-frontend uses shared-types 1.2.0 but the latest is 1.4.0), and version mismatches (web-frontend uses react 18.2.0 but mobile-app uses react 18.1.0 — these should be synchronised). Automate dependency updates. Ask Claude Code: Create a command that updates a shared dependency across all repos. For example: update TypeScript to version 5.4 in all repos. The command should: find every repo that uses TypeScript, update the version in package.json, run npm install to update the lock file, run the TypeScript compiler to check for new errors, run tests, and create a branch and commit for each repo. Report any repos where the update causes build or test failures. Add a dependency health report. Ask Claude Code: Create a weekly report that shows: packages with known security vulnerabilities (run npm audit in each repo), packages that are more than 2 major versions behind the latest, internal dependencies that are out of date, and the total dependency count per repo (bloated repos with too many dependencies). Rank repos by urgency — the one with the most critical vulnerabilities should be updated first. Common error: updating a shared dependency can have cascading effects. If updating TypeScript in the shared-types repo changes the emitted type definitions, every consuming repo may need changes. Always update from the bottom of the dependency tree upward.
Coordinated pull requests and releases
Cross-repo changes need coordinated PRs that reference each other and are merged in the correct order. Ask Claude Code: Create a coordinated PR system at src/lib/coordinated-pr.ts. When a cross-repo change is ready for review, create a PR in each repo using the GitHub API (via the gh CLI). Each PR description should include: a summary of the overall cross-repo change, links to the related PRs in other repos, the merge order (which PR should be merged first), and any pre-merge requirements (shared-types must be published to npm before web-frontend PR can be merged). Ask Claude Code: Implement PR creation using gh pr create. For each repo in the change: push the feature branch, create the PR with the linked description, add reviewers (configurable per repo in the workspace config), and add labels (cross-repo-change, the change ID). Build a merge coordinator. Ask Claude Code: Create a merge command that processes a cross-repo change. Following the dependency order: merge the first PR (shared-types), wait for CI to pass, trigger the package publish (if it is a library), wait for the new version to be available on npm, update the dependent repos' PRs to use the new version, merge the next level of PRs (API), and continue until all PRs are merged. At each step, check CI status and pause if tests fail. Add a release coordination system. Ask Claude Code: Create a release command that cuts a coordinated release across all repos. Tag each repo with a version (following semver), generate a changelog from the commit messages since the last release, create GitHub releases in each repo with the changelog and links to related releases, and publish packages that need publishing (npm publish for libraries, deploy for applications). Common error: merging PRs in the wrong order breaks things. If you merge the frontend PR before the API PR, the frontend will reference endpoints that do not exist yet. The merge coordinator must enforce the dependency order strictly. If a PR fails CI, it blocks all downstream merges.
Repository health monitoring
With multiple repos, it is easy to lose track of which ones are healthy and which need attention. Ask Claude Code: Create a workspace health dashboard at src/lib/health.ts. For each repo in the workspace, check: CI status (is the default branch's last CI run passing?), dependency freshness (any outdated or vulnerable packages?), branch hygiene (how many stale branches exist — branches older than 30 days with no recent commits?), PR backlog (how many open PRs, how old are they?), code coverage (what percentage of code is covered by tests?), and documentation status (does README exist, is it up to date, are there broken links?). Generate a workspace health report. Ask Claude Code: Create a formatted report showing all repos with traffic-light indicators: green for healthy, yellow for needs attention, red for action required. Rank repos by health score so the worst ones surface to the top. Include specific actionable items: merge PR 47 in api repo (open for 23 days), update lodash in web-frontend (known vulnerability CVE-2024-xxxx), delete 12 stale branches in mobile-app. Add a standards checker. Ask Claude Code: Define workspace standards that all repos should follow: must have a CI configuration, must have a README with specific sections (setup, development, deployment), must have a .gitignore that excludes node_modules and .env, must use the same linter configuration (share a base ESLint config), and must have a CODEOWNERS file for review assignment. Check each repo against these standards and report violations. Add an automated fixer for common violations — missing .gitignore entries, missing CI configuration (generate from a template), and outdated README sections. Common error: repo health checks that run too slowly get ignored. Optimise by caching results (GitHub API responses can be cached for 5 minutes), running checks in parallel across repos, and only rechecking metrics that are likely to change (CI status changes frequently, dependency counts change weekly, documentation changes monthly).
Automation scripts and team workflows
Package all the multi-repo management capabilities into an easy-to-use CLI that your team can adopt. Ask Claude Code: Create a CLI at src/cli.ts using Commander.js (npm install commander). Define commands: workspace status (show all repos with branch, last commit, and health indicators), workspace sync (pull latest changes in all repos), change create description (start a new cross-repo change — creates branches in all affected repos), change plan (show the planned changes without executing), change apply (execute the planned changes), change pr (create coordinated PRs), change merge (merge PRs in dependency order), deps update package version (update a dependency across all repos), deps audit (run security audit across all repos), health report (generate the workspace health report), and release (coordinate a release across all repos). Add a CLAUDE.md file for each repo in the workspace. Ask Claude Code: Generate a CLAUDE.md file that describes the repo's purpose, its dependencies on other workspace repos, the development workflow (how to run, test, and deploy), and the conventions (branch naming, commit message format, PR process). When Claude Code opens any repo in the workspace, it immediately understands the context and conventions. Add team workflow automation. Ask Claude Code: Create a new-developer-setup command that: clones all workspace repos, installs dependencies in each, sets up environment variables from .env.example files, runs the test suite in each repo to verify setup, and generates a workspace map showing how the repos relate to each other. This reduces new developer onboarding from a day of manual setup to a 10-minute automated process. Deploy the toolkit as an npm package. Ask Claude Code: Package the CLI for distribution. The team installs it globally: npm install -g @myorg/workspace-cli. After installation, the ws command is available: ws status, ws change create, ws health report. Include an auto-update check that notifies when a new version is available. The multi-repo management toolkit is complete — transforming a manual, error-prone process into an automated, reliable workflow.
DevOps at Scale
This guide is hands-on and practical. The full curriculum covers the conceptual foundations in depth with structured lessons and quizzes.
Go to lesson