Note: Sync with Git applies only to Design Documents at this time. Collections use our own Insomnia Sync for versioning. To learn about version control sync for Collections, refer to Version Control Sync.
Sync with Git is a built-in feature for Design Documents that enables you to configure your repository to an external Git version control system like GitHub or BitBucket.
Pushing to a remote Git repository creates the
.insomnia directory that can also be used with Inso CLI.
Clone a remote Document from Git via the Create dropdown on the Dashboard view. You will be prompted to fill out remote Repository Settings to gain remote access.
The remote repository must contain the root
.insomnia directory, otherwise you will be prompted to create a new Design Document.
Note: This section assumes that you already have a remote Git repository.
Enable Git Sync on Design Documents by clicking on the Setup Git Sync button beside Preferences. Then select Repository Settings. A Configure Repository modal will open.
Inside a Design Document, click Setup Git Sync.
When configuring a remote repository, you can chose to connect with GitHub or GitLab, or manually set up a remote repository.
Click Authorize to allow Insomnia to connect with your GitLab account.
If successful, you will be redirected to the Insomnia website with the message “Successfully authenticated Insomnia”.
Return to the Insomnia app and wait for sync to finish.
app.insomnia.restinto the Insomnia app, then click Sync.
Note: You may fail to set up Git Sync properly due to not enough or the wrong types of Git permissions.
Find instructions on how to create a personal access token or app password on the following platforms:
public_repowhen creating your token.
repowhen creating your token.
apiwhen creating your personal access token.
Repositoryoptions when creating your app password.
Once complete, click Done and the repository settings will be persisted for future operations. The author details and token can be updated as needed.
When working with Git, it’s good practice to make changes in separate branches. This has two benefits:
Note: Remote branches will only appear if they do not already exist locally.
Commit your changes via the branch dropdown menu. You’ll be prompted to add a descriptive message as your commit message.
Pushing your changes to your remote repository for the first time creates the
.insomnia directory, which you can use with the Inso CLI.
Note: If you’d like to push to an alternative branch than the default, click on the branch dropdown menu. Select Branches, and add your desired branch name.
Commits and branches only exist locally when created. A push needs to be done to share the commits and history of a branch remotely. If pushing fails, you will be given the option to force push.
The push or force push operation can fail for many reasons, and logs will be presented in the Developer Console prefixed with
git-event with further debugging information. A likely cause is that your user does not have permissions to push to a protected branch.
For instance, with GitLab, the main/master branch is protected by default, and those with the developer role are unable to push directly to it. In that case, push to a separate branch and create a pull request, or update the permissions for your user on the repository.
If a collaborator makes a change to the remote repository, pull the changes to access the work locally. Click the branch dropdown menu in a Document and then Pull. Any incoming changes will be merged to your local machine.
Git sync does not currently support the ability to resolve conflicts within the application. If changes were made locally and remotely, a pull may fail.
Here are some strategies to help with conflicts:
Sign out of a synced Git management account.
The Configure Repository box will no longer list the account that was signed out in its list of configured accounts.