Work with Git in Katalon Studio
A Katalon Studio project lives on your machine as a local project. Only you can see and change it. To share a project and work on it with your team, connect it to a Git repository.
With Git integration, you can:
- Collaborate on one project: Teammates work on the same test cases, objects, and keywords, then share their changes through a remote repository, such as GitHub, GitLab, Bitbucket, or Azure DevOps.
- Track every change: See who changed what and when, and go back to an earlier version when needed.
- Work in parallel: Use branches to build and review tests without affecting your team's main project.
- Run tests from one source: Use the same repository for CI/CD pipelines and other Katalon products.
Katalon Studio has Git built in, so you can do all of this without leaving the app.
Choose your starting point:
- Your team already has the project in a Git repository: Enable Git integration, then clone the repository.
- You have a local project that isn't in Git yet: Enable Git integration, then publish your project as a Git repository.
After that, the daily workflow is: pull your team's latest changes, make your changes, commit, and push.
You'll need:
- A Git account and access to the remote repository.
- A personal access token for HTTPS connections, or SSH keys. See Create a personal access token.
Enable Git integration
-
Go to Katalon Studio > Preferences > Katalon > Git.
Shortcut:
⌘+,(macOS) orCtrl+Shift+P(Windows). -
Select Enable Git Integration.
-
Click Apply and Close.
The Git icon appears in the main toolbar.
For advanced settings, go to Katalon Studio > Preferences > Team > Git.
Git action menu
After you enable Git integration, the Git icon appears in the main toolbar. Click its dropdown arrow to open the Git menu.
| Option | What it does |
|---|---|
| Clone Project | Copy a remote Git repository to your machine and open it in Katalon Studio. |
| Share Project | Turn the current local project into a Git repository. Available only for projects that aren't under Git yet. |
| Show History | View commits, branches, and tags of the current repository. |
| Manage Branches | Create, check out, or delete branches. |
| Commit | Save staged changes to your local branch. |
| Push | Upload local commits to the remote repository. |
| Pull | Fetch remote changes and merge them into your current branch. |
| Fetch | Download remote changes without merging them. |
Clone a Git repository
Clone an existing Git repository to a new folder on your machine.
-
Open Git dropdown menu > Clone Project. You can also click Clone Git Project in the Tests Explorer.
The Clone Git Repository dialog appears.
-
On the Source Git Repository page, enter the repository details, then click Next. To use SSH instead of HTTPS, see Connect to Git with SSH keys.
- Repository URL: The HTTPS URL of your repository. To get it, open the repository on GitHub, GitLab, Bitbucket, or Azure DevOps, click Clone, select HTTPS, and copy the URL. See About remote repositories.
- User: Your Git username.
- Password: Your personal access token (PAT), not your account password. See Create a personal access token.
- Save authentication: Store your credentials so you don't need to enter them again when you push, pull, or fetch.
-
On the Branch Selection page, select the branches to clone, then click Next.
- Use the filter box to find a branch, or click Select All or Deselect All.
- Under Tag fetching strategy, choose how to fetch tags:
- When fetching a commit, also fetch its tags (default): fetches only tags that point to cloned commits.
- Fetch all tags and their commits: fetches every tag in the repository.
- Don't fetch any tags: skips tags.
-
On the Local Destination page, set where to store the project, then click Finish.
- Directory: the local folder for the cloned project. Click Browse to choose another folder.
- Initial branch: the branch to check out after cloning.
-
When you open the cloned project for the first time, Katalon Studio asks whether you trust it. See Trust dialog on first open.
- If your Git credentials change, clone the repository again with the new credentials.
- Katalon Studio doesn't support AWS CodeCommit.
Create a personal access token
Git hosts require a personal access token instead of your account password for HTTPS connections. The token needs read and write access to your repository. With read-only access, you can clone and pull, but push fails.
For GitHub tokens:
- Fine-grained token: Under Repository access, select your repository. Under Repository permissions, set Contents to Read and write.
- Classic token: Select the
reposcope.
To create a token, see:
-
GitHub: Creating a personal access token.
-
GitLab: Create a personal access token.
-
Bitbucket: HTTP access tokens.
-
Azure Repos: Click Generate Git Credentials, then copy the Username and Password into the User and Password fields in Katalon Studio. See Use personal access tokens.
Troubleshoot SSL errors
If you can't reach the repository after clicking Next, the connection might fail SSL verification. As a last resort, you can turn off SSL verification:
git config --global http.sslVerify false
Turning off SSL verification makes your connection less secure. Turn it back on with git config --global http.sslVerify true once the issue is resolved.
Trust dialog on first open
When you first open a cloned project, review its path in the Trust and open this project dialog.
Click Trust Project if you trust the source, or Don't Open if you're unsure. To trust other projects directly in the parent folder, select Trust all projects in the parent folder before clicking Trust Project. Projects in nested folders require separate approval.
Connect to Git with SSH keys
To connect to Git with SSH keys, see Git integration authentication with SSH keys.
Katalon Studio supports SSH SHA-1, RSA-1024, and RSA-2048 private keys. GitHub no longer supports DSA and RSA SHA-1 keys, so you can't connect to GitHub with SSH. SSH still works with GitLab, Bitbucket, and Azure DevOps.
To work with GitHub, use one of these instead:
- HTTPS with a personal access token. See Clone a Git repository.
- Git in a terminal.
- A third-party Git tool.
Publish a local project as a Git repository
Use Share Project to turn a local Katalon Studio project into a Git repository.
-
In the main toolbar, click the Git dropdown arrow > Share Project.
Katalon Studio creates a .git folder and a .gitignore file in your project.
-
Review .gitignore. It tells Git which files to ignore. By default, it contains:
/bin /Libs .settings .classpath /.svn
Commit
Commit saves your staged changes to your local branch. For details, see Git commit.
-
In the main toolbar, click the Git dropdown arrow > Commit.
The Git Staging tab appears.
- Unstaged Changes: Changes you've made but haven't staged.
- Staged Changes: Changes to include in the next commit.
- Commit Message: A short description of what changed.
- Author/Committer: Your Git name and email. Katalon Studio fills these in from your Git settings.
-
In Unstaged Changes, select the changes to commit, right-click, and select Add to Index. You can also drag them to Staged Changes.
-
Enter a Commit Message.
tipIf you use the Katalon Studio - Copilot build, click the GitHub Copilot icon (highlighted in the screenshot above) to generate a commit message from your staged changes. Review and edit the message before you commit. To set up GitHub Copilot, see GitHub Copilot.
-
Do one of the following:
- Click Commit to save the changes to your local branch only.
- Click Commit and Push to save the changes and push them to the remote repository in one step. See Push.
Manage branches
Click the Git dropdown arrow > Manage Branches to create, check out, or delete branches.
New branch
-
Click the Git dropdown arrow > Manage Branches > New Branch.
The Create Branch dialog appears.
Field Description Source The local or remote branch to create the new branch from. 
Branch name The name of the new branch. Checkout new branch Switch to the new branch after it's created. -
Click Finish.
Checkout branch
Check out a branch to switch your working branch.
-
Click the Git dropdown arrow > Manage Branches > Checkout Branch.
The Select Source dialog appears. A check mark (√) marks your current branch.
-
Select the branch to check out, then click OK.
Delete branch
-
Click the Git dropdown arrow > Manage Branches > Delete Branch.
The Delete Branch dialog lists local and remote branches.
-
Select the branch to delete, then click OK.
Push
Push uploads your local commits to the remote repository. For details, see Git push.
Commit your changes before you push.
-
In the main toolbar, click the Git dropdown arrow > Push.
The Push Branch dialog appears.
-
In Remote branch, select the branch to update, then click Next.
tipTo create a new remote branch, enter a name that doesn't match an existing branch.
-
In the Push Confirmation dialog, review your commits, then click Finish.
If you didn't save your credentials when cloning, Katalon Studio prompts you to log in when you push, pull, or fetch.
Pull
Pull fetches changes from the remote repository and merges them into your current branch. For details, see Git pull.
-
In the main toolbar, click the Git dropdown arrow > Pull.
The Pull dialog appears.
-
Select the remote branch to pull from, then click Finish.
-
Review the Pull Result dialog, then click OK.
Fetch
Fetch downloads changes from remote branches without merging them into your work. For details, see Git fetch.
-
In the main toolbar, click the Git dropdown arrow > Fetch.
The Fetch Results dialog shows the remote branches, tags, and changes that were fetched.
-
To review what was fetched, click the Git dropdown arrow > Show History.
The History tab shows the fetched branches and tags.
Resolve Git conflicts using Katalon Studio
Why do we have Git conflicts?
- In a source control system like Git, conflicts occur when two or more people make changes to the same file concurrently. The conflicts may appear at a member's local repository or Git remote repository.
- To avoid conflicts, the team must collaborate following several Git practices. For example, before pushing new source code to the Git remote repository, one must remember to fetch the latest version from Git remote repository, resolve any conflicts, and merge the code with the local version.
Expand to view anexample of how to resolve Git conflicts using Katalon Studio
- The chart below demonstrates how conflicts may occur when Tom and Emma are working on the same project. The conflicts occur when Tom and Emma try to push new code to the Git remote repository without updating the changes from each other.

