> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt. # Publishing your docs > Publish your Fern docs to production and staging sites with automated workflows. Set up custom domains and manage deployments easily. When you are ready for your docs to be publicly accessible, publish them using the Fern CLI. To validate changes with reviewers first, generate [preview links](/learn/docs/preview-publish/preview-changes#preview-links). Choose one of the following approaches: publish [only to a production site](#publish-to-production), or [to separate staging and production sites](#publish-to-staging-and-production). Use the [Fern Dashboard](https://dashboard.buildwithfern.com) to manage CLI access, connect your GitHub repository, and monitor analytics and broken links. ## Publish to production For a single production site (no staging environment), run the following command to publish your documentation: ```bash fern generate --docs ``` **`Example`** ```bash Example fern generate --docs [docs]: Found 0 errors and 1 warnings. Run fern check --warnings to print out the warnings. [docs]: ✓ All checks passed [docs]: Published docs to https://plantstore.docs.buildwithfern.com ┌─ │ ✓ https://plantstore.docs.buildwithfern.com └─ ``` #### Automate publishing process Use a GitHub Action workflow to publish your docs when a push is made to the `main` branch. Publishing runs on any CI provider that can install the CLI and read a `FERN_TOKEN` secret: for GitLab, use the [GitLab CI/CD pipeline](/learn/docs/developer-tools/git-lab). #### Generate API key Use `fern token` to generate an API key for authenticating the Fern CLI in CI/CD environments. The API key is specific to your organization defined in [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson) and doesn't expire. You can also create and manage API keys from the [API keys](/learn/dashboard/configuration/api-keys) page in the Dashboard. #### terminal ```bash fern token ``` #### Add API key as a secret Add the API key as a [repository secret](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository) called `FERN_TOKEN`. #### Create workflow Create a Publish Docs workflow ([example](https://github.com/fern-api/docs/blob/main/.github/workflows/publish-docs.yml)), and reference the secret. **`.github/workflows/publish-docs.yml`** ```yaml .github/workflows/publish-docs.yml maxLines=7 startLine=21 {21} name: Publish Docs on: push: branches: - main jobs: run: runs-on: ubuntu-latest if: ${{ github.event_name == 'push' && contains(github.ref, 'refs/heads/main') && github.run_number > 1 }} steps: - name: Checkout repository uses: actions/checkout@v4 - name: Install Fern run: npm install -g fern-api - name: Publish Docs env: FERN_TOKEN: ${{ secrets.FERN_TOKEN }} run: fern generate --docs ``` ## Publish to staging and production To preview changes on a staging site before publishing to production, define [multiple instances](/learn/docs/configuration/site-level-settings#instances-configuration) in your `docs.yml` file. Once you configure multiple instances, you must use the `--instance` flag when publishing. #### Configure instances Add both staging and production URLs to your `docs.yml` file. Don't include `https://` in the URLs. **`docs.yml`** ```yaml docs.yml instances: - url: plantstore-prod.docs.buildwithfern.com - url: plantstore-staging.docs.buildwithfern.com ``` #### Publish to a specific instance Use the `--instance` flag to publish to a specific environment: ```bash # Publish to staging fern generate --docs --instance plantstore-staging.docs.buildwithfern.com # Publish to production fern generate --docs --instance plantstore-prod.docs.buildwithfern.com ``` After publishing, both instances will appear in the [Fern Dashboard](https://dashboard.buildwithfern.com). #### Automate publishing process Use GitHub Action workflows to automatically deploy to staging on every push, while keeping production deployments manual. #### Generate API key Use `fern token` to generate an API key for authenticating the Fern CLI in CI/CD environments. The API key is specific to your organization defined in [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson) and doesn't expire. You can also create and manage API keys from the [API keys](/learn/dashboard/configuration/api-keys) page in the Dashboard. #### terminal ```bash fern token ``` #### Add API key as a secret Add the API key as a [repository secret](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository) called `FERN_TOKEN`. #### Set up automatic staging deployment workflow This workflow automatically publishes to your staging instance when changes are pushed to the `main` branch: **`.github/workflows/publish-staging.yml`** ```yaml .github/workflows/publish-staging.yml maxLines=7 name: Publish Staging Docs on: workflow_dispatch: push: branches: - main jobs: run: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v4 - name: Install Fern run: npm install -g fern-api - name: Validate configuration run: fern check - name: Publish to Staging env: FERN_TOKEN: ${{ secrets.FERN_TOKEN }} run: fern generate --docs --instance plantstore-staging.docs.buildwithfern.com ``` #### Set up manual production deployment workflow This workflow allows you to manually trigger a production deployment from the GitHub Actions UI: **`.github/workflows/publish-production.yml`** ```yaml .github/workflows/publish-production.yml maxLines=7 name: Publish Production Docs on: workflow_dispatch: jobs: run: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v4 - name: Install Fern run: npm install -g fern-api - name: Validate configuration run: fern check - name: Publish to Production env: FERN_TOKEN: ${{ secrets.FERN_TOKEN }} run: fern generate --docs --instance plantstore-prod.docs.buildwithfern.com ``` To deploy to production, go to the **Actions** tab in your GitHub repository, select the workflow, and click **Run workflow**. ## Hosting When you publish your docs, Fern takes care of hosting them for you. You can also [publish your docs to a custom domain](/learn/docs/preview-publish/setting-up-your-domain). ### Self-hosting your docs If you need access to your docs offline or would like to host your docs on your own server, Fern [offers that option as well](/learn/docs/self-hosted/overview). Self-hosted docs have limited access to certain features (including Ask Fern and analytics). ## Unpublishing your docs To unpublish a docs site, navigate to the **Settings** page for your site in the [Fern Dashboard](https://dashboard.buildwithfern.com) and click **Unpublish**. This makes the domain no longer publicly accessible, but doesn't delete the site — you can republish it at any time. This is useful for creating draft sites or temporarily hiding a site from public view. ## Common errors ### No token found. Please set the FERN\_TOKEN environment variable or run `fern login`. `fern generate --docs` needs an authenticated session to publish. Run [`fern login`](/learn/cli-api-reference/cli-reference/general-commands#fern-login) locally, or set `FERN_TOKEN` in your shell or CI environment. Generate an API key from the [API keys](/learn/dashboard/configuration/api-keys) page in the Dashboard or by running [`fern token`](/learn/cli-api-reference/cli-reference/general-commands#fern-token). ### OpenAPI spec validation failed with N errors. Fix the errors above before generating docs. One or more [OpenAPI specs](/learn/docs/api-references/overview) referenced by the docs have fatal validation errors. The individual `: ` lines above this message identify the exact problem — fix those in your spec, then re-run `fern generate --docs`. > Publish your Fern docs to production and staging sites with automated workflows. Set up custom domains and manage deployments easily.