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.
Is this for you?
Section titled “Is this for you?”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.
The two repositories
Section titled “The two repositories”| 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 |
Decide placement before architecture
Section titled “Decide placement before architecture”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/acmecore. 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.
Enforce it with check-edition-boundary.sh
Section titled “Enforce it with check-edition-boundary.sh”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_enterprisepackage: acme-enterprisepackage: @acme/enterprise
# Prose that legitimately mentions the enterprise edition.exclude: docs/**exclude: CHANGELOG.mdexclude: 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_ssois not caught bypackage: acme_enterprise; give it its ownpackage: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
.gitattributesmarking a filebinaryor-diffalso 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.
Licensing and the Confidential banner
Section titled “Licensing and the Confidential banner”- The core: Apache-2.0 plus a
NOTICEfile, as/kickoffleaves the template’sLICENSE. - The enterprise edition: a proprietary
LICENSE. Use the same text/kickoffwrites 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.
Labels
Section titled “Labels”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.
Set it up
Section titled “Set it up”- Run
/kickoffand choose Open core. /kickoffwritesedition-boundary.confwith the enterprise package names you gave and runsmake check-edition-boundary. Without/kickoff, write the file by hand and run the check. Until it exists,make customizeflags the uncommented section as unenforced./kickoffcreates theenterprise-boundaryandenterprise-extension-pointlabels on a GitLab project. Create them by hand otherwise.- Create the private enterprise repository with a proprietary
LICENSEand a “Confidential” banner in its README. - Set up the one-way mirror from the core into the enterprise repository.
- Ship the first extension point in the core, in its own MR, before the first enterprise feature that needs it.