Publishing Content

All documentation and API reference content on the portal is version-controlled. Every change — whether it’s a single-page edit or a bulk import of Markdown and asset files — is recorded as a commit, and nothing is visible to portal visitors until it has been reviewed on a staging branch and explicitly promoted to main.

By default, this history lives in git storage that FixSpec hosts and manages for you. If your organisation needs your documentation source to live in a repository you already own and control, your portal can instead be backed by your own GitHub or GitLab repository — see Bringing your own GitHub or GitLab repository below. This is a one-time choice made during onboarding, not something you switch day to day, but everything else in this guide — the staging/main model, the editor, reviewing and publishing, reverting and rolling back — works identically either way.

There is no direct git push to a repository hosted on the portal itself. Instead, changes reach the portal through the paths described below, and are then promoted or rolled back from the Versions admin screen.

The staging → main model

Content for each customer lives on two branches:

  • staging — where all new commits land first: edits made in the admin editor, bulk uploads, and imports. Nothing here is served to end users.
  • main — what is actually served to portal visitors. main only changes when an admin explicitly promotes staging into it.

This means you can make several changes over time — fix a typo, add a new guide, update an OpenAPI spec — and none of them go live until someone with admin access reviews the accumulated staging changes and clicks Merge staging → main.

If your portal is backed by your own GitHub or GitLab repository, staging and main are literally the two branches of that repository — your team can view the same commit history in your own GitHub/GitLab UI, not just on the Versions screen.

Uploading content

1. In-browser editor (single files, quick edits)

For small or one-off changes, admins can edit a document directly from the Schema Validation screen (/admin/validation, linked from the admin sidebar). This is currently the only in-browser path to editing a page — there is no separate “page editor” screen or deep link to a specific document.

To edit a page:

  1. Open Schema Validation from the admin sidebar.
  2. Pick a schema from the first dropdown, then pick a document from the second dropdown. The document list is whatever SchemaValidationService::discoverDocuments() returns for that schema — content that has an associated JSON/YAML schema, not arbitrary Markdown pages.
  3. The document’s raw content loads into a code editor, with validation against the selected schema running automatically (debounced) as you type.
  4. Click save to open a Commit to staging dialog. Enter a commit message and confirm.

Each save:

  • Writes a single commit to staging (this is the default target branch for saves from this screen)
  • Runs schema/lint validation before the commit is accepted
  • Is attributed to the signed-in admin

This is the fastest path for correcting a typo, updating front matter, or making a small content change without leaving the browser — but only for documents the schema picker exposes. There is currently no browse-by-folder or “edit any Markdown file” experience; if the page you want to fix doesn’t have a matching schema/document entry, use SFTP instead.

2. SFTP upload (bulk changes, asset files, automated pipelines)

This path applies only to portals backed by FixSpec’s own git storage. If your portal is backed by your own GitHub or GitLab repository, there is no separate SFTP endpoint — see Bringing your own GitHub or GitLab repository for the equivalent bulk-upload path.

For larger changes — a batch of new Markdown pages, images, or a full API spec update — content is pushed via SFTP into a staging upload session:

  1. Connect to the SFTP endpoint for your portal using the credentials issued during onboarding.
  2. Upload your Markdown files, images, and any other assets into your staging session, preserving the folder structure expected by portal.yaml / sidebars.yaml.
  3. Once you stop uploading, the session automatically finalizes into a single commit on staging after a short quiet period, so multiple related files land together rather than as a flurry of separate commits.
  4. If you need the upload committed immediately rather than waiting out the quiet period, an admin can trigger Finalize staging upload now from the Versions screen.

This is the recommended path for CI/CD pipelines or any automated publishing tool that doesn’t already push to your own git repository: sync your build output to the SFTP staging session, and let it settle into a single, reviewable commit.

Bringing your own GitHub or GitLab repository

If your organisation needs documentation source content to remain in a repository you own — for compliance, internal tooling, or simply because it already lives there — your portal can be backed by your own GitHub or GitLab repository instead of FixSpec’s own git storage. FixSpec never takes a separate, persistent copy of your repository’s history to do this: content is read from and written to your repository directly, and only the current published (main) and in-review (staging) versions are cached in the portal’s database so pages render quickly.

This is set up once, during onboarding, with your FixSpec contact — there is currently no self-service screen in the portal for configuring or changing this. To set it up, we’ll need the following from you:

For a GitHub-backed portal

  1. Tell us which repository (organisation/user and repository name) will back your portal, and confirm it already has main and staging branches (we can create staging for you if it doesn’t exist yet).
  2. Install the FixSpec GitHub App on that repository. Your FixSpec contact will send you an installation link — this requires organisation admin permission on GitHub. Installing it scopes our access to exactly that repository (or repositories, if you choose), rather than a personal account token, and lets you revoke access at any time from your GitHub organisation’s settings.
  3. Send us the installation ID shown once the app is installed (visible in your GitHub organisation’s Settings → GitHub Apps → Configure). We use this, not a password or personal token, to authenticate — access tokens are minted per-request and expire automatically within the hour.
  4. Once we’ve configured your portal, we’ll give you a webhook URL and a shared secret. Add these under your repository’s Settings → Webhooks (content type application/json, “Just the push event” is sufficient). This is what lets the portal notice changes made directly on GitHub — for example, by your own engineers merging a pull request — without you needing to do anything else.

For a GitLab-backed portal

  1. Tell us which project (namespace/project path or numeric project ID) will back your portal, and confirm it has main and staging branches.
  2. Create a Project Access Token (or Group Access Token, if you’d rather manage it at the group level) scoped to that project with the api and read_repository/write_repository scopes, and a long expiry consistent with your organisation’s token-rotation policy. GitLab: Settings → Access Tokens.
  3. Send us that token through the secure channel your onboarding contact provides — never over email or chat.
  4. Once we’ve configured your portal, we’ll give you a webhook URL and a secret token. Add these under your project’s Settings → Webhooks (trigger on “Push events”), so changes made directly on GitLab are picked up automatically.

