Skip to content

Sharing one knowledge bundle on two branches

This is a blueprint

The concrete, copyable artefact a decision produced.

The shape a knowledge bundle takes once more than one person files into it, produced by Federating my knowledge base as privacy-tiered OKF bundles and shipped in federated-knowledge-skills v0.2.0. The bundle you are reading runs it, and so does one shared with an employer's team.

The constraint it answers: a bundle anyone publishes from has a default branch that takes no direct pushes, so a change reaches it through a pull request and a review. That gate is measured in days. The knowledge it gates is written in minutes.

Manifest - what is assembled

Two branches, each with one job.

the default branch the shared branch
Holds what has been reviewed, and what the site is built from everything reviewed, plus what is not ready
Protected yes: pull request and review no: open to anyone with write access
Who works here nobody directly every checkout, every agent
Reaches the other by a release pull request, on a cadence a merge, after every change to the default
  • Merge commits only, on both routes. Squash and rebase merging write a new commit with the same content and no shared ancestry, so the two branches stop knowing they ever met. The next release then re-displays everything already released.
  • One manifest field, sync: staging, naming the branch this machine's checkout belongs on. It says three things at once: check this branch out, commits here may leave the machine, and somebody else is writing here so read it fresh.
  • A reusable merge-back workflow, called by the bundle on every push to the default branch and pinned by full commit SHA:
on:
  push:
    branches: [main]

jobs:
  merge_back:
    uses: ftschindler/federated-knowledge-skills/.github/workflows/merge-back.yml@<sha>
    with:
      branch: staging
    permissions:
      contents: write
      pull-requests: write
  • The governance checks run on the shared branch too, not only on pull requests. A page edited in the forge's web editor has no working copy, so the bundle's own pre-commit hooks never ran on it, and the shared branch is where such a change lands first.

Principles it instantiates

Pin GitHub Actions to full commit SHAs, which matters more here than usual: this workflow holds write access to the shared branch. Grant least-privilege CI permissions at both workflow and job level, Guard invariants at commit-time, not review-time and Mirror every local guard in CI, which is what the web-editor case above is. The branch shape itself is Give a shared repository two clocks when review is slower than the work.

One principle this departs from on purpose: Keep a linear history cannot hold where two long-lived branches have to keep meeting. Shared ancestry is the thing being protected, and a merge commit is what records it.

Operating manual

  • Before reading the bundle, fkb sync <bundle>. This is what stops an answer coming from a page a teammate corrected this morning.
  • After filing, commit through the bundle's hooks, then fkb sync <bundle> again. Pushing is part of filing here in the way committing is.
  • The command refuses rather than resolves. It does not stash, switch branches or finish a rebase. Uncommitted work in the tree, a checkout on another branch, a conflict: the commit stands, nothing is pushed, and the reason is one line of output. An unpushed commit costs a teammate an hour's delay; a guess about whose work was in the tree costs the work.
  • Cutting a release is gh pr create from the shared branch to the default one, on whatever cadence suits. Nothing automates it, because a command that did would put a forge inside the CLI.

What it costs

A concept is shared with the team before it is reachable by URL. It sits on the shared branch, where every checkout sees it, whilst the site still carries the last release. A cross-bundle citation written today therefore points at a page the world cannot open yet, and nothing detects this: the link checker asks whether the file exists on this disk, and it does.

A conflict stops the machine every time. Two people writing the same concept is a question about what is true, which is the last thing to hand to an agent working quickly.

The following pages link to this page: