Skip to main content

Getting Started

This guide walks you through setting up Git Connectivity for the first time: configuring a Git provider, connecting an app to a repository, and performing your first commit and pull operations.

Step 1: Enable Git Connectivity​

Ensure that Git Connectivity is enabled in your Design application configuration:

flowable.design.git.enabled=true

This property is enabled by default when the JGit library is present on the classpath. If Git features are not available in your Design UI, verify this property is set.

Step 2: Configure a Git Provider​

Before connecting any app to a repository, you need to configure at least one Git provider. A provider defines how Design authenticates with your Git hosting platform.

  1. Navigate to the Git Providers management page in Design.
  2. Click Add Provider.
  3. Select a provider type (GitHub, GitLab, or Bitbucket).
  4. Fill in the required fields:
    • Name - A descriptive name for this provider configuration.
    • Server URL - The URL of your Git hosting server (e.g., https://github.com, https://gitlab.com, or your self-hosted instance).
    • Authentication details - Depending on the provider type, this may include a Personal Access Token, SSH key, or GitHub App configuration.
  5. Click Test Connection to verify that Design can connect to the Git server with the provided credentials.
  6. Save the provider configuration.

Add Git provider

tip

For a quick start, using a Personal Access Token (PAT) is the simplest authentication method for GitHub and GitLab. For organizational use, consider a GitHub App configuration for better access control.

Step 3: Connect an App to a Git Repository​

There are two ways to connect a Design app to a Git repository:

Option A: Clone from Git​

Use this option when you have an existing Git repository that already contains Flowable models, or when you want to start with a fresh repository.

  1. Navigate to your workspace.
  2. Choose the Clone from Git option.
  3. Select the Git provider to use.
  4. Enter the repository URL or browse available repositories (for GitHub, GitLab, and Bitbucket providers).
  5. Select the branch to clone (default: main).
  6. Optionally specify a sub-path if the models are located in a subdirectory of the repository (monorepo setup).
  7. Click Clone to create the app package from the repository contents.

Clone from Git

Option B: Connect an Existing App​

Use this option when you already have a Design app and want to start tracking it in Git.

  1. Open the app you want to connect.
  2. Open the Git panel and choose Setup Git.
  3. Select the Git provider to use.
  4. Enter the repository URL or browse available repositories.
  5. Select the branch.
  6. Optionally specify a sub-path for monorepo setups.
  7. Click Setup to establish the connection.
info

When connecting an existing app to a repository that already contains models, Design will detect any differences between the local app and the remote repository. You may need to resolve divergences before proceeding.

Step 4: Your First Commit​

Once your app is connected to a Git repository, any changes you make to models will be tracked by Git.

  1. Make a change to one of the models in your app (for example, edit a BPMN process or a form).
  2. Open the Git panel on the app details page.
  3. You will see the changed models listed with their modification status.
  4. Click Commit.
  5. Select which models to include in the commit (or select all).
  6. Write a descriptive commit message explaining what changed and why.
  7. Click Commit to push the changes to the remote repository.

Step 5: Pull Remote Changes​

When other team members push changes to the repository, you can pull those changes into your local app.

  1. Open the Git panel on the app details page.
  2. The status banner will indicate if remote changes are available.
  3. Click Pull to fetch and apply the remote changes.
  4. If there are no conflicts, the changes are applied and the app is updated.
  5. If conflicts are detected, you will be guided through the conflict resolution process.

What's Next​

Now that you have a Git-connected app, explore these topics to get the most out of Git Connectivity: