Publishing to Postman | Fern Documentation

Publish your Postman collection directly to Postman workspaces, making it easy for your team and API consumers to discover and test your endpoints.

This page assumes that you have:

An initialized fern folder. See Set up the fern folder.
A GitHub repository for your Postman collection. See Project structure.
A Postman generator group in generators.yml. See Postman Quickstart.

Generate an API key

Log into Postman

Log into Postman or create a new account.

Navigate to API Keys

Click on your profile picture.
Select Settings.
Select API Keys.

Generate key

Click on Generate API Key. Name your key, then click Generate.

Save your new token – it won’t be displayed after you leave the page.

Configure Postman publication

You’ll need to update your generators.yml file to configure the output location, repository, publishing mode, and authentication credentials for Postman publishing. Your generators.yml should live in your source repository (or on your local machine), not the repository that contains your Postman collection file.

Configure `output` location

In the group for your Postman collection, change the output location from local-file-system (the default) to postman to indicate that Fern should publish your collection directly to Postman:

generators.yml

1 groups: 
2   postman: # Group name for your Postman collection
3     generators:
4       - name: fernapi/fern-postman
5         version: 0.4.2
6         output:
7           location: postman

Add repository location

Add the path to the GitHub repository containing your Postman collection:

generators.yml

1 groups: 
2 postman:
3   generators:
4     - name: fernapi/fern-postman
5     version: 0.4.2
6     output:
7       location: postman
8     github: 
9       repository: your-org/company-postman

Choose your publishing mode

Optionally set the mode to control how Fern handles Postman publishing:

mode: release (default): Fern generates code, commits to main, and tags a release automatically
mode: pull-request: Fern generates code and creates a PR for you to review before release
mode: push: Fern generates code and pushes to a branch you specify for you to review before release

You can also configure other settings, like the reviewers or license. Refer to the full github (generators.yml) reference for more information.

generators.yml

1 groups: 
2   postman:
3     generators:
4       - name: fernapi/fern-postman
5       version: 0.4.2
6       output:
7         location: postman
8       github: 
9         repository: your-org/company-postman
10         mode: push
11         branch: your-branch-name

Configure Postman API key

Add api-key: ${POSTMAN_API_KEY} to generators.yml to tell Fern to use your API key for authentication when publishing to a Postman collection.

generators.yml

1 groups: 
2 postman:
3   generators:
4     - name: fernapi/fern-postman
5     version: 0.4.2
6     output:
7       location: postman
8       api-key: ${POSTMAN_API_KEY}
9     github: 
10       repository: your-org/company-postman

Choose your versioning approach

Fern’s Postman publishing uses a simple versioning approach based on whether you specify a collection-id:

Update existing collection: Specify collection-id. Fern updates the same collection each time. Use this option to keep your workspace clean with one collection that is always current.
Create new collections: Omit collection-id. Fern creates a new collection with each publish. Use this option to maintain historical versions or separate environment collections.

Publish as a new collection

Specify the workspace ID

You can get your workspace ID by navigating to your workspace and either:

Copying the ID from the URL: https://user-name.postman.co/workspace/workspace-name~WORKSPACE-ID/request/create
Making a GET request to https://api.getpostman.com/workspaces. You must also enter your API key in the Auth tab. This request returns configuration, including IDs, for all of your workspaces.

generators.yml

1 groups:
2   postman:
3     generators:
4       - name: fernapi/fern-postman
5         version: 0.4.0
6         output:
7           location: postman
8           api-key: ${POSTMAN_API_KEY}
9           workspace-id: your-workspace-id
10         github: 
11           repository: your-org/company-postman

Specify the collection name

Set the name for your new collection. Each time you publish, Fern creates a new collection with this name in the specified workspace.

generators.yml

1 groups:
2   postman:
3     generators:
4       - name: fernapi/fern-postman
5         version: 0.4.2
6         output:
7           location: postman
8           api-key: ${POSTMAN_API_KEY}
9           workspace-id: your-workspace-id
10         config:
11           collection-name: My collection name # Creates new collection called "My collection name"
12         github: 
13           repository: your-org/company-postman

Publish to an existing collection

To publish to a existing collection, specify the workspace ID, existing collection ID, and name of the existing collection.

Specify the workspace ID

You can get your workspace ID by navigating to your workspace and either:

Copying the ID from the URL: https://user-name.postman.co/workspace/workspace-name~WORKSPACE-ID/request/create
Making a GET request to https://api.getpostman.com/workspaces. You must also enter your API key in the Auth tab. This request returns configuration, including IDs, for all of your workspaces.

generators.yml

1 groups:
2   postman:
3     generators:
4       - name: fernapi/fern-postman
5         version: 0.4.0
6         output:
7           location: postman
8           api-key: ${POSTMAN_API_KEY}
9           workspace-id: your-workspace-id
10         github: 
11           repository: your-org/company-postman

Specify the collection name and ID

