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. You need access to a supported Git hosting platform (GitHub, GitLab, or Bitbucket) with credentials for the repository you want to work with.

Step 1: Check that Git Connectivity is Enabled​

Git Connectivity is enabled by default. To turn it off, set the following property in your Design application configuration:

flowable.design.git.enabled=false

If Git features are not available in your Design UI, check that this property has not been set to false and, in a custom build, that the starter below is on the classpath.

Adding the Git connectivity dependency to a custom build

In a custom Design build the Git connectivity starter is not included by default. Add the following dependency to the pom.xml of your Design application:

<dependency>
    <groupId>com.flowable.design</groupId>
    <artifactId>flowable-spring-boot-starter-design-git</artifactId>
</dependency>

Step 2: Assign Permissions​

Before configuring a provider, make sure the users working with Git have the permissions they need:

  • Manage Git provider (tenant scoped) - Required to create and manage Git provider configurations.
  • Manage Git (app scoped) - Required to connect apps to repositories, switch branches, and manage Git configuration.
  • Push to Git (app scoped) - Required to commit and push changes to the remote repository.

These permissions are granted through the roles assigned to a user. See Custom roles for how to configure roles and their permissions.

note

Administrators have these permissions by default, so this step is only needed for other users.

Step 3: 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 4: 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 5: 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 6: 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: