Skip to content

Rebase the UniFi forks onto upstream

We move both UniFi forks from their 2026-08 base onto upstream main, re-carry our own work as a short patch series, and release the result as provider 0.60.0-fzymgc.1. The approach is a replay, not a git rebase. Each fork commit is re-applied by hand on a branch cut from upstream. Commits that upstream now covers are dropped. The riskiest assumption is that upstream’s state upgraders accept the state our fork wrote, so that tf/unifi plans no change after only a configuration rewrite.

Sean chose this path on 2026-10-16 over two alternatives: stay diverged and regenerate the models ourselves, or stay diverged and hand-patch only what the site uses. The audit that led to the choice is in the engram records dyg0yg2mkg and zkqn6atzr4. The facts it rests on are restated below.

Repository Our base Upstream main Distance
fzymgc-house/go-unifi branch fzymgc ead9900 plus 10 commits f52a177 (v1.36.0, models regenerated from Network 10.6.101) 18 upstream commits
fzymgc-house/terraform-provider-unifi branch fzymgc c16b66a plus 24 commits 647cf534 (after v0.60.0-beta.0) 69 upstream commits

Upstream builds again. It regenerated the go-unifi models for Network 10.x, migrated the provider to them, nested the prefixed attributes into objects, and shipped a state upgrader for every nested resource. Our fork’s go-unifi models every key on every adopted collection. Upstream’s regenerated models lack 12 keys we added by hand. Our fork also carries behavior upstream does not have: unifi_device_ports, the raw Do request method, keep-live-keys-on-update for WLAN, WAN, BGP and network, the radio table booleans as pointers, the radio_ai setting block, rrm_enabled, passphrase_wo_version and dhcp_v6_server.allow_slaac.

Section 1. Decisions you will want to tweak

Section titled “Section 1. Decisions you will want to tweak”

D1. Replay, not rebase. We cut fzymgc-next from upstream main in each repository and re-apply our commits as a fresh series. A git rebase of 24 commits across a schema that upstream restructured would conflict in every resource file. Changing this later costs nothing before work starts and everything after.

D2. Version 0.60.0-fzymgc.1. Upstream’s next release is 0.60.0, now at beta.0. The runbook names versions <next-upstream-minor>-fzymgc.<n>. The alternative is 0.61.0-fzymgc.1, which leaves room if upstream tags 0.60.0 before we release. The pin is exact, so the choice costs one line in tf/unifi/versions.tf either way. Decided 2026-10-16: 0.60.0-fzymgc.1.

