---
seo:
  title: "Pushing Content"
  description: "How documentation and asset changes are uploaded, staged, reviewed, and published on the portal, including bringing your own GitHub or GitLab repository."
llm_context: "Guide to the portal's git-based content workflow: staging vs main branches, the two upload paths (in-browser editor and SFTP), merging to main, reverting/rolling back changes, and the setup steps for backing a portal with a customer-owned GitHub or GitLab repository instead of FixSpec's own git storage."
category: "guide"
related:
  - "/portal/guides/organisation"
  - "/portal/guides"
---

# 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](#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](#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](#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.

:::tip 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.
:::