What changes for a GitHub/GitLab-backed portal

  • Publishing changes: you can promote content either the usual way — clicking Merge staging → main on the Versions screen — or by merging staging into main yourself directly on GitHub/GitLab (for example, via a pull request your own team reviews). Either way, the published content updates automatically; the portal doesn’t need to be told which one happened.
  • Bulk changes: rather than uploading via SFTP, push directly to the staging branch of your own repository using whatever tooling you already use (a CI pipeline, git push from your own machine, a pull request merge). The portal picks up the change automatically via the webhook configured above — there is no separate portal-side upload step.
  • The in-browser editor (Schema Validation screen, above) still works exactly as described, committing straight to your repository’s staging branch.
  • Branch protection on main: FixSpec does not configure or enforce branch protection rules on a repository we don’t host. We strongly recommend you protect main in your own GitHub/GitLab settings (e.g. requiring pull request review) if you want to prevent direct pushes to it — but if a direct push to main does happen on your side, it will still be detected and published normally, since main is what portal visitors see.
  • SFTP is not available for GitHub/GitLab-backed portals — your own repository’s tooling replaces it.

Previewing staging content

Before merging, admins can browse the portal as it would look once staging is promoted, via Preview Staging in the admin sidebar (/admin/preview).

This works by mirroring the public content routes under an /admin/preview/... prefix: DocsController::show() and ApiReferenceController::show() are reused as-is, but the route defaults branch to staging instead of main, so the exact same rendering code reads from the staging branch. For example:

  • /guides/pushing (public, main) becomes /admin/preview/guides/pushing (staging)
  • /reference/openapi/fixspec/v5 (public, main) becomes /admin/preview/reference/openapi/fixspec/v5 (staging)

Known issue: the Preview Staging sidebar link currently points at /admin/preview with no trailing slash and no path. DocsController::show() strips the admin/preview/ prefix from the request path with a regex that requires that trailing slash; without it, the controller treats admin/preview itself as the document path, tries to fetch a staging document at that (nonexistent) path, and renders a blank page. Visiting /admin/preview/ (with the trailing slash), or any specific path like /admin/preview/guides/pushing, works correctly and shows the staging version of that page. Until the sidebar link is fixed, add a trailing slash manually or browse to a specific staging path.

Preview pages are read-only — they don’t offer an editor. Use the Schema Validation screen (above) or SFTP to make changes, then come back to Preview Staging to check how they’ll look before merging.

Reviewing and publishing changes

Admins review pending changes on the Versions screen (/admin/versions), which shows:

  • The current HEAD commit on staging and on main, side by side
  • A full commit history for each branch (message, author, commit hash, timestamp)
  • A Merge staging → main button, which promotes every accumulated staging commit to main in one step. This is disabled once the two branches are already in sync.

Nothing published via the editor or SFTP is visible to customers until this merge happens.

Reverting and rolling back

Two distinct operations are available per branch (from the Versions screen, this applies to staging):

  • Revert a commit — undoes one specific commit by adding a new commit on top that reverses it. History is preserved; everything else made before and after that commit stays in place. Use this when one change was wrong but later changes are still good.
  • Roll back to a commit — resets the branch pointer back to an earlier commit, discarding every commit made after it. Use this when you want to throw away a run of recent changes entirely and start again from a known-good point.

Rolling back or reverting on staging does not affect main — visitors keep seeing whatever was last merged until an admin merges again. If a bad change has already been merged to main, revert or roll back main directly and merge again (or roll back main to the previous good commit).

If a commit succeeds in git but content fails to appear on the portal (a sync issue rather than a content issue), an admin can trigger a re-export, which re-syncs the portal’s content store from the current state of the branch without creating a new commit.

Access

  • Editing content and managing branches (merge, revert, rollback, finalize) requires an admin account authenticated through Keycloak.
  • SFTP credentials for bulk/automated uploads are issued separately per customer during onboarding — contact your portal administrator if you need a set. Not applicable to GitHub/GitLab-backed portals.
  • GitHub App installations, GitLab access tokens, and webhook secrets for a GitHub/GitLab-backed portal are set up once during onboarding with your FixSpec contact, not through a self-service screen in the portal — see Bringing your own GitHub or GitLab repository.

Information Needs

GitLab

In order to configure your GitLab set-up, please provide:

  1. Webhook signing token (webhook set up with “push events”)
  2. Project/Group/Personal Access token with read_repository and write_repository access

Pre Publication Checks and Post Publish Actions

Since the storage mechanism behind portal content is git, “publication” is equivalent to merging the staging branch into main. Before such a merge happens, a series of quality checks are run automatically:

  • All API Schemas (OpenAPI and FinSpec) pass schemantic validation and contain unique operation IDs,
  • All internal references to API schemas are valid,
  • All internal and external website links (including anchor links between sections) are valid and present.

💡 Strong Recommendation To Merge Via The UI

The platform supports the use of both our internal git and external providers such as GitHub and GitLab to manage core version control, but also surrounds those with other software elements which manage replication, caching and search.

If you use a third-party git provider and directly merge (or commit) into your main branch, then the post-publication actions such as search indexing should run as expected once we detect this in our platform. The pre-publication checks will not run, however, which may leave your portal at risk of bad web links or schemas.

For this reason, we strongly recommend always merging to main using our UI, as this guarantees all publication checks are completed correctly. The merge will also be reflected into your GitHub/GitLab automatically, so no second, manual merge is required.