Git Sync

Table of Contents

Introduction

Insomnia Designer is a collaborative tool for creating, managing, and sharing API specifications. This collaboration is built on the ubiquitous version control system Git, which was chosen to allow Insomnia Designer to fit within the existing editing, review, testing, and deployment workflows that companies and teams already have in place for source code.

Introduction

Remote Repository Settings

To configure a repository, click the “Setup Git Sync” button to the top right of the header.

  • Git URI – The URI of the git repository you wish to connect to. Note, only https URLs are supported.
  • Author Name/Email – Git author metadata that will be stored with each commit
  • Authentication Token – The token needed to authenticate with remote repository provider (GitHub, Bintray, etc). If you have two-factor authentication (2FA) enabled on your account, it is unlikely you will be able to use your username and password. Instead, generate a Personal Access Token (or an App Password in Bitbucket lingo). Instructions for: Github | Gitlab | Bitbucket | Bitbucket Server.

Repo Settings

Once complete, click “Done” and the repository settings will be persisted for future operations. Author details and token can be updated after if needed.

Cloning an Existing Repository

If a team member has already pushed a Designer project to a remote repository, it can be cloned via the main menu in the top-right of the application on the Documents Listing view. Here, you will see the same Repository Settings dialog to configure remote access.

Note: Designer does not currently support repositories that contain files outside the root ".insomnia" folder.

In order to clone, the repository must exist and also contain the root .insomnia/ folder.

Cloning a Repo

Commits and History

A new commit can be created via the git menu at the top right of the header.

In the following example, you can see we are creating a new commit and adding the API Spec object. The descriptive message that will be saved in Git is entered in the input area.

Create a new commit

Once we create the commit, we can view it in the repository history.

View it in the repo history

Pushing Changes Remotely

Commits only exist locally when created. In order to collaborate, changes need to be pushed to the remote repository.

Push Changes

Managing Branches

When working with Git, it is recommended to perform changes in separate branches. This has two benefits:

  1. Reduces the chances of merge conflicts when team members are making frequent changes
  2. Supports a pull-request workflow where team members can leave feedback before merging

Local branches can be created from the branch management dialog. This dialog presents both local branches and remote branches. Note, remote branches will only appear if they do not already exist locally.

Managing Branches

Pushing Changes

Commits and branches only exist locally when created. A push needs to be done to share the commits and history of a branch remotely.

Pushing Changes

Pulling Changes

If a team member makes a change to the remote repository, they will need to be “pulled” down in order to use locally. Pulling will fetch the current branch from the remote repository and merge any changes locally.

Pulling Changes

Conflict Resolution

Designer does not currently support the ability to resolve conflicts. If changes were made locally and remotely, a pull may fail.

Here are some strategies to help with conflicts:

  • Each team member should make changes in a separate branch to avoid conflicts. Changes should be merged into master once reviewed and approved by other team members (eg. GitHub pull request)
  • If a conflict occurs on pull, delete the branch locally and re-fetch it from the branches dialog
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us