D3. Hand-added keys move into the generator. The 12 keys that upstream’s regeneration lacks (networkconf external_id, ipv6_enabled, routing_table_id, portconf tagged_networkconf_ids, wlanconf external_id, passphrase_autogenerated, short_id, apgroups for_wlanconf, bgp error, redistribute_to_sd_wan, firewall-zone cloud_template, external_id, firewall-policies origin_id, radio_ai auto_enabled) are injected in cmd/fields/main.go and cmd/fields/custom/*.json, as upstream does for mdns_enabled. Then we regenerate from the 10.6.106 package. The alternative is to patch the generated files by hand, as the fork did until now. The generator route costs more once and nothing on every later regeneration.

D4. unifi_device_ports follows upstream’s port_override shape. Upstream nests five groups inside a port: dot1x, egress_rate_limit, lldpmed, port_security and stormctrl. Our resource adopts the same five objects, with a state upgrader from the flat keys. Keys that upstream has no shape for yet (stp_edge_state, stp_bpdu_guard_enabled, multicast_router_mode, lag_idx, sd_wan_underlay_port) stay flat until upstream gives them one. In tf/unifi, three ports change dot1x_ctrl and dot1x_idle_timeout into dot1x = { ctrl, idle_timeout }. The alternative was to keep every key flat, which is cheaper now and diverges from upstream for good. Decided 2026-10-16: follow upstream.

D5. Adopt upstream’s nested shapes everywhere else. tf/unifi changes: ipv6_* on 7 networks becomes an ipv6 object, dhcp_v6_server.dns_auto becomes dns.auto, wpa_mode, wpa3_* and ap_group_ids on 4 WLANs become wpa, wpa3 and ap_group objects, dot1x_idle_timeout and lldpmed_* on 4 port profiles become objects, mgmt.auto_upgrade* and syslog.netconsole_*, syslog.this_controller* in settings.tf become objects. Our flat roaming_assistant_*_enabled and *_rssi attributes are dropped for upstream’s nested roaming_assistant_na and roaming_assistant_6e. rrm_enabled has no upstream form and stays flat. The alternative, a compatibility layer that accepts both shapes, doubles every schema and is not worth it for one site. Decided 2026-10-16: adopt upstream’s shapes, drop our flat roaming assistant attributes.

D6. Keep-live-keys-on-update is re-carried. Upstream issue #583 shows unifi_wlan at 0.59.0 still zeroes fields it does not model on update. Our read-then-overlay code for WLAN, WAN, BGP and network is re-applied on the new base. The alternative is to trust upstream’s per-field fixes. The field audit gate below is what tells us which one holds.

D7. Branch mechanics. Work lands on fzymgc-next and is reviewed there. Then fzymgc is reset to the new series with a force push, and the release tag is cut from its head. The old commits stay reachable through the existing v0.56.0-fzymgc.* tags. The alternative was a merge commit into fzymgc, which keeps two unrelated histories in one branch. Decided 2026-10-16: reset.

D8. The Integration API is a second plan. DNS policies, policy ordering, traffic matching lists and vouchers exist only on the official API, which needs an API key that Vault does not hold. This plan does not touch it.

U1. State upgraders and our schema versions. Upstream’s upgraders map from upstream’s prior schema versions. If a fork commit bumped a resource’s schema version that upstream did not, the upgrader map misses and terraform plan fails with “no upgrade function”. Default: before release, compare every resource’s Version between the fork at v0.56.0-fzymgc.16 and the new series, and add a passthrough upgrader where they differ. Signal to pivot: the speculative plan errors on refresh.

U2. Generator conflicts. Upstream cleaned the generator (e70afb4) and repaired the 10.x fallout (91a2ea4). Our injections land on that code. Default: regenerate from the cached 10.6.106 package and expect only the files that carry our keys to change. Signal: the regeneration diff touches files outside that set.

U3. Static defaults on adopted objects. Upstream issue #544 names 138 Optional+Computed attributes with static defaults that overwrite the controller’s value. Upstream fixed some in 0.59.0. Default: the tf/unifi speculative plan is the detector. Signal: a planned change on an attribute the configuration does not declare.

U4. The demo controller. The provider’s acceptance tests run a demo-mode controller in Docker. It does not run Network 10.6.106. Default: unit tests and acceptance tests gate the fork pull requests, and the live speculative plan gates the release.

U5. Dropped commits. Four fork commits have an upstream counterpart that is close but not identical: the vlan-only import (a9214fc5, upstream #525), the global_switch block (283ab7b3, upstream #513), setting import reads every section (3605939b) and the two inconsistent-result fixes (df1e37e3). Default: drop each and rely on upstream. Signal: a failing unit test from the fork, or a planned change on a tf/unifi object, brings the commit back.

Each phase ends at a gate a person can run at a shell.

  1. go-unifi. Cut fzymgc-next from upstream/main. Re-apply do.go and its tests. Move the 12 keys and the pointer booleans (radio_table bools, mesh_sta_vap_enabled, switch_vlan_enabled, fork issue #24) into the generator. Merge our custom/*.json with upstream’s. Run go run ./cmd/fields -output-dir unifi 10.6.106. Re-apply the network_encode.go changes and controller_fields_test.go. Gate: go test ./... passes, and scripts/unifi-field-audit.py <dump> --go-unifi <checkout> --tier all prints no gap for every collection in tf/unifi and names at most 14 gapped collections.
  2. Provider. Cut fzymgc-next from upstream/main. Point the go.mod replace at the new go-unifi commit. Re-apply, in this order: the release configuration and the publish script, unifi_device_ports with the port action, keep-live-keys for network, WLAN, WAN and BGP, passphrase_wo_version, ipv6_setting_preference and allow_slaac, rrm_enabled, the radio_ai block, the radio table boolean send. Extend TestPlanUnchangedConfigIsEmpty to unifi_device_ports. Write the fork section of CHANGELOG.md. Gate: go build ./..., go test ./..., and the acceptance suite against the demo controller pass.
  3. Release. Reset fzymgc to the reviewed series, tag v0.60.0-fzymgc.1, build with .goreleaser.fzymgc.yml, sign and publish per docs/operations/terraform-provider-fork.md. Gate: terraform init in tf/unifi reports self-signed, key ID 7B381B811D6398AD.
  4. tf/unifi. One pull request: bump the pin, rewrite the attributes named in D5, run terraform providers lock -platform=linux_arm64 -platform=darwin_arm64, update docs/operations/terraform-provider-fork.md with the new base commits. Gate: the main-cluster-unifi speculative plan shows No changes. The rule stands: the pull request does not merge while the plan changes anything it does not declare.
  5. Close out. Close fork issue #24. Narrow fork issue #20 to the fixed mesh parent, because upstream covers the minimum data rate and the roaming assistant. Record the new bases in engram. Open the second plan for the Integration API and the exposure work from the audit.

Sean answered the four open questions on 2026-10-16. The answers are recorded next to D2, D4, D5 and D7 above. Work starts with phase 1.

Phases 1 to 3 landed on 2026-10-17. go-unifi fzymgc is at 4329be4 on upstream f52a177, and the provider fzymgc series is on upstream 647cf534. The release that tf/unifi pins is v0.60.0-fzymgc.4, not .1. The first speculative plan against .1 found five provider faults, and each took a fork release:

  • .2: unifi_network read ipv6.setting_preference as null on every refresh, and the upstream plan-time refusal of forward = "customize" on an untagged native network rejected the live AllServer profile. The controller keeps customize when tagged_vlan_mgmt is custom and a tagged network stays allowed.
  • .3: leaf defaults in the undeclared unifi_setting sections and the deprecated optional-only assisted_roaming_* leaves of unifi_device tripped the plan-change gate of the framework.
  • .4: Terraform core plans an optional and computed object from the configuration, which is null, when the prior object holds a non-null leaf the schema does not mark computed. country.code was Required.

The procedure that found the last two causes is in docs/operations/terraform-provider-fork.md, section “Find what trips a plan”. Phase 4 is pull request #3148, whose plan shows No changes. Fork issue #24 is closed. Fork issue #20 keeps the minimum data rate fields and the fixed mesh parent: upstream covers the roaming assistant, and the fork covers rrm_enabled, but neither has minrate_*_data_rate_kbps.