Skip to main content

Setting Up GitHub

This example walks through setting up Git Connectivity with GitHub, covering the available authentication methods: Personal Access Token (simplest), GitHub App (recommended for organizations), and SSH Key.

Option 1: Personal Access Token (PAT)​

The simplest way to connect to GitHub. Best for individual developers or quick setups.

Step 1: Create a Personal Access Token on GitHub​

  1. Go to GitHub > Settings > Developer settings > Personal access tokens > Fine-grained tokens (or Classic tokens).
  2. Click Generate new token.
  3. Give the token a descriptive name (e.g., "Flowable Design").
  4. Set an expiration date.
  5. For fine-grained tokens, grant the following repository permissions:
    • Contents: Read and write
    • Pull requests: Read and write
    • Metadata: Read-only
  6. For classic tokens, select the repo scope.
  7. Click Generate token and copy the token value.
caution

Store the token securely. GitHub will only show it once. If you lose it, you'll need to generate a new one.

Step 2: Configure the GitHub Provider in Design​

  1. In Flowable Design, navigate to the Git Providers management page.
  2. Click Add Provider.
  3. Select GitHub as the provider type.
  4. Fill in the fields:
    • Name: e.g., "GitHub - Personal"
    • Server URL: https://github.com (or your GitHub Enterprise URL)
    • Authentication type: Personal Access Token
    • Access Token: Paste the token from Step 1
  5. Click Test Connection to verify.
  6. Save the provider.

Step 3: Clone or Connect a Repository​

  1. Navigate to your workspace.
  2. Choose Clone from Git to import an existing repository, or open an existing app and use Setup Git to connect it.
  3. Select the GitHub provider you just created.
  4. Browse and select the repository, or enter the repository URL manually.
  5. Select the branch (default: main).
  6. Complete the setup.

GitHub Apps provide fine-grained permissions and don't tie access to an individual user account.

Step 1: Create a GitHub App​

  1. Go to your GitHub organization's Settings > Developer settings > GitHub Apps.
  2. Click New GitHub App.
  3. Configure the app:
    • GitHub App name: e.g., "Flowable Design Integration"
    • Homepage URL: Your Flowable Design URL
    • Repository permissions:
      • Contents: Read & write
      • Pull requests: Read & write
      • Metadata: Read-only
    • Disable webhook (uncheck Active under Webhook).
  4. Click Create GitHub App.
  5. Note the App ID from the app's settings page.
  6. Generate a private key and download the .pem file.

Step 2: Install the GitHub App​

  1. From the GitHub App settings page, click Install App.
  2. Select the organization to install it on.
  3. Choose which repositories the app should have access to (all or specific ones).
  4. Complete the installation.
  5. Note the Installation ID from the URL of the installation page (the number in the URL after /installations/).

Step 3: Configure the GitHub App Provider in Design​

  1. In Flowable Design, navigate to the Git Providers management page.
  2. Click Add Provider.
  3. Select GitHub as the provider type.
  4. Fill in the fields:
    • Name: e.g., "GitHub - Organization App"
    • Server URL: https://github.com
    • Authentication type: GitHub App
    • App ID: The App ID from Step 1
    • Private Key: Paste the contents of the .pem file from Step 1
    • Installation ID: The Installation ID from Step 2
  5. Click Test Connection to verify.
  6. Save the provider.

Option 3: SSH Key​

SSH key authentication provides a secure, token-free way to authenticate with GitHub.

Step 1: Generate an SSH Key Pair​

  1. Open a terminal and run: 
    ssh-keygen -t ed25519 -C "flowable-design"
  2. Save the key pair to a file (e.g., ~/.ssh/flowable_design).
  3. Copy the public key: 
    cat ~/.ssh/flowable_design.pub

Step 2: Add the Public Key to GitHub​

  1. Go to GitHub > Settings > SSH and GPG keys.
  2. Click New SSH key.
  3. Give it a title (e.g., "Flowable Design") and paste the public key.
  4. Click Add SSH key.

Step 3: Configure the SSH Provider in Design​

  1. In Flowable Design, navigate to the Git Providers management page.
  2. Click Add Provider.
  3. Select GitHub as the provider type.
  4. Set the Authentication Method to SSH Key.
  5. Fill in the fields:
    • Name: e.g., "GitHub - SSH"
    • Server URL: https://github.com
    • Private Key: Paste the contents of the private key file (~/.ssh/flowable_design)
  6. Click Test Connection to verify.
  7. Save the provider.

Verifying the Setup​

After configuring the provider and connecting an app:

  1. Make a small change to a model in your app.
  2. Open the Git panel and click Commit.
  3. Enter a commit message and confirm.
  4. Open the repository on GitHub and verify the commit appears with the correct author and message.

GitHub Enterprise Server​

For GitHub Enterprise Server (self-hosted), the setup is identical to the options above. The only difference is the Server URL, which should point to your GitHub Enterprise instance (e.g., https://github.yourcompany.com).