---
title: "Core concepts"
description: "How organizations, repos, and the extension registry fit together in Bedrock."
---

> Documentation Index
> Fetch the complete documentation index at: https://marketing--pr-1329.buildr-bedrock-preview.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Core concepts

Bedrock separates shared tenant administration from version-controlled operational data. An organization has two shared parts that are not versioned: the **org** itself and the **registry** of published extension versions. Below them sits a flat set of **repos**. Every repo is an independent version-controlled database, and extensions carry shared standards and behavior between them.

## System pieces

The data model has five distinct pieces:

| Piece | Versioned | What it holds |
| --- | --- | --- |
| Org | No | Members, groups, policies, third-party connections, OAuth clients, and the list of repos |
| Registry | No, but every entry is immutable | Releases and prereleases of extensions from repos in the org |
| Repo | Yes, one commit DAG each | Custom models, custom fields, records, tag families, tags, CI checks, agent instructions and skills, extension source files, and installation pins |
| Extension | Yes, by release | Custom models, tag families, CI checks, tools, schedules, triggers, webhooks, workflows, third-party connection requirements, and browser UI |
| Installation | The release pin and schedule settings are versioned, and runtime state is not | Which release a repo runs on `main`, which of its schedules are on, its connection bindings, its webhook subscriptions, and its schedule, trigger, webhook, and workflow runs |

## Organizations

An org is the top-level tenant boundary. Bedrock keeps org state outside any commit history for a security reason: reverting a commit or creating a branch must never undo a revoked membership or restore a deleted credential.

An org manages five shared resources:

- **Members**: An org's owners bypass its policies. Every other member does what the org's policies allow; a new org gives every member its Editor policy, which reads the org, its member list, its registry, and its providers, and works on the records and branches of every repo. Changing schema, publishing or installing extensions, calling tools, running automations, managing connections, and the org's own actions, such as renaming it or adding members, take a policy of their own, which a new org gives no member. Only an owner makes another member an owner.
- **Groups**: A group is a named set of the org's members, such as Finance, HR, or Project managers. A job role such as "project manager" is a group too, while owning the org is not. Groups don't nest, and a group's name is unique in the org regardless of case, so `Finance` and `finance` can't both exist. Any member can read the groups, who is in each, and which groups a member is in. Org owners, and members whom a policy allows `manageGroups`, create, rename, and delete groups and add or remove their members. Only members of the org can join its groups: removing someone from the org removes them from its groups, and deleting a group ends every membership in it and frees its name. Bedrock keeps deleted groups and ended memberships as a record of who was in each group and when.
- **Repos**: The org keeps a flat list of repos. Repos have no parent-child hierarchy, and there is no special template or org-level database.
- **Connections and OAuth clients**: Third-party credentials, such as a Linear or Stripe OAuth grant or an API token, live in the org so that the team connects a service once and binds that connection to individual repos. A connection's `audience` is `org` by default, which lets every member use it. A `user` connection is for the person who connected it alone.
- **The extension registry**: Every commit that changes an extension publishes it, and the org registry records the immutable version. Any repo in the org can inspect or install a release.

```sh
# Create an organization
bedrock orgs create-org --data '{"name":"Acme Corp"}'

# List members of the organization
bedrock orgs list-members --org "$ORG"

# Put a member in a group
bedrock groups create-group --org "$ORG" --data '{"name":"Finance"}'
bedrock groups create-group-member --org "$ORG" --group "$GROUP" --data '{"user_id":"'"$USER_ID"'"}'

# Create a repo inside the organization
bedrock repos create-repo --org "$ORG" --data '{"name":"North America Operations","idempotency_key":"na-ops-creation-1"}'
```

To retry a repo creation safely, pass the same `idempotency_key`. Reusing a key with the same repo name returns the repo that the first call created, whereas reusing a key with a different name fails with `RepoCreationConflict`.

## Repos

Each repo is its own database, and Bedrock applies a repo's writes one at a time, so two commits to a repo never interleave.

Who reads and writes a repo's records and schema is a policy over `read` on the repo and the actions on its models. The Editor policy a new org ships lets every member work in every repo, and an org or repo policy narrows that, down to single records. Permissions explains how policies decide.

A single repo can hold any combination of five things:

- **Business records**: The rows of custom models, such as orders, invoices, vendors, employees, or budgets, along with their tag memberships and file attachments.
- **Repo-owned schema and checks**: Custom models, custom fields, tag families, tags, and CI checks created directly for that repo.
- **Extension source**: Declarations of extensions, their schema and tag families, and their TypeScript and UI source files, which each commit publishes to the org's registry.
- **Extension installations**: Pins to releases from the registry, which copy the extension's schema and tag families into the repo.
- **Agent instructions and skills**: `AGENTS.md` files and agent skills, which tell an agent how to work in the repo. The repo, each extension it defines, and each extension it installs can hold some. They're versioned like the rest of the repo, and `bedrock agent-instructions` and `bedrock agent-skills` read and write them.

### Repo copies

To start a repo from another one, an org owner copies it. `bedrock repos create-copy` (`POST /repos/:repo_id/copies`) copies everything the repo holds into a repo under a new name in the same org. Its policies stay with the source repo. The copy holds every branch and its history as they stood when the copy started, and keeps no link to the repo it came from. The call answers `202` at once while the copy runs, and `bedrock repos get-copy` (`GET /orgs/:org_id/repo-copies/:repo_id`) says whether the copy is still copying, ready, or failed. Reusing the same `idempotency_key` resumes the same copy.

```sh
bedrock repos create-copy --repo "$REPO" --data '{"name":"West Operations","idempotency_key":"west-ops-copy-1"}'
bedrock repos get-copy --org "$ORG" --repo "$COPY"
```

### Archived repos

Someone with `update` on a repo, such as an org owner, archives it when the team no longer works in it. An archived repo keeps all of its data and history and answers every read, but it takes no writes: commits, branches, records, schema, and installations all fail with `RepoArchived`. It also runs none of its extensions' tools, including its schedules. A workflow run writes to its repo until it ends, so nobody can archive a repo while any of its runs is queued, running, or waiting: the archive fails with `RepoWorkflowRunsActive` until the runs end or a member terminates them. The repo records who archived it and when, as `archived_by_id` and `archived_at`. Unarchiving the repo, which takes `update` on it too, makes it writable again and clears both.

An archived repo drops out of `bedrock repos list-repos`, which shows it again with `--archived`. Extensions that the repo publishes keep their names, and repos that installed one of their releases keep running and updating it, but no other repo can install one of them until the repo is unarchived.

```sh
bedrock repos update-repo --repo "$REPO" --data '{"archived":true}'
bedrock repos list-repos --org "$ORG" --archived
bedrock repos update-repo --repo "$REPO" --data '{"archived":false}'
```

## The registry

The registry is the org-wide catalog of published extension versions. Any member of the org can browse the registry's releases and inspect them, even if that user can't read the repo that published the extension.

Every entry in the registry follows semantic versioning and is permanent:

- Every commit that changes an extension adds a version to the registry, along with its build and its catalog of custom models, tag families, CI checks, tools, schedules, triggers, webhooks, workflows, providers, requirements, and whether it has a UI.
- A commit to `main` that raises the extension's version above its latest release adds a release, `MAJOR.MINOR.PATCH`, which any repo in the org can install. Each release must be strictly higher than the extension's latest release.
- Every other commit adds a prerelease, `MAJOR.MINOR.PATCH-pre.<commit>`, which only the repo that defines the extension runs. The registry lists only releases to other repos, and `bedrock registry get-extension-version` refuses a prerelease.
- The repo that first publishes an extension name owns that name across the org. No other repo in the org can publish under the same name.

Source: https://marketing--pr-1329.buildr-bedrock-preview.dev/docs/index.mdx