You can get your collection name and ID by navigating to your workspace and either:

Copying the ID from the URL: https://user-name.postman.co/workspace/workspace-name~workspace-id/collection/COLLECTION-ID
Making a GET request to https://api.getpostman.com/collections. You must also enter your API key in the Auth tab. Send the request. This request returns configuration, including IDs and names, for all of your collections.

generators.yml

1 groups:
2   postman:
3     generators:
4       - name: fernapi/fern-postman
5         version: 0.4.2
6         output:
7           location: postman
8           api-key: ${POSTMAN_API_KEY}
9           workspace-id: your-workspace-id
10           collection-id: your-collection-id
11         config:
12           collection-name: Your collection name # Name of the existing collection
13         github: 
14           repository: your-org/company-postman

Publish your collection

Decide how you want to publish your collection to Postman. You can use GitHub workflows for automated releases or publish directly via the CLI.

Release via a GitHub workflow

Set up a release workflow via GitHub Actions so you can trigger new Postman collection releases directly from your source repository.

Set up authentication

Open your source repository in GitHub. Click on the Settings tab. Then, under the Security section, open Secrets and variables > Actions.

You can also use the url https://github.com/<your-repo>/settings/secrets/actions.

Add secret for your API key

Select New repository secret.
Name your secret POSTMAN_API_KEY.
Add the corresponding API key you generated above.
Click Add secret.

Add secret for your Fern Token

Select New repository secret.
Name your secret FERN_TOKEN.
Add your Fern token. If you don’t already have one, generate one by running fern token. By default, the fern_token is generated for the organization listed in fern.config.json.
Click Add secret.

Set up a new workflow

Set up a CI workflow that you can manually trigger from the GitHub UI. In your repository, navigate to Actions. Select New workflow, then Set up workflow yourself. Add a workflow that’s similar to this:

.github/workflows/publish.yml

1 name: Publish Postman collection
2 
3 on:
4   workflow_dispatch:
5     inputs:
6       version:
7         description: "The version of the Postman collection that you would like to release"
8         required: true
9         type: string
10 
11 jobs:
12   release:
13     runs-on: ubuntu-latest
14     steps:
15       - name: Checkout repo
16         uses: actions/checkout@v4
17 
18       - name: Install Fern CLI
19         run: npm install -g fern-api
20 
21       - name: Release Postman collection
22         env:
23           FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
24           POSTMAN_API_KEY: ${{ secrets.POSTMAN_API_KEY }}
25         run: |
26           fern generate --group postman --version ${{ inputs.version }} --log-level debug

You can alternatively configure your workflow to execute on: [push]. See Vapi’s npm publishing GitHub Action for an example.

Regenerate and release your collection

Navigate to the Actions tab, select the workflow you just created, specify a version number, and click Run workflow. This regenerates your collection.

Specifying the version number will update the release number in your GitHub repository, but won’t version your collection.

The rest of the release process depends on your chosen mode:

Release mode (default): If you didn’t specify a mode or set mode: release, no further action is required. Fern initiates the publishing workflow in your collection repository.
Pull request or push mode: If you set mode: pull-request or mode: push, Fern creates a pull request or pushes to a branch respectively. Review and merge the PR (pull-request) or branch (push), then tag a new release to initiate the publishing

Once the workflow completes, you can view your new or updated collection by logging into Postman and navigating to your workspace.

Release via CLI and environment variables

Set Postman environment variable

Set the POSTMAN_API_KEY environment variable on your local machine:

$ export POSTMAN_API_KEY=your-actual-postman-api-key

Regenerate and release your collection

Regenerate your collection.

The --version parameter in fern generate --version X.X.X creates a GitHub release tag but doesn’t affect Postman collection naming or versioning. Collection versioning is controlled by the collection-id configuration.

$ fern generate --group postman --version <version>

The rest of the release process depends on your chosen mode:

Release mode (default): If you didn’t specify a mode or set mode: release, no further action is required. Fern initiates the publishing workflow in your collection repository.
Pull request or push mode: If you set mode: pull-request or mode: push, Fern creates a pull request or pushes to a branch respectively. Review and merge the PR (pull-request) or branch (push), then tag a new release to initiate the publishing

Once the workflow completes, you can view your new or updated collection by logging into Postman and navigating to your workspace.

Generate an API key

Log into Postman

Navigate to API Keys

Generate key

Configure Postman publication

Configure output location

Add repository location

Choose your publishing mode

Configure Postman API key

Choose your versioning approach

Publish as a new collection

Specify the workspace ID

Specify the collection name

Publish to an existing collection

Specify the workspace ID

Specify the collection name and ID

Publish your collection

Release via a GitHub workflow

Set up authentication

Add secret for your API key

Add secret for your Fern Token

Set up a new workflow

Regenerate and release your collection

Release via CLI and environment variables

Set Postman environment variable

Regenerate and release your collection

Configure `output` location