Synchronize an Insomnia project with Git

Tech Preview and uses: Insomnia

This feature is currently in Tech Preview and should not be used in a production environment.

Prerequisites

Insomnia

Download and install Insomnia.

Git repository

When you create an Insomnia project with Git Sync, you can either add the repository now or later (if you’re using Insomnia 11.5 or later). If you want to add the repository when you create the project, you can either use an existing repository with Insomnia content or an empty repository.

Create a project

A Projects storage type isn’t fixed. If you have an existing cloud or local project, you can also update it to use Git Sync from the projects Settings option.

In your Insomnia organization, click the + button under PROJECTS in the left pane.
In the Project name field, name your project.
In the Type field, click Git Sync.
Select whether you want to clone the repository from GitHub, GitLab, or Git:

If you have not connected Insomnia to your GitHub account yet, click Authenticate with GitHub.
In the page that opens in your browser, click Continue, then click Authorize Kong.
Click Open Insomnia.
Ensure that the Insomnia GitHub App is installed and has access to the repository that you want to use, navigate to Github insomnia-desktop.
From your chosen repository, click Configure.
Select your GitHub account or organization.
Click Use passkey.
Under Repository access, ensure that the specific repository that you want to use allows access to the Insomnia GitHub App.
Click Update access.

If you use a managed GitHub account, you might not be able to install GitHub Apps. In this case, use the Git tab to configure the repository with the generic Git workflow. For more details, see the GitHub docs.
If needed, select a branch.
Click Scan for files.
Click Clone Project.

If your Git repository already contains Insomnia content, you will be prompted to import the content to your project. You can also create the Git Sync project now and add a repository later.

If the repository contains legacy Insomnia content prior to 11.0, Insomnia will convert this content to the new format introduced in newer versions.

Commit and push the content to your repository

Once you’ve created content or made changes to existing content in your project, you can push the changes to your repository:

From the bottom of the left pane, click the name of the branch.
Click Commit.
Enter a commit message.
Stage changes by clicking the + button next to the changes that you want to commit to the repository and click Commit.
Click the name of the branch again and click Push 1 Commit.

Git status notifications appear at the bottom right corner of the window.

FAQs

Why can I only see public repositories after connecting GitHub?

If you can see only public repositories but not private repositories, review your GitHub App installation settings.

Insomnia uses the GitHub App integration. The app must be granted access to private repositories during installation.

To verify repository access:

Navigate to Insomnia GitHub App.
Click Configure.
Select your account or organization.
Under Repository access, confirm that:
- All repositories is selected, or
- The required private repositories are explicitly included.
If you make changes, click Save.

After updating the installation settings, disconnect and reconnect GitHub in Insomnia if the repositories still don’t appear.

Which Personal Access Token should I use for Git Sync?

If you authenticate using a Personal Access Token (PAT), use a fine-grained PAT.

Navigate to Github Personal access tokens and ensure that the token is configured to allow access to the repositories you want to sync.

Why do I get a 403 error when committing?

A 403 Forbidden error usually indicates that Insomnia does not have access to the target repository.

If you use GitHub, navigate to Github applications to ensure that the Insomnia GitHub App is installed and has access to the repository.

If you use a managed GitHub account that restricts GitHub App installation, use the Git tab and configure the repository with the generic Git workflow instead.

I tried the Insomnia beta version and then downgraded back to the release version. Why do I get a ‘Could not find HEAD’ error?

You haven’t lost anything in your project, but after downgrading you need to specify which branch to use in your Git Sync project again. To fix the error:

Open your project.
Restart Insomnia.
Open the Git menu in the bottom-left corner.
Select your desired branch.