Developer tools

Hosting with GitLab

View as Markdown

Use GitLab CI/CD to automatically generate preview links on merge requests and publish your Fern docs when changes are merged to main.

Prerequisites

Add a Fern token to GitLab

1

Generate a Fern token

Run fern token in your terminal from the directory containing your fern folder. This generates an organization-scoped token that authenticates the Fern CLI in CI/CD.

$fern token

Copy the token output — you’ll add it to GitLab in the next step.

2

Add the Fern token as a CI/CD variable

  1. Log in to GitLab and navigate to your Fern docs repository.
  2. Go to Settings > CI/CD.
  3. Scroll to the Variables section, select Expand, then click Add variable.
  4. Set the key to FERN_TOKEN, paste the token you generated in the previous step as the value, deselect Protect variable, and click Save changes.

Add a project access token to GitLab

To post preview links on merge requests, you need a GitLab project access token.

1

Create a project access token

  1. In your GitLab repository, go to Settings > Access Tokens.
  2. Click Add new token and configure the following:
    • Token name: a descriptive name (e.g., fern-preview)
    • Expiration date: set as needed (you’ll need to regenerate once it expires)
    • Role: Reporter
    • Scopes: api
  3. Click Create project access token and copy the token.
Save your token

Save the generated token immediately — it won’t be displayed after you leave the page.

2

Add the project access token as a CI/CD variable

  1. Go to Settings > CI/CD.
  2. Scroll to the Variables section, select Expand, then click Add variable.
  3. Set the key to REPO_TOKEN, paste the project access token as the value, deselect Protect variable, and click Save changes.

Add the CI/CD pipeline

Create a .gitlab-ci.yml file in the root of your repository. This pipeline validates your API definition, posts preview links on merge requests, and publishes your docs when changes are merged to main.

.gitlab-ci.yml
1stages:
2  - check
3  - preview_docs
4  - publish_docs
5
6before_script:
7  - apt-get update -y
8  - apt-get install -y curl
9  - curl -sL https://deb.nodesource.com/setup_current.x | bash -
10  - apt-get install -y nodejs
11  - npm install -g fern-api
12
13check:
14  stage: check
15  rules:
16    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
17    - if: '$CI_COMMIT_BRANCH == "main"'
18  script:
19    - echo "Checking API is valid"
20    - fern check
21
22preview_docs:
23  stage: preview_docs
24  rules:
25    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
26  script:
27    - echo "Generating preview..."
28    - |
29      OUTPUT=$(fern generate --docs --preview) || true
30      echo "$OUTPUT"
31      DEMO_URL=$(echo "$OUTPUT" | grep -oP -m1 '(https://[^\s]+-preview-[^\s]+)(?: )')
32      echo "Preview URL: $DEMO_URL"
33    - |
34      if [ -z "$DEMO_URL" ]; then
35        echo "No preview URL found"
36        exit 1
37      fi
38      curl --location --request POST \
39        --header "PRIVATE-TOKEN: $REPO_TOKEN" \
40        --header "Content-Type: application/json" \
41        --url "https://gitlab.com/api/v4/projects/$CI_MERGE_REQUEST_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/notes" \
42        --data-raw "{ \"body\": \"Preview your docs [here]($DEMO_URL)\" }"
43
44publish_docs:
45  stage: publish_docs
46  rules:
47    - if: '$CI_COMMIT_BRANCH == "main"'
48  script:
49    - echo "Publishing Docs"
50    - fern generate --docs

Commit and push the .gitlab-ci.yml file to your repository. The pipeline runs automatically when changes are merged to main.