Hosting with GitLab

To host your Fern docs using GitLab, you will need to add a Fern token to your repository variables.

The following GitLab CI/CD workflow will generate a preview link of your docs on merge request and publish your docs when updates are made to main.

To add this to your GitLab Fern project, create a .gitlab-ci.yml file in the root of your repository.

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

Add a token to GitLab

1

Log in

Log into GitLab.

2

Navigate to CI/CD in settings

Click on the Settings tab in your repository. Then, click on CI/CD.

3

Add variable

Scroll to the Variables section and select Expand > Add variable. Add your key and value, deselect Protect variable, and then click Save changes.

Preview docs with GitLab

1

Contact us

To get set up with a GitLab pipeline to preview your docs automatically, reach out via your dedicated Slack channel or email.

2

Log in

Log into GitLab.

3

Navigate to Access Tokens

Click on the Settings tab in your repository. Then, click on Access Tokens.

4

Generate project access token

Click on Add new token. You then need to:

  • Add your token name
  • Select an expiry date (note: once the token expires, you will need to generate a new one)
  • Set role to Reporter
  • Set scope to api

When finished, click Create project access token.

Save your token

Be sure to save the generated token - it won’t be displayed after you leave the page.

5

Add token to repository variables

You can do this using the steps listed above.

Built with