Skip to main content

GitHub Configuration

Team Plan

Connect your workspace to a GitHub repository through a GitHub App. The connection works over HTTPS, and you choose the branch to sync with directly in ToolJet.

Role Required: Admin

1. Create a New Repository and Make an Initial Commit​

Create a new repository on your GitHub. The repository can be public or private. You can also use an existing repository. Make sure that the repository is empty, then create an initial commit (for example, by adding a README.md). This first commit initializes the repository and creates the default branch (such as main).

2. Create the GitHub App​

Setup a GitHub App and make sure it is created by the same owner as the Git repository. If you have multiple ToolJet instances, use this same GitHub App across all instances.

Register new GitHub App page with the GitHub App name, description, and Homepage URL fields

Enter your App details on the Register new GitHub App page and make sure to uncheck the Expire user authorization tokens and Active checkbox under Identifying and authorizing users and Webhook sections respectively.

Set the Homepage URL to the URL of your ToolJet instance. For ToolJet Cloud, use https://app.tooljet.com. For self-hosted ToolJet, use the URL of your own ToolJet instance.

note

Add the following Repository permissions:

  • Contents: Read & Write
  • Pull requests: Read & Write

After creating the GitHub App, you will be directed to the GitHub App Settings page.

note

Make sure to copy the App ID.

Next, generate the Private key (.pem key), download it, and store it securely. This information will be essential later when configuring GitSync.

GitHub App settings page showing the App ID and the prompt to generate a private key

3. Install the GitHub App​

To install your GitHub App, follow these steps:

  • Click on Install App on the GitHub App Settings page.
    GitHub App settings sidebar with Install App highlighted
  • Click the Install button next to your organization.
  • Select repositories option and select the repositories you want to connect to ToolJet.
  • You’ll be redirected to the installation page. The number at the end of the URL is the installation ID. Save this for later. 
    https://github.com/settings/installations/:installation_id

4. Configure GitHub in GitSync​

Navigate to the Workspace settings page and click on the Configure git sync tab. Then, enter the required configuration values after selecting GitHub as your repository provider.

GitHub configuration form in ToolJet with the Repository, Self hosted GitHub, and App access sections

The table below describes each configuration values:

Repository​

SettingDescription
Repo URLThe URL of the repository you created to use with ToolJet. (e.g https://github.com/your-org/repo-name.git)
Branch nameBranch name of your repo. By default, it uses the main branch.

Self-hosted GitHub (Optional)​

SettingDescription
GitHub enterprise URLThe domain used to access your self-hosted GitHub instance. If you use GitHub Cloud, you can leave this blank.
GitHub enterprise API URLThe API endpoint for your self-hosted GitHub instance. If you use GitHub Cloud, you can leave this blank. (e.g. https://[hostname]/api/v3/)

App Access​

SettingDescription
GitHub app IDThe GitHub App ID.
GitHub app installation IDThe GitHub installation ID.
GitHub app private keyPrivate key you downloaded after App creation.

Once you've entered the necessary configurations, click Save changes. Your workspace is now connected to your GitHub repository.

note

You can use the same credentials to configure a specific repository across multiple instances or workspaces.


Need Help?​