cross-repo-upstream-submodule-sync

Files (1)

• SKILL.md

SKILL.md (first lines)

# Cross-Repo Upstream Sync

## Goal

Use this skill when the real source repo lives outside the control repo and the control repo tracks it through a sibling checkout.

Default example:

- upstream repo: `/Users/shenlan/workspaces/cloud-neutral-toolkit/accounts.svc.plus`
- sibling checkout: `/Users/shenlan/workspaces/cloud-neutral-toolkit/accounts.svc.plus`
- control repo: `/Users/shenlan/workspaces/cloud-neutral-toolkit/github-org-cloud-neutral-toolkit`

## Required Order

Always execute in this order:

1. fix the upstream repo
2. commit and push the upstream repo
3. verify the control-plane reference in the control repo
4. commit and push the control repo pointer change

Do not make the primary code change only inside the control repo metadata checkout. The sibling repo is the source of truth.

## Preconditions

Before editing:

- confirm the upstream repo path
- confirm the sibling checkout path
- confirm the target branch for the upstream repo
- confirm the control repo branch
- inspect `git status --short` in all three working trees

If the task involves env vars, tokens, passwords, keys, or secret files, also follow [../env-secrets-governance/SKILL.md](../env-secrets-governance/SKILL.md).

## Execution Workflow

### 1) Fix the upstream repo

Work in the standalone upstream repo first.

Example:

```bash
cd /Users/shenlan/workspaces/cloud-neutral-toolkit/accounts.svc.plus
git checkout main
git pull --ff-only origin main
```

Make the code change there, not in the control repo metadata checkout.

Run the narrowest relevant validation first, then the broader package-level validation if needed.

### 2) Commit and push the upstream repo

Use Conventional Commits.

Example:

```bash
git add <files>
git commit -m "fix(accounts): ensure tenant schema exists before bootstrap"
git push origin main
```

Record the pushed commit SHA because the control repo will need to reference it.

### 3) Verify the control-plane reference

Move to the sibling repo path and confirm it is on the pushed upstream branch tip.

Example:

```bash
cd /Users/shenlan/workspaces/cloud-neutral-toolkit/accounts.svc.plus
git fetch origin --prune
git checkout main
git pull --ff-only origin main
```

Verify the sibling checkout now points at the intended upstream commit:

```bash
git rev-parse HEAD
```

### 4) Commit and push the control repo

Commit only the control-plane metadata change in the control repo unless the task explicitly also updates docs or governance files there.

Example:

```bash
cd /Users/shenlan/workspaces/cloud-neutral-toolkit/github-org-cloud-neutral-toolkit
git add config/single-node-release/repositories.json
git commit -m "chore(release): update accounts.svc.plus reference"
git push origin main
```

## Verification

Run these checks before closing the task:

### Upstream repo

```bash
cd /Users/shenlan/workspaces/cloud-neutral-toolkit/accounts.svc.plus
git status --short
git rev-parse HEAD
git log --oneline -1
```

### Sibling checkout

```bash
cd /Users/shenlan/workspaces/cloud-neutral-toolkit/accounts.svc.plus
git status --short
git rev-parse HEAD
```

From haitaopanhq/.github, Apache-2.0.

More from haitaopanhq/.github