User Guide for the sync-postman CLI Tool

sync-postman is an open-source CLI tool designed to sync Postman collections and environments with GitHub. This allows teams to collaborate on Postman collections and environments securely and for free, without relying on paid Postman collaboration plans. Your API keys and credentials remain on your local machine, ensuring complete security and privacy.

Features

• Push Postman Collections and Environments to GitHub: Automatically sync your Postman data to a GitHub repository for version control and team collaboration.

• Pull Collections and Environments from GitHub: Fetch collections and environments from GitHub to Postman, ensuring all team members are working with the latest updates.

• Collaborative Workflow: Use GitHub's centralized repository to enable seamless collaboration among team members.

• Custom Branch Support: Specify branches for pushing and pulling collections, making it ideal for workflows involving feature branches.

• Hard Pull for Fresh Sync: Replace all Postman collections in your workspace with data from GitHub for a clean slate.

• Secure by Design: API keys and tokens are stored only on your local machine, ensuring maximum security.

• Configurable Setup: Customize your Postman and GitHub integration with an easy setup process.

Prerequisites

1. GitHub Repository:

   • Create a GitHub repository for your team to store and manage Postman collections.
   • Add your team members as collaborators to this repository.

2. GitHub Personal Access Token:

   • Generate a GitHub token with full repository access.
   • Learn how to create a GitHub token here.

3. Postman API Key:

   • Obtain your Postman API key from your Postman account.
   • Visit the Postman API keys page to generate a key.

4. Node.js:

   • Download and install Node.js from nodejs.org if you don’t already have it installed.

Installation

Install the sync-postman package globally using npm:

  npm install -g sync-postman

Initial Setup

Before using sync-postman, you need to configure it with your Postman and GitHub credentials:

  sync-postman setup

Follow the prompts to enter the following details:

• Postman API Key: Your Postman API key.
• GitHub Repository URL: The repository where collections and environments will be stored.
• GitHub Username: Your GitHub username.
• GitHub Token: A personal access token for accessing the GitHub API.

Reset a Specific Configuration

You can reset a specific configuration key (e.g., Postman API Key):

  sync-postman setup --reset POSTMAN_API_KEY

Following Keys for reset configs - POSTMAN_API_KEY, GITHUB_REPO, GITHUB_USERNAME, GITHUB_TOKEN

Usage

1. Push Postman Collections and Environments to GitHub

  sync-postman push

This command pushes your current Postman collections and environments to the specified GitHub repository. By default:

• A new branch is created with a timestamp.
• The main branch (main) is used as the source branch.

Optional Arguments:

• --branchName <branchName>: Specify a custom branch name for the push.
• --sourceBranch <sourceBranch>: Specify the source branch (default is main).

Example:

  sync-postman push --branchName feature-sync --sourceBranch dev

2. Pull Collections and Environments from GitHub

  sync-postman pull

This command pulls collections and environments from GitHub and updates them in Postman.

Optional Arguments:

• --hard: Perform a hard pull, replacing all Postman collections with GitHub data.
• --branch <branchName>: Specify the branch to pull data from (default is main).

Example:

  sync-postman pull --hard --branch feature-sync

3. Check Configuration

  sync-postman check-config

Displays the current configuration details.

Safe Workflow with Pull Requests

This npm package uses a pull request (PR) workflow to ensure safety when syncing collections and environments. Instead of directly pushing changes to the main branch, the package creates a new branch and opens a pull request. This approach offers the following benefits:

• Review Changes: Easily track what has changed in the collections or environments before merging.
• Prevent Overwriting: Avoid accidental overwrites of the main branch, preserving the integrity of existing collections and environments.
• Collaborate Seamlessly: Enable team members to review, approve, or comment on updates via GitHub's PR system.

By following this approach, the package ensures a controlled and transparent workflow, making it ideal for collaborative teams.

Workflow

1. Set Up Configuration: Use the sync-postman setup command to configure the CLI with Postman and GitHub credentials.

2. Push Collections to GitHub: Use the sync-postman push command to sync your Postman collections and environments to GitHub.

3. Collaborate via GitHub: Share the GitHub repository with your team. Team members can pull the latest collections using the sync-postman pull command.

4. Pull Updates: Use the sync-postman pull command to fetch updates from GitHub and sync them to your Postman workspace.

5. Hard Pull (Optional): Use sync-postman pull --hard to replace all existing collections in Postman with GitHub data.

Security

• Local Configuration: All sensitive information (Postman API Key, GitHub Token) is stored only on your local machine in the .sync-postman-config.json file located in your home directory.
• No External Sharing: Your credentials are never shared or transmitted outside your local environment.

Example Scenarios

Collaborative Team Workflow

1. Alice sets up sync-postman and pushes her collections to a shared GitHub repository.
2. Bob pulls the collections from GitHub using sync-postman pull and works on updates.
3. Bob pushes his changes back to GitHub using sync-postman push.
4. Alice pulls Bob's updates using sync-postman pull.

License

This project is licensed under the MIT License.