Given situation:
-
Tom and Emma are working on the same test case in a test project. Emma added a new comment ("EMMA ADDED THIS COMMENT"), then committed and pushed the change to the Git remote repository.
-
At almost the same time, Tom added a new comment ("TOM ADDED THIS COMMENT"), then committed and tried to push to the Git remote repository.

- Because Emma pushed first, the version of code in Git was different from the version of code in Tom's local repository. Therefore, Git rejected Tom's push action.
Question: What should Tom do to push his change to the remote repository?
- First, Tom has to pull the code from the Git remote repository to his local machine.

- Tom sees a message about the conflict:

- In the Script mode of the test case TC2_Verify Successful Appointment in Tom's Katalon Studio project, there are errors with indicators such as
<<<<<<<(convention from Git). Let's look at the script more carefully:

- Recall that the comments were added by Tom and Emma, and the conflict is now on Tom's Katalon Studio project. Everything within
"<<<<<<< HEAD"and"======="is the change from Tom. And, everything within"======="and">>>>>>> branch 'master'…"comes from Emma, which is currently in the Git remote repository. - Now Tom has to decide which change is correct, or both are correct or wrong. He replaces these lines of code with the correct ones. For example, "THIS IS THE CORRECT COMMENT":

- After resolving the conflict, Tom is now able to commit and push the change to the Git remote repository.
Best practices
Refer to these suggested best practices for Katalon-related projects.
- Don’t commit logs or reports. Exclude generated files like
Reports/, as they clutter history and cause conflicts. - Version-control profiles and test data when needed. Include files from
Profiles/andData Files/if tests rely on them. These are usually easy to merge—just document changes in commit messages. - Use Katalon Export/Import for enterprise sharing. Enterprise users can move test cases between projects using Tools > Utility > Test Artifacts Sharing, but rely on Git for daily work.
- Commit core test artifacts. Always include folders like
Test Cases/,Test Suites/,Object Repository/,Profiles/, andKeywords/to ensure full project functionality. - Keep your
.gitignoreclean. Ignore generated and IDE-specific files (Reports/,bin/,.cache/, etc.) to avoid clutter and merge issues. - Review project setting changes. Changes to
Project/Settings/(e.g., environment variables) should be limited and reviewed by the team. - Use Git submodules only if truly needed. For shared libraries or keyword packages across projects, Git submodules can help. They centralize shared code but add complexity, so use them only when necessary.
Troubleshooting
Push fails with "git-receive-pack not permitted"
Your token doesn't have write access, or you signed in with your GitHub password instead of a token.
- Create a token with read and write access. See Create a personal access token.
- Clear your saved credentials. See Katalon Studio keeps using old Git credentials (macOS).
- Push again, and enter your GitHub username and the new token when prompted.
Katalon Studio keeps using old Git credentials (macOS)
Katalon Studio stores Git credentials in Eclipse secure storage, not under "github.com" in Keychain. To reset them:
- If your profiles contain protected global variables, remove them. Then close Katalon Studio.
- Open Keychain Access, then search for and delete
equinox.secure.storage. Or rename thesecure_storagefile in~/.eclipse/org.eclipse.equinox.security/. - Reopen Katalon Studio, run a Git action, and enter your username and token when prompted.
This clears everything saved in Katalon Studio secure storage, not only Git credentials.