GitHub Integration

Last updated: July 2026

This document explains how to set up and manage a GitHub integration in Katalon True Platform.

Connect GitHub to Katalon True Platform to sync test cases and test suites between the two systems.

Katalon True Platform supports the following GitHub instance types and authentication methods:

• GitHub.com (SaaS): Use this instance type for repositories hosted on GitHub.com. You can authenticate with either GitHub App or Personal Access Token (PAT).
  • GitHub App: Authorizes repository access through a GitHub App installation and lets Katalon True Platform list installed repositories, branches, and target directories during project setup.
  • Personal Access Token (PAT): Use this method when GitHub App integration is unavailable or when you need to keep an existing PAT-based connection.
• Self-managed (on-premise): Use this instance type for GitHub Enterprise Server or another self-managed GitHub instance. This instance type supports Personal Access Token (PAT) authentication only. Katalon True Platform supports GitHub Server version 3.13.16 and above. Older versions may cause issues.

Find your starting point:

• You are setting up a GitHub.com (SaaS) connection via GitHub App? → Start from Step 1A.
• You are setting up a GitHub.com (SaaS) PAT connection or a Self-managed (on-premise) connection? → Start from Step 1B.
• Your organization is already connected and you just need to link a repository? → Skip to Step 2.
• You just need to push your edits on Katalon True Platform back to GitHub? → Skip to Step 3.

---

Step 1A: Authorize GitHub with GitHub App (Account-level)

This step establishes the connection between Katalon True Platform and GitHub.com (SaaS) through GitHub App access. No data is synced yet.

requirements

• You must have the Account Admin or System Admin role in Katalon True Platform.
• You must have permission in GitHub to install or manage GitHub Apps for the GitHub organization or account you want to connect.
• The GitHub App must have access to the repositories you want to sync with Katalon True Platform.

1. Go to Account Settings > Integrations and click + Create Integration.

2. In the Available Integration list, select GitHub.

3. For Instance Type, select GitHub.com (SaaS).

4. For Authentication method, select Connect GitHub App.

5. Click Connect GitHub App.

6. In the GitHub installation window, select the GitHub organization or account you want to connect.

7. Select the repositories that Katalon True Platform can access.

   You can select all repositories or only selected repositories. If you select only selected repositories, make sure to include every repository you want to link to Katalon projects.

Access Required

During installation, Katalon GitHub App requires the following settings:

• Repository permissions
  • Metadata: Read access
  • Contents: Read access
  • Webhooks: Read and write
• Subscribed events: Installation and Installation repositories

8. Click Install & Authorize in GitHub to complete the installation.
9. Return to Katalon True Platform after the GitHub window closes.

Result

When the connection is active, your GitHub integration will be listed under the Integration list.

• If the status initially shows as Inactive, reload the page to update the status to Active.
• If the connection was previously configured with a PAT for the same GitHub organization, Katalon True Platform upgrades the same connection to GitHub App access. The existing PAT is retained for compatibility, but repository sync and webhook setup use GitHub App access.
• If the GitHub App does not have access to a repository, the repository does not appear during project-level setup. To update repository access, open the connection and click Manage GitHub App.

---

Step 1B: Authorize GitHub with a Personal Access Token (Account-level)

This step establishes a PAT-based connection between Katalon True Platform and GitHub. No data is synced yet.

Use this method for GitHub.com (SaaS) PAT connections, existing PAT-based GitHub connections, or Self-managed (on-premise) GitHub instances. Self-managed (on-premise) instances support PAT authentication only.

requirements

• You must have the Account Admin or System Admin role in Katalon True Platform.
• The Personal Access Token (PAT) must be created by a user with full access to all repositories in the GitHub organization. Using a PAT with limited permissions may cause errors when integrating repositories at the project level.

1. Go to Account Settings > Integrations and click + Create Integration.

2. In the Available Integration list, select GitHub.

3. Select GitHub.com (SaaS) instance type and Use Personal Access Token authentication method.

4. Fill in the required fields:

   • Integration Name: A custom label (max 50 characters).

   • Organization Account URL: Your GitHub organization URL, for example https://github.com/your-org-name.

   • GitHub Personal Access Token: To generate a PAT, refer to this GitHub documentation on creating a personal access token.

     PAT Permission Requirements

     This PAT is also used to automatically create GitHub webhooks during project-level setup, so webhook permissions are required.

     Fine-grained PAT

     • Contents: Read and write
     • Metadata: Read access
     • Webhooks: Read and write

     

     Classic PAT

     • Must be created by a repository Admin.
     • Must grant full permissions for the repo scope.

   • Description (Optional): Max 255 characters.

5. If connecting to Self-managed (on-premise), fill in the same fields above and optionally select an active tunnel that can access your GitHub server.

   If no tunnel is available, set up a new tunnel first. See Configure Katalon Tunnel.
   Supported GitHub Server version: 3.13.16 and above. Older versions may cause issues.

6. Click Test Connection to verify the connection is successful, then Save.

Result

If the connection is active, your GitHub integration will be listed under the Integration list.

• If the status initially shows as Inactive, reload the page to update the status to Active.
• If the status shows Error, check that all required configuration fields, especially the PAT, are valid and configured correctly.

---

Step 2: Link Repository to Project (Project-level)

This step shows how to connect a specific GitHub repository, branch, or directory to your Katalon True Platform project and sync test data.

requirements

• You must have the Project Admin role in this project. Account Admins and System Admins without the project's Project Admin role cannot configure this.
• A GitHub connection must already be configured at the account level using GitHub App or PAT.
• For GitHub App connections, the GitHub App must have access to the repository you want to link.
• For Self-managed (on-premise) repositories, your GitHub account needs to have an admin role within that repository.

1. Navigate to your specific project's UI > Settings > Integrations.
2. On your linked GitHub connection, click the right edge and select New configuration (Settings icon).

3. Fill in the project-level configuration fields.

   For a GitHub App connection, fill in the following fields:

   • Display Name: A custom name for the linked project (max 50 characters).
   • Repository: Select a repository from the repositories available to the GitHub App installation.
   • Branch: Select the branch you want to sync.
   • Target Directory: Enter the folder path you want to sync. Leave this field empty to use the repository root.
   • Link existing test execution results with test cases having the exact same paths and names (Optional): Enable this if you want Katalon True Platform to automatically attach existing test results to test cases and test suites whose paths and names match your GitHub structure.
   • Description (Optional): A brief description of this linked project (max 255 characters).

   For example, select repository katalon-studio/katalon-repo, branch main, and leave Target Directory empty to sync from the repository root. To sync from a folder, enter a path such as Test Cases.

   For a PAT-based connection, fill in the following fields:

   • Display Name: A custom name for the linked project (max 50 characters).
   • URL: The URL to the desired repository, branch, or directory from the linked GitHub account. Copy and paste the URL into this field.
     • For example: If you linked a connection under https://github.com/katalon-studio, then the URL should look like: https://github.com/katalon-studio/katalon-repo/tree/main.
   • Link existing test execution results with test cases having the exact same paths and names (Optional): Enable this if you want Katalon True Platform to automatically attach existing test results to test cases and test suites whose paths and names match your GitHub structure.
   • Description (Optional): A brief description of this linked project (max 255 characters).

4. Click Proceed to sync data and finalize the connection. Katalon True Platform automatically syncs your project with the GitHub repository.

   • A GitHub webhook is created automatically, enabling real-time updates such as test results and GitHub action triggers.
   • If webhook creation succeeds → The integration status updates to Active.
   • If webhook creation fails → The status shows Inactive, with an error message: "Failed to create GitHub webhook. Please try again." You can retry by clicking Proceed again once the issue is resolved.

   Additional behavior:

   • If the status initially shows as Inactive, reload the page to update the status to Active.
   • If you modify the connection details and click Save, the changes are saved, but the status may remain Inactive. To sync data and finalize the connection, you must click Proceed.

