Backstage TechDocs setup: what teams get and when they need it
Engineers often cannot find the documentation for the services they own. Runbooks sit in one wiki, API notes in a repository README, and architecture diagrams in a shared drive that nobody updates. TechDocs is the core Backstage feature that renders documentation next to the catalog entity it describes, so a service page can show its owner, its dependencies and its docs in one place. The Backstage architecture overview lists TechDocs among the core built-in features, alongside the Software Catalog and Software Templates.
TechDocs works on a docs-like-code model. Authors keep Markdown files in the same repository as the service, organized with *MkDocs*, a static site generator, and a mkdocs.yml configuration file. The docs are built into a static site and stored in an object store, and the Backstage frontend reads the pages from there. An entity links to its docs through the backstage.io/techdocs-ref annotation in its catalog descriptor. A team should run TechDocs in production once it has more than a handful of services, when docs must follow code through review, and when the organization needs a single place to find them. Small installations can start with local builder and storage settings, but production setups move the build into CI and publish to remote storage.
Before rollout, confirm three things with your platform team: which object store you will use (S3, Google Cloud Storage or Azure Blob Storage, or an S3-compatible service you operate), whether CI or the Backstage backend will generate the sites, and who may read internal documentation. Those answers decide how much of the build and access design you own. Check the current TechDocs configuration reference in the Backstage documentation for your release line, since the defaults for builders and publishers have changed over time.
Choosing how TechDocs is built and where it is stored
TechDocs can be generated in two places. In the Backstage backend, the portal builds each MkDocs site when it is requested, which keeps the first setup small but ties build load and failures to the portal server. In CI, the pipeline runs techdocs-cli to generate and publish sites to storage ahead of time, so the backend only reads finished output. Most production teams with more than a handful of documented services prefer CI because builds run on separate capacity and failures show up in the owning repository.
- Backend build: Fits pilots and small catalogs where one team owns the portal and build failures are easy to watch.
- CI build: Moves generation into each repository's pipeline, so the owning team sees build failures next to its other checks.
- Operating effort: CI builds add pipeline templates, publish credentials and a standard for every repository, which is a one-time effort that recurs when templates change.
- Scale: Backend builds compete with portal traffic for resources, so catalog growth tends to push teams toward CI.
- Confirm: Ask your platform team which Backstage version and TechDocs configuration they will use, and check the current TechDocs documentation for supported build modes before committing.
The build location also decides where the write credentials live, so settle it before choosing storage.
Local storage keeps generated sites on the Backstage backend's own disk. It needs no object storage account, no bucket policy and no extra network path, which makes it the simplest option for evaluation and single-instance pilots. It does not suit a portal that runs as several replicas or that must survive container restarts, because each instance needs the same generated files and the files must persist.
- Fit: Proofs of concept, small internal portals and single-replica deployments.
- Effort: Low at the start, but you must manage persistent volumes, backups of the generated output and disk growth as the catalog grows.
- Limits: Replicas do not share files unless the volume is shared, so a rollout can serve stale or missing docs.
- Recurring cost: Disk capacity, volume snapshots and the time spent diagnosing storage faults on the portal host.
- Confirm: Ask whether your deployment model allows a shared persistent volume and how your team would restore generated sites after a node loss.
If you expect more than one backend replica or a CI build pipeline, plan for object storage from the start.
Amazon S3 and S3-compatible services hold generated sites as objects, so any backend replica can read them and CI can publish them without touching the portal host. This is the most common production pattern. The effort lies in bucket design, IAM policy, encryption settings and keeping read and write credentials separate. Self-hosted S3-compatible storage, such as systems run in your own data center, follows the same model but adds operating work for the storage platform itself.
- Fit: Multi-replica portals, CI-published docs and teams already running S3 or an S3-compatible platform.
- One-time work: Bucket creation, a write role for the CI pipeline and a read-only role for the backend, plus encryption and versioning choices.
- Recurring work: Storage cost, lifecycle rules for old builds and credential rotation.
- Latency: Keep the bucket in the same region as the backend when possible, since remote reads add time to every page load.
- Confirm: Ask the TechDocs configuration reference for the exact publisher settings for your storage type and whether your S3-compatible platform supports the required API calls.
Separate the CI write identity from the backend read identity so a compromised pipeline cannot rewrite what readers see by default.
Google Cloud Storage and Azure Blob Storage fill the same role as S3 for teams whose platform already runs on those clouds. The publishing model is the same: CI writes generated sites to a bucket or container and the backend reads them. Choose the provider where the portal and most of its users sit, because cross-cloud reads add latency and egress cost that operations teams must track.
- Fit: Organizations standardized on Google Cloud or Azure, with the portal hosted in the same cloud.
- One-time work: Bucket or container setup, identity configuration for CI and the backend, and network rules if storage is private.
- Recurring work: Storage and egress charges, identity rotation and periodic review of access grants.
- Skills: The team running the platform needs working knowledge of that provider's identity model, which may differ from the team's existing S3 experience.
- Confirm: Check the TechDocs storage documentation for the supported publisher type on your version, and confirm how your cloud identity method maps to the backend's authentication.
If your organization runs more than one cloud, pick one storage location for TechDocs and document why, so auditors and operators know where the sites live.
Whatever build location and storage you choose, the write path and the read path should use separate credentials. CI needs permission to publish, the backend needs permission only to read, and neither should share a long-lived secret with the other. This separation limits the damage from a leaked pipeline token and keeps the portal from changing content it serves. The same split also makes it easier to show which system wrote each site.
- Write identity: Scoped to publishing into the TechDocs prefix or container for the pipeline, with short-lived credentials where the platform supports them.
- Read identity: Scoped to reading the same location, used only by the Backstage backend.
- Audit trail: Keep storage access logs enabled so publishing events can be traced to a pipeline run.
- Visibility: Storage access does not replace catalog permissions, so review how docs are restricted to users in the portal separately.
- Confirm: Ask your security team which secret store will hold each credential and how rotation will be scheduled and tested.
Before go-live, test that a CI job cannot read other teams' buckets and that the backend cannot write to them.
How to set up TechDocs in production
This sequence takes TechDocs from a configured publisher to a rendered site for a sample entity, with CI holding write access and the backend holding read access only. Each step closes with a check so problems surface before more entities depend on the setup.
Choose the publisher and storage bucket
Decide where generated sites will live before touching configuration: an S3 or S3-compatible bucket, a Google Cloud Storage bucket or an Azure Blob Storage container. Your platform team creates the bucket with versioning and private access, and confirms that the region matches where your Backstage backend runs, since latency from the storage location affects page loads. Done means the bucket exists, is private and is documented with its name and region for the next step.
Enable TechDocs in app-config
A Backstage developer sets the techdocs section in app-config.yaml to use an external publisher type, names the bucket and credentials source, and keeps the builder setting pointed at CI rather than the backend so the server does not generate sites on demand. Storage credentials for the backend should be read-only at this point. Check: the backend starts without configuration errors and the TechDocs settings appear in the backend startup log.
Add the techdocs annotation to catalog entities
Each component that owns documentation gets the backstage.io/techdocs-ref annotation in its catalog-info.yaml. Use the dir: form when docs live in the same repository, and a url: form when they live elsewhere. The docs folder must contain an mkdocs.yml and the Markdown source. Check: after the catalog refreshes, the entity page shows a Docs tab, even though the page may still be empty until the first publish.
Create separate CI write credentials
The platform team creates a dedicated identity for CI with write access to the bucket only, and stores its credentials in the CI secret store, not in the repository. The backend keeps its own read-only identity. Keeping the two apart means a compromised pipeline cannot alter what the portal serves beyond the sites it publishes, and a leaked backend credential cannot publish content. Check: the CI identity can write a test object, and the backend identity is denied writes to the same bucket.
Build and publish from CI with techdocs-cli
Add a pipeline job, owned by the team that maintains the repository, that runs techdocs-cli generate to build the MkDocs site and techdocs-cli publish to upload it to the bucket under the entity's namespace and name. Enable the skip-if-unchanged option if your CLI version supports it, so unchanged docs are not rebuilt on every commit. Check: the pipeline log reports a successful publish and the expected files appear in the bucket under the entity path.
Grant the backend read access
Confirm the backend identity can read objects from the bucket and nothing more. Test this by requesting a published page through the backend's TechDocs API path, not by opening the bucket directly. If the request fails with an access error, check the policy attached to the backend identity and the bucket's access rules, not the CI configuration. Check: the backend returns the generated HTML for a known page with a 200 response.
Verify a site renders for a sample entity
Pick one entity with a published site and open its Docs tab in the portal. Confirm the navigation tree matches mkdocs.yml, internal links resolve, and images load. Then change one line in the source, rerun the pipeline and confirm the change appears after a refresh. Check: the sample entity renders correctly end to end, and the team that owns it agrees the output matches the source before you roll the pattern out to other entities.
How docs link to catalog entities
A TechDocs site only appears in Backstage when a catalog entity tells the portal where its documentation lives. The link is made with the backstage.io/techdocs-ref annotation in the entity's catalog-info.yaml, which points to the source of the docs. The value dir:. means the docs sit in the same repository as the descriptor, with mkdocs.yml and a docs/ folder beside it. A value such as url: points to a separate repository. Because the annotation is set per entity, two components in one repository can each publish their own site, and the entity decides which docs a reader sees. Confirm the annotation names and accepted formats against the TechDocs documentation for your Backstage version before you write a standard for teams to copy.
The entity model therefore drives what readers see. A system or domain entity with no techdocs-ref will show an empty docs tab, while a component whose annotation points at a stale branch will keep showing old content. Ownership matters just as much. The spec.owner field decides which team is accountable for the entity and, once catalog permissions are in place, who can see its docs. Decide before rollout whether docs follow the component, the system or the team, and write that rule into your descriptor template. Teams that copy descriptors without reviewing the owner field usually create the orphaned entities described below.
Orphaned docs appear when a repository is archived, renamed or transferred, or when its descriptor is deleted while the generated site remains in object storage. Stale docs appear when the CI job that publishes the site stops running, or when the annotation points at a path that no longer exists. Build a recurring check that lists catalog entities with a techdocs-ref whose source repository or branch cannot be read, and compares each entity's last publish time with its latest commit. Entities whose owner group no longer exists in your identity directory need a separate review. Ask your platform team how the check will report findings and who acts on them, because a list nobody owns becomes a stale list.
Extending TechDocs pages with addons
What are TechDocs addons and what can they change on a rendered page?
TechDocs addons are extension points that let you add React components to a TechDocs page, such as a banner, a feedback widget, or a custom header or footer, without forking the TechDocs reader. Each addon is a frontend component registered in your Backstage app and placed at a defined location in the rendered page. They run in the browser, so they can read the page content and metadata the reader exposes, but they should not be treated as a security boundary. Confirm the current addon API, the available placement points and the component props against the official TechDocs documentation for your Backstage version before you design anything.
Do TechDocs addons survive a Backstage upgrade?
Addons themselves are usually small, but they depend on frontend APIs and component libraries that Backstage changes between releases. Each upgrade can rename an extension point, change component props, or move a dependency, so an addon that worked last quarter can fail silently or break the page build. Check the Backstage Upgrade Helper for the template changes between your current and target versions, and read the release notes for the TechDocs and frontend packages. Plan a test pass on a staging portal with real documentation sites before each upgrade.
How much does it cost to maintain custom TechDocs addons?
The cost comes from the number of addons, how much they depend on internal Backstage APIs, and how often your Backstage version moves. The build cost is one-time, but maintenance recurs with every upgrade cycle, because each addon needs review, rebuilding and regression testing. Ask any partner or internal team to estimate the upgrade effort per addon, separate from the initial build, and to state which addons depend on unstable or internal APIs. Keep the addon count small, and prefer configuration or standard features where they meet the requirement.
Which addon features are worth building versus using standard TechDocs features?
Build an addon only when a standard TechDocs feature or a configuration option cannot meet a documented need. Common valid reasons include an internal feedback link tied to your ticketing system or a compliance notice that must appear on every page. Before writing code, check whether the requirement can be met with MkDocs theme settings, a plugin in your documentation build, or content in the docs themselves. Each custom addon adds an ongoing upgrade item, so record the business reason for it.
Can addons expose documentation that users should not see?
Addons run in the same browser context as the rendered page, so anything an addon fetches or displays is visible to anyone who can view that page. Addons must not embed secrets, internal tokens or data from restricted systems. If an addon calls a backend API, that API must enforce its own authorization and must respect the same catalog permissions that govern the documentation. Review every addon in your security review as client-side code, and keep access decisions in the server, not in the addon.
How do we test TechDocs addons before a Backstage upgrade?
Test addons in a staging Backstage instance that runs the target version and points at a copy of your production TechDocs storage. Build a small set of representative documentation sites that cover long pages, code blocks, navigation depth and any pages where the addon appears. Check that each placement renders, that the addon does not block page load, and that the browser console shows no errors. Automate these checks in CI where possible, and keep the test set in version control so each upgrade reuses it.
What should we ask for in a quote for TechDocs addon work?
Ask for a written list of each addon with its purpose, placement, data it reads, and any internal APIs it calls. Request the build effort, the test plan, and the documentation handover as separate line items. Also ask who maintains each addon after handover, how upgrades are scoped, and whether maintenance is included in a retainer or billed per upgrade. DeployOpen plans and builds work on a fixed scope agreed in writing, and ongoing upgrades can run under a retainer, so ask for the upgrade and support terms alongside the build terms.
Security and operational risks to plan for
TechDocs puts generated documentation in a storage bucket, a CI pipeline and a rendered reader, and each of those is an access path. The cards below cover the decisions that keep documentation reachable by the right people and nobody else.
Separate CI write access from backend read access
The pipeline that runs techdocs-cli publish needs write permission on the bucket, while the Backstage backend only needs to read the generated sites. Give CI a write-scoped credential that lives in the pipeline secret store, and give the backend a read-only identity. If one credential does both jobs, a compromised backend or a leaked build token can overwrite the documentation that every team trusts. Check that the two identities are separate in your cloud IAM and that neither can be used interactively by developers.
Lock down bucket access controls
The storage bucket should not be publicly readable, and listing permissions should be narrower than read permissions. Confirm that public access blocks or equivalent settings are on, that object versioning or a retention policy protects against accidental deletion, and that access is logged. Storage locations differ in how these controls are named, so verify the exact settings with your cloud provider's documentation for the bucket type you chose.
Sanitize rendered HTML
TechDocs renders Markdown from repositories into HTML that runs in users' browsers. Anything a contributor can put in a page, including raw HTML or script-bearing content, can reach every reader of that site. Confirm which sanitization and content security settings your Backstage version applies to the TechDocs reader, and treat changes to docs addons and custom HTML as code review items. Test with a deliberately malicious page in a non-production portal before you trust the defaults.
Keep docs within the intended audience
Documentation for an internal service often describes architecture, runbooks and hostnames that should not reach outside staff or contractors. Access to the rendered page is decided by Backstage, not by the bucket, so the portal's sign-in and visibility rules determine who can read it. Map which groups should see which entities before publishing sensitive sites. Restricting visibility through catalog permissions is a sibling topic with its own design decisions.
Avoid guest access in production
The Backstage authentication documentation advises against offering guest access in production. A guest identity can reach catalog entities and the TechDocs pages linked to them, so an open guest sign-in quietly widens the audience for every site. Turn off guest access, configure sign-in resolvers so each provider resolves to the same identity, and confirm with a test user from outside the intended group that documentation is not visible to them.
Review and log publication events
Every publish is a change to what the organization tells its engineers, so record who published which site, from which commit and pipeline. Keep these logs with your other CI audit records and review unexpected publishes, such as a site published from a branch that is not the default. Ask your team to confirm how long pipeline and storage logs are kept and whether they meet your internal retention rules.
Questions teams ask before running TechDocs
What drives the cost of running TechDocs in CI?
The main cost drivers are CI build minutes, object storage for generated sites, and the engineering time to build and maintain the pipeline. Build minutes scale with how many repositories publish docs and how often they change, so a content hash with a skip-if-unchanged step can reduce wasted runs. Storage grows with the number of sites and the versions you keep, and it recurs monthly with your cloud provider. Engineering time is mostly one-time setup, followed by ongoing work when MkDocs plugins or TechDocs addons change. Ask any vendor or partner to split a quote into one-time build work, recurring infrastructure you pay directly, and ongoing support.
How long does a first TechDocs rollout take?
Duration depends mainly on how many repositories publish docs, how many teams must adopt a shared CI template, and which storage option you choose. A pilot with a few repositories on one storage backend is far shorter than a rollout across every service in the catalog. Storage choice matters because S3, Google Cloud Storage and Azure Blob Storage each need their own bucket, identity and access setup before the first publish. No duration is stated here because none has been supplied for this topic. Ask for a written timeline tied to a defined repository count and storage backend.
What do we need to provide before the work starts?
You will need a storage account or bucket in the cloud you control, CI runners that can build MkDocs sites and push to that storage, and a write identity for CI that is separate from the read identity used by the Backstage backend. You also need a Backstage instance where the TechDocs reader and catalog are already running, and access to the repositories that will hold docs. Identity matters because the backend should read published sites without holding write rights. Confirm each item with your platform, security and cloud teams before scoping the engagement.
Can an internal team set up TechDocs without outside help?
Yes, a team with strong CI and Backstage experience can do it alone, and the TechDocs documentation covers the core steps. The harder parts are usually the storage access model, keeping write credentials out of the backend, and standardizing a CI template across many repositories. Teams without recent Backstage upgrade or plugin experience often spend more time on those areas than on the build itself. A partial approach is also common: the internal team builds the first pipeline and a partner reviews access design and addons. Decide based on who will own the pipeline after go-live.
Which addons or MkDocs plugins create the most ongoing work?
Addons and MkDocs plugins that render custom components, change page navigation, or depend on a specific MkDocs version create the most upkeep. Each one must be tested when Backstage or MkDocs is upgraded, and a plugin that falls behind can break builds across every repository that uses it. Keep the addon list short and pin versions so upgrades are deliberate. Ask any partner to list every addon in scope and to state who owns its updates after handover.
How do TechDocs builds affect our compliance evidence?
Published documentation can support change management and secure development evidence, because the pipeline records when docs were built and from which commit. Storage access logs and CI logs are the usual sources for that trail. DeployOpen prepares systems, controls and evidence for compliance assessments, but it does not issue audit reports or certifications, and independent auditors decide what is sufficient. Ask your auditor which artifacts they will test before you define retention for build logs and storage.
What breaks most often after TechDocs goes live?
The most common failures are expired or over-scoped storage credentials, MkDocs build errors after a plugin change, and sites that stop updating because the CI job skipped a publish. Teams also report slow page loads when docs sit in a distant storage region, which is often handled with caching. Monitor publish jobs and storage access from the first day, and assign a named owner for the CI template. Ask a partner for its runbook for these cases before signing a fixed-scope agreement.
How DeployOpen scopes and supports TechDocs
DeployOpen plans and builds the TechDocs pipeline inside your own infrastructure, from the CI build that generates MkDocs sites to the storage and catalog links the portal reads. Engagements are fixed-scope, with the scope, deliverables and timeline agreed in writing before work starts.
How we scope
- Inventory which repositories hold docs and which catalog entities should link to them.
- Agree the CI platform, the object storage target and who may write versus read the sites.
- Record the written scope, deliverables and timeline before any build work begins.
How we build
- Configure CI jobs that generate and publish MkDocs sites with techdocs-cli in your pipelines.
- Set up storage access so CI holds write credentials and the Backstage backend holds read-only access.
- Test catalog links, rendering and skip-if-unchanged behavior before handing the pipeline over.
How we hand over
- Document the pipeline, storage layout, credential scopes and the steps to add a new docs repository.
- Walk your platform and documentation owners through troubleshooting for failed builds and missing pages.
- Deliver runbooks that describe how to bump Backstage and TechDocs versions in your environment.
How we support
- Offer ongoing support, upgrades and testing as a retainer after the initial handover.
- Review TechDocs pipeline changes when Backstage releases or the MkDocs toolchain changes.
- Confirm with your team which support scope and response expectations apply before signing.
