Skip to content

Open core and editions

The big picture: an open-core project ships a public, Apache-2.0 core and sells an enterprise edition from a separate private repository. The rule that keeps this workable is one-directional: the enterprise edition depends on the core, and the core never knows the enterprise edition exists. Visiban and TruePPM are both built this way.

Why it matters: the first import of an enterprise package into the core couples the public tree to private code. Nothing fails when it happens, and from then on the core cannot be built or published without the private repository. A placement decision made after implementation means moving code between repositories, which is the expensive direction.

If one team ships one product from one repository under one license, skip this guide. Choose Open source or Private at /kickoff and delete the open-core block from AGENTS.md.

This guide applies when you intend to publish a core under an open-source license and sell or privately maintain an enterprise edition on top of it. /kickoff asks the license question; choosing Open core: Apache-2.0 core plus a separate enterprise edition keeps the Apache-2.0 LICENSE and uncomments the Open core vs. enterprise boundary section of AGENTS.md. The rest of this guide is what that choice commits you to.

Repository Visibility License Contents Banner
The core (for example acme/acme) Public Apache-2.0 plus a NOTICE file Everything a small team needs to use the product end to end, plus the extension points None
The enterprise edition (for example acme/acme-enterprise) Private Proprietary Enterprise features that register against the core’s extension points “Confidential” at the top of the README

Ask one question of every feature: “Can a small team work together effectively without this?”

  • No: it belongs in the core.
  • Yes: it is an enterprise candidate. Typical candidates are SSO/SAML, audit logs, advanced analytics, automation rules, multi-tenancy, white-labeling and compliance tooling.

Record the answer on the issue and label it enterprise-boundary when the feature sits on or near the line. Do this before the architecture review, not after it: the architect agent checks for a recorded placement on open-core projects, and treats a missing one as blocking. Moving a feature between repositories after implementation means rewriting its imports, its tests and its release path in two places.

The boundary: the core never imports the enterprise edition

Section titled “The boundary: the core never imports the enterprise edition”

No import, require, or string reference to the enterprise package appears anywhere in the scanned tree (everything tracked except the configured excludes). That includes tests, fixtures, dependency files and settings entries such as an INSTALLED_APPS line. If the core needs something the enterprise edition provides, the core defines the interface and the enterprise edition implements it.

Extension points: the enterprise edition registers, never patches

Section titled “Extension points: the enterprise edition registers, never patches”

The enterprise edition plugs into hooks the core exposes. It never edits, vendors, or monkey-patches core files. A generic sketch, using acme throughout:

  • Settings includes. The core’s settings load an optional extra module named by an environment variable; the enterprise edition ships that module and adds its apps and middleware there.
  • URL patterns. The core mounts any extra URL configuration the deployment names; the enterprise edition supplies its routes in that module.
  • Hooks. The core defines registries (for example a list of permission checks or export formats) with a register() call; the enterprise edition calls it at startup.

When a feature needs a hook that does not exist, add the extension point to the core first, in its own MR, labeled enterprise-extension-point. The enterprise feature lands afterward against a released or pinned core version.

The enterprise code never modifies or forks core files: it builds against a pinned core version (a tag or an exact commit), supplied by a read-only mirror of the core (see below), and registers through the extension points. Paste something like this into the enterprise repository’s own AGENTS.md:

This repository is the private enterprise edition of the open-source acme/acme core. It registers against the core’s extension points and never modifies, vendors, or monkey-patches core files. If a feature needs a hook the core lacks, add the hook to the core in its own MR first. Do not copy enterprise code into the core.

scripts/check-edition-boundary.sh fails when the core names an enterprise package. TruePPM runs the same idea as a CI grep for its enterprise package name, with a self-test. The gate is a no-op until you opt in by adding edition-boundary.conf at the repository root:

# Packages the open-source tree must never name.
package: acme_enterprise
package: acme-enterprise
package: @acme/enterprise
# Prose that legitimately mentions the enterprise edition.
exclude: docs/**
exclude: CHANGELOG.md
exclude: changelog.d/**

When you choose Open core, /kickoff asks for the enterprise package name(s) and writes this file for you (scripts/write-edition-boundary.sh): package: lines only, no exclude: lines, because a stale exclude fails the gate. It then runs the gate once. If the open-core section in AGENTS.md is uncommented and no edition-boundary.conf exists, make customize lists it under “Needs your stack”.

What counts as a match. Any whole-word, literal occurrence of a configured identifier in a tracked, non-binary file outside the exclusions: an import, a require, a Go import path, a string reference, a dependency-file line. There is no language parsing. Whole-word means acme_enterprise_tools does not match acme_enterprise, and the identifier is literal, so acme.enterprise does not match acmeXenterprise.

Exclusions. exclude: takes a git glob path relative to the repository root. There are no default exclusions: tests and vendored code are scanned, because that is where an import hides. An exclude that matches no tracked file is an error, so a stale exclude cannot quietly hide a renamed path. The config file is always excluded.

Output and exit codes.

Exit Meaning
0 Clean, or not configured. Without a config the gate prints not configured (no edition-boundary.conf) — nothing checked and passes
1 A reference to an enterprise package, a malformed config, a stale exclude, or zero files scanned
2 The gate could not run: no git, not a work tree, a git error, or an unreadable config

Once the config is valid, git is usable and every exclude matches a file, a run prints scanned <m> tracked file(s) for <n> package(s) before its verdict, so a scan that covered nothing is visible. (A missing, comment-only or malformed config, a stale exclude, a missing work tree and a git error stop before that line.) A config path you name explicitly that does not exist exits 2, so a typo cannot pass as “not configured”. If the exclusions cover every tracked file the gate fails instead of reporting a green it did not earn.

Discovery. bash scripts/check-edition-boundary.sh --list prints the configured packages, each exclude with the number of files it matches, and every in-scope path. It never judges. --self-test proves the gate can still fail; CI runs it before the real scan, on the same image.

What it cannot see. Read these before trusting a green run:

  • a sibling package. Matching is whole-word, so acme_enterprise_sso is not caught by package: acme_enterprise; give it its own package: line. A plain grep would catch it, so this is a false negative on the dangerous side;
  • a different capitalization. Matching is case-sensitive;
  • symlink targets, tracked directory and file names, and submodule contents. A submodule is one tracked entry, so it also inflates the “scanned” count;
  • names built at runtime;
  • copied code that does not carry the package name;
  • a transitive import through a third package that re-exports the enterprise one;
  • untracked files, and binary files (by content). On git older than 2.40 a tracked .gitattributes marking a file binary or -diff also exempts it, and the gate prints a notice; newer git ignores those attributes;
  • the enterprise repository vendoring the core, which is the opposite direction.

It runs in make pre-push-checks and in the edition-boundary CI job.

Mirror the core into the enterprise repository

Section titled “Mirror the core into the enterprise repository”

Visiban push-mirrors the core into the enterprise repository. The direction is one-way: core to enterprise, never back. The mirror is a read-only copy of the core that the enterprise code builds against; it is not a fork, and nothing in it is edited on the enterprise side.

A GitLab push mirror overwrites branches that have diverged on the receiving side unless Keep divergent refs is turned on, so enable it before the first sync or an enterprise-only branch can be lost. Mirror setup is covered by GitLab’s push mirror documentation, and the click-through for a one-way mirror is the same as in Publishing to GitHub. Decide the branch and tag layout in the enterprise repository yourself and write it down in that repository’s README.

  • The core: Apache-2.0 plus a NOTICE file, as /kickoff leaves the template’s LICENSE.
  • The enterprise edition: a proprietary LICENSE. Use the same text /kickoff writes for its Private option: Copyright <year> <holder>. All rights reserved. plus one line saying no license is granted.
  • A “Confidential” banner at the top of the enterprise README, so nobody copies a file from it into the public core.

Governance files follow the same split: the core repository’s (GOVERNANCE, CONTRIBUTING, SECURITY) are public, and the enterprise repository’s are private.

This guide is not legal advice. Have a lawyer review the license text before you sell anything.

Two issue labels carry the boundary through the tracker, matching what TruePPM uses:

  • enterprise-boundary: the issue’s placement is on or near the open-core line, and the decision is recorded on it.
  • enterprise-extension-point: the change adds or alters a hook in the core that the enterprise edition will use.

/kickoff creates these two labels on the GitLab project when you choose Open core (scripts/gitlab-bootstrap.sh labels --open-core-labels); a single-edition project never gets them. Without a GitLab project, or on a group layout where labels are made on the group first, create them by hand.

  1. Run /kickoff and choose Open core.
  2. /kickoff writes edition-boundary.conf with the enterprise package names you gave and runs make check-edition-boundary. Without /kickoff, write the file by hand and run the check. Until it exists, make customize flags the uncommented section as unenforced.
  3. /kickoff creates the enterprise-boundary and enterprise-extension-point labels on a GitLab project. Create them by hand otherwise.
  4. Create the private enterprise repository with a proprietary LICENSE and a “Confidential” banner in its README.
  5. Set up the one-way mirror from the core into the enterprise repository.
  6. Ship the first extension point in the core, in its own MR, before the first enterprise feature that needs it.