| name | rebase-onto-upstream |
| description | Rebases this Tenstorrent fork of terraform-provider-netbox onto the latest e-breuninger upstream and cuts a new release. Use when the user asks to rebase onto upstream, sync with upstream, pull in upstream changes, update from e-breuninger, or release a new version of the fork. |
Rebase onto upstream
This skill encodes the full workflow for bringing the tenstorrent/terraform-provider-netbox fork up to date with e-breuninger/terraform-provider-netbox (the upstream) and producing a verified release.
The fork also depends on a second fork: msollanych-tt/go-netbox of fbreckle/go-netbox, wired in via a replace directive in go.mod. Both forks must be rebased together, in order. See AGENTS.md at the provider repo root for the full fork-management context.
Preconditions
- Both repos are present locally and clean (
git status shows no changes):
terraform-provider-netbox with remotes origin = tenstorrent/... and upstream = e-breuninger/...go-netbox (typically a sibling directory) with origin = msollanych-tt/... and upstream = fbreckle/...
gh CLI authenticated against both forks- Go 1.25+ installed locally
- The user has approved doing the rebase now (don't start without confirmation)
Workflow
Track progress with this checklist:
- [ ] Phase 1: rebase go-netbox master onto upstream/master
- [ ] Phase 1: push and tag new go-netbox version
- [ ] Phase 2: create rebase branch off upstream/master
- [ ] Phase 2: cherry-pick our patches in order, resolve conflicts
- [ ] Phase 2: bump go.mod replace to new go-netbox tag, go mod tidy
- [ ] Phase 2: verify build (go vet, go build, go test -short)
- [ ] Phase 2: push branch + prerelease tag, watch goreleaser CI
- [ ] Phase 2: validate prerelease binary against a real NetBox
- [ ] Phase 3: fast-forward master, push real tag
- [ ] Update AGENTS.md "state at last rebase" section
Phase 1 — Rebase go-netbox first
Order matters: upstream provider features sometimes depend on recent go-netbox changes (e.g. v2 token support depended on WritableToken.Expires omitempty removal).
cd ../go-netbox
git fetch upstream
git checkout master
git rebase upstream/master
Resolve conflicts on our patches. Our changes touch model files (e.g. WritableAvailableIP); upstream changes are usually generated client/model deltas elsewhere.
git push --force-with-lease origin master
git tag -a vX.Y.Z -m "Rebased onto upstream <sha>"
git push origin vX.Y.Z
X.Y.Z should bump the minor version (e.g. v0.3.0 → v0.4.0). Earlier tags used a -tenant-fix suffix; clean tags going forward. Force-pushing master is fine because the provider pins by tag, not branch.
Phase 2 — Rebase the provider
cd ../terraform-provider-netbox
git fetch upstream
git checkout -b rebase-onto-upstream-<MMMYYYY> upstream/master
Cherry-pick our patches in their original order. Get the list with:
git log --oneline master ^upstream/master
Read it bottom-up (oldest first) and cherry-pick in that order:
git cherry-pick <oldest-sha>
git cherry-pick <next-sha>
Conflict resolution rules
go.sum conflicts every time. Resolve with git checkout --ours go.sum && git add go.sum. It will be regenerated by go mod tidy later.netbox/resource_netbox_available_ip_address.go is the file most likely to have real conflicts (both we and upstream actively touch it). Read both sides, preserve upstream's additions (e.g. custom_fields, DNS case suppression) and our additions (tenant_id) together.netbox/resource_netbox_service.go may conflict if upstream touched parent-object handling.- Cherry-picks sometimes leave stray braces or whitespace. Always run
go vet ./... after the cherry-picks.
Bump go-netbox dep
After all cherry-picks land, edit go.mod:
replace github.com/fbreckle/go-netbox => github.com/msollanych-tt/go-netbox vX.Y.Z
Use the new tag from Phase 1. Then:
go mod tidy
Verify locally
go vet ./...
go build ./...
go test -count=1 -short ./netbox/...
If any of these fail, fix them on this branch — either as a new commit or by amending the last cherry-pick. Do not go back and try to amend earlier cherry-picks; the history will get tangled.
If you fix anything in the test file or other patch-related files, amend into the most recent cherry-pick:
git add <files>
git commit --amend --no-edit
Push branch
git push -u origin rebase-onto-upstream-<MMMYYYY>
(Optional) prerelease tag
The release pipeline is the only place we have full cross-platform build coverage. For risky rebases or first-time releases, push an rc tag to dry-run the build:
git tag -a vA.B.C-rc1 -m "Prerelease, rebased on upstream <sha>"
git push origin vA.B.C-rc1
Most of the time you can skip this — dev_overrides against a real NetBox already validated the same code, and the release pipeline either builds or it doesn't (it's deterministic).
Caveat: prerelease tags don't satisfy ~> 5 constraints downstream (SemVer rule). To smoke-test from the registry you'd need to pin exactly. The dev_overrides path is usually faster.
Phase 3 — Cut the real tag
Once the rebase branch passes locally and (optionally) the rc build is green:
git checkout master
git merge --ff-only rebase-onto-upstream-<MMMYYYY>
git push origin master
git tag -a vA.B.C -m "Rebased on upstream <sha> + tenstorrent patches"
git push origin vA.B.C
Watch the release workflow:
gh run watch <run-id> --repo tenstorrent/terraform-provider-netbox --exit-status
Or list runs to find it:
gh run list --repo tenstorrent/terraform-provider-netbox --limit 5
The build takes ~6 minutes. On success, verify all artifacts published:
gh release view vA.B.C --repo tenstorrent/terraform-provider-netbox
Should show zips for darwin/linux/windows × arm64/amd64/386 plus SHA256SUMS + signature.
If the build fails on the real tag, you can't reuse the tag — bump the patch (vA.B.D) and try again. (This is part of why the optional rc step exists.)
Tag scheme: plain vA.B.C semver, monotonically increasing from our own release history. Don't anchor to upstream's version. Confirm with the user what the next patch number should be before tagging.
Phase 4 — Update AGENTS.md
Edit the "Quick reference: state at last rebase" section in AGENTS.md to reflect the new state:
- Upstream sha rebased onto
- Latest go-netbox tag
- Latest provider release tag
Commit this on master:
git add AGENTS.md
git commit -m "docs: update AGENTS.md state at rebase to <new-tag>"
git push origin master
What to never do
- Never push to
upstream on either repo (you don't have permission).
- Never edit
go.sum by hand — always regenerate with go mod tidy.
- Never reuse a published version tag.
- Never tag without explicit user confirmation of the next patch number to use.
- Never include the
replace directive, the release-workflow tweak, or AGENTS.md in a PR opened against upstream e-breuninger.
Cleanup (optional)
After a successful rebase, old rebase-onto-upstream-<old-month> branches can be deleted:
git push origin --delete rebase-onto-upstream-<old-month>
git branch -d rebase-onto-upstream-<old-month>
Confirm with the user before deleting.
Reference
For the broader fork-management context (why two forks exist, what each carried patch does, what's upstreamable, local dev setup), see AGENTS.md at the provider repo root.