5. [Optional] To edit an existing linked GitHub integration, click the Edit (pen) icon, make the necessary changes, and click Proceed. After editing, reload the page to ensure data is refreshed.

Result

Your GitHub repository is now active within your project and test data has been synced from GitHub to Katalon True Platform.

---

Step 3: Enable Updates to GitHub

This step is only required if you edit test cases in Katalon True Platform and want those changes to sync to GitHub. Each user must complete this setup individually.

Before enabling sync from Katalon True Platform to GitHub, ensure that:

• GitHub is connected at the account level (Step 1).
• A repository is linked at the project level (Step 2).
• You have write permissions for the repository in GitHub.

By default, changes you make in Katalon True Platform, such as priority, assignee, or structure, remain local. To push these changes back to GitHub, you need to provide your own Personal Access Token (PAT). Katalon True Platform uses this token to sync changes on your behalf.

note

GitHub App access is used for repository sync and webhook setup. Publishing updates from Katalon True Platform back to GitHub still requires a user-level PAT.

1. Go to User Settings > Personal Integration.
2. Click the settings icon next to the integration you want to configure.
3. Enter your User Email and GitHub Personal Access Token (PAT).
4. Click Save.

Once saved, any edits you make to artifacts in linked repositories within Katalon True Platform will automatically sync back to GitHub.

---

View Test Cases or Test Suites Synced from GitHub

To view test cases or test suites synced from the linked GitHub integration, navigate to Tests > Test Cases/Test Suites.

---

Manage your GitHub integration

Katalon True Platform provides multiple ways to manage GitHub integrations without losing historical data. This section covers how to manage GitHub App access, disconnect a connection, archive a project-level integration, and restore an archived integration.

• Use Manage GitHub App to update the repositories available to a GitHub App connection.
• Use Disconnect to disable GitHub integration across all projects (Account-level).
• Use Archive to disable GitHub connection for a single project (Project-level).

Katalon does not support permanently deleting integrations. This ensures audit history is preserved and enhances security and traceability.

Manage GitHub App access

Required role: Account Admin or System Admin in Katalon True Platform. You also need permission in GitHub to manage the GitHub App installation.

Use this flow when you need to add or remove repository access for a GitHub App connection.

1. Go to Account Settings > Integrations.
2. Open the GitHub connection that uses GitHub App access.
3. Click Manage GitHub App.
4. In GitHub, update the repository access for the Katalon GitHub App.
5. Save the change in GitHub and return to Katalon True Platform.

If the GitHub App is uninstalled or suspended in GitHub, Katalon True Platform updates the connection status. If the connection had an existing PAT before it was upgraded to GitHub App, Katalon True Platform can continue using the retained PAT mode. If no retained PAT exists, the connection becomes Inactive until you reinstall or reconnect the GitHub App.

Disconnect a GitHub Connection

Required role: Account Admin or System Admin.

Disconnecting makes the integration inactive across all projects. Katalon True Platform does not support fully deleting integrations, in order to preserve audit history.

1. Go to Account Settings > Integrations.

2. Click the Disconnect icon next to the connection.

3. Confirm by clicking Disconnect in the dialog.

   => The status changes to Inactive. All projects using this integration lose the ability to sync with GitHub.

4. To reconnect, click the Reconnect icon next to the integration and confirm. All projects will resume syncing once reconnected.

Archive a Linked Repo

Required role: Project Admin.

Archiving disables the connection for that project only — other projects using the same GitHub integration are unaffected. Archived configurations no longer appear in Project Settings, and any scheduled test runs will be canceled at runtime.

1. Go to Project Settings > Integrations.
2. Click the right edge of your linked connection and select Archive.
3. Confirm by clicking Archive in the dialog.

Result: The integration no longer appears in the Test Cases/Test Suites module. Any scheduled test runs in the Execution module will be automatically canceled at runtime.

Restore an Archived Integration

1. Go to Project Settings > Integrations.
2. Click New configuration (settings icon) on the GitHub connection.
3. Enter the same repository URL as the archived configuration and click Proceed.

Katalon True Platform will restore the archived configuration rather than creating a duplicate.