Developers, partners and operations from one repository

One shipment, three kinds of reader

A logistics business documents the same operation for people who should not read the same pages. A shipper's developer wants to know how to create a shipment through the API. A carrier needs the handover rules, cut-off times and the rate card for their lane. A dispatcher needs the exceptions playbook for when a parcel is lost. All of it describes the same shipments, and much of it is written by the same team, often next to the code.

The usual answers are one docs site with everything behind one login, or three tools in three places. The first shows partners your internal runbooks. The second means the same facts drift apart in three copies.

When we wrote the first industry setup for DocuGate, logistics, we chose a third shape: one repository, three folders, three spaces, each with its own access rule. It is written as data in src/data/industries.ts, and the same definition drives the industry page, the New space form, the prompt we give Claude for drafting pages, and the API key settings.

Which audience gets which access mode, and why

Space	Folder	Access	Why
Developers	docs/developers	Public	The people who would integrate are not yet your customers. Public docs are how they decide to become one.
Partners	docs/partners	Allowlist	Rate cards, lanes and contacts are commercial. Name the people allowed in and nobody else reads them.
Operations	docs/operations	Repository access	Internal procedures belong to the team. Whoever can open the repository reads them, with no list to keep in step.

The reasoning behind each mode is in how the modes work on the server.

Developers are public because gating integration docs makes the decision to integrate harder, and the API reference is the thing developers look for first.

Partners are on an allowlist because partners are outside your GitHub organisation and should stay there. An allowlist names GitHub logins or email addresses, and it is read with the owner's token, so a customs broker who signs in with Google reads the space without ever having a GitHub account. The list is kept in DocuGate's settings, not in the repository, because it is a list of other people's email addresses.

Operations follows repository access because staff already have access to the repository, and that list is maintained anyway, by whoever adds and removes people on GitHub. The space reads with each reader's own token, so GitHub decides, and someone who leaves the organisation loses the docs when they lose the repository.

The part the gate does not cover

This is the thing to understand before copying the setup. DocuGate's access rules apply to the published spaces. They do not apply to the repository. Anyone who can open the repository on GitHub can read docs/partners/ and docs/operations/ there directly.

So the repository has to be private, and that has consequences we would rather state than have someone discover:

• Publishing a private repository needs Pro. If the owner's plan lapses, the spaces pause until it is renewed.
• The public developer space is read with the owner's token. A private repository published openly is a deliberate choice, so the server reads it with the owner's stored credentials, and so is the partner space. If the owner disconnects DocuGate, those two stop until they reconnect. The operations space keeps working, because it reads with each reader's own token.
• Nothing from a private repository is cached. Every page view of every space, including the public one, is a live read from GitHub.
• Spaces from private repositories are never listed on Explore. The developer docs are public by link, not discoverable through DocuGate.
• Repository collaborators read everything. If some of your staff should not see partner rate cards, they should not be collaborators on that repository, and the setup is the wrong shape for you.

If any of these is unacceptable, the same three folders work in two repositories: the developer docs in a public one, the other two in a private one. You lose the single place to edit, which was the point, but nothing else.

Which pages to write first

Each audience comes with a list of pages, and the order is the order we think a new reader needs them. For developers it starts with an overview, a quickstart that goes from nothing to a shipment created in the sandbox and tracked to delivery, then shipments, the shipment lifecycle, tracking, rates, labels and documents, webhooks, errors, and an API changelog. Partners start with an onboarding checklist, integration specifications and service levels. Operations starts with inbound, outbound and returns, and ends with an exceptions playbook, incident runbooks and a glossary.

The setup also says which audience comes first for each kind of company. A freight forwarder leans on partners. A last-mile courier leans on developers. A warehouse or a trucking fleet leans on operations, with runbooks a dispatcher can find at 3 a.m.

The prompt we hand to Claude for each space carries three notes we think matter more than the list: use the real names of statuses, event codes and fields from the code and invent none; prefer a real example to a description of one; and say what costs money or cannot be undone on the page where someone is about to do it. The prompt for one audience never mentions the other audiences' pages; a test holds that, because a prompt listing all three would draft the wrong things.

API keys that read by default

On Enterprise, a developer reading the API docs can generate a key on the page. The question is what that key may do before the owner looks at it. In logistics the line is money:

Scope	On by default
rates:read	Yes
tracking:read	Yes
shipments:read	Yes
shipments:write	No
labels:write	No
webhooks:manage	No

A key that reads is harmless. A key that books a shipment or buys a label spends the customer's money, so it is granted by the owner, key by key. That is not only a convention in the data: server/industries.test.ts fails if any scope ending in :write, :manage or :delete is on by default, and it runs the setup's key settings through the same validation the server applies on save, so a setup cannot suggest something saving would refuse.

Each key starts at 1,000 calls and 90 days, with at most five per person. The setup also tells the owner to list the sandbox first in the OpenAPI file's servers, because the console starts on the first server, so a new developer lands where nothing ships and nothing is charged.

The trade-off

A setup pre-fills and never applies. It fills in the form, and the person still presses the button. A space made from a setup has no link back to it, so there is nothing to keep in step when the setup changes. The cost is that the three spaces are set up one at a time, and improving the setup later does nothing for spaces already made from it.

What we would do differently

Our own notes say this plainly, and so should this page: the logistics sectors, the page lists and the scope names were written from general knowledge of the industry, not from running a logistics operation. They are marked in our decision log as the first thing to correct, by someone who has. We added only the setups we could write down, and there is no "coming soon" list of industries, because a list of promises is what our changelog rules exist to avoid. If we started again, we would find that person before publishing the page, not after.