Sync your OpenAPI Specification

If you host your OpenAPI Specification at a publicly available URL, you can have Fern programmatically fetch the latest spec on a preconfigured cadence through the sync-openapi GitHub Action. This ensures your committed OpenAPI spec stays up to date with your live API.

Setup

Configure the origin URL

Add the origin field to your generators.yml to specify where your OpenAPI spec is hosted:

generators.yml

1  api:
2    path: openapi/openapi.json
3    origin: https://api.example.com/openapi.json

Add the GitHub Action

Create .github/workflows/sync-openapi.yml in your repository:

1 name: Sync OpenAPI Specs # can be customized
2 on:                               # additional custom triggers can be configured
3   workflow_dispatch:              # manual dispatch
4   push:                                          
5     branches:
6       - main                      # on push to main
7   schedule:
8     - cron: '0 3 * * *'           # everyday at 3:00 AM UTC
9 jobs:
10 update-from-source:
11   runs-on: ubuntu-latest
12   steps:
13     - uses: actions/checkout@v4
14       with:
15         token: ${{ secrets.OPENAPI_SYNC_TOKEN }}
16     - name: Update API with Fern
17       uses: fern-api/sync-openapi@v2
18       with:
19         update_from_source: true
20         token: ${{ secrets.OPENAPI_SYNC_TOKEN }}
21         branch: 'update-api'
22         auto_merge: false
23         add_timestamp: true

Add a GitHub token

Generate a fine-grained personal access token with read/write access to your repository.

Add to Repository Secrets

Navigate to your repository’s Settings > Secrets and variables > Actions. Select New repository secret, name it OPENAPI_SYNC_TOKEN, add your token, and click Add secret.

By default, this will create daily PRs with API spec updates to the repo containing your Fern folder. If you would like to adjust the frequency, learn more about GitHub’s schedule event.

For detailed configuration options and other use cases, see the sync-openapi GitHub Action README.