Blog Posts BPMN DMN

Synchronize your KIE Sandbox workspace with Bitbucket or GitHub

Blog: Drools & jBPM Blog

1 Introduction 

KIE Sandbox now brings the possibility to synchronize your changes not only with GitHub, but also Bitbucket. 

Bitbucket has several variants of their offering. Only support for Bitbucket Cloud is available, namely – a publicly hosted instance. Other Bitbucket variants, being it Bitbucket Server or Bitbucket Data Center are not supported, due to significant differences in provided APIs.

Support for enterprise instances of Bitbucket Cloud will arrive in future. 

2 Connecting to an account 


For KIE Sandbox to be able to communicate with a given git instance, it needs to be provided a way to authenticate with. In the case of Bitbucket, the supported way is to use a so-called App password, in the case of GitHub, its name is Personal Access Token. They are long-lasting OAuth2 tokens with selected scopes that enable the actions in KIE Sandbox when working with our workspace. 

List of related OAuth2 scopes: 

Bitbucket scope Description
account For the initial authentication and user details retrieval (e.g., uuid of the user) 
repository  Read access to repositories of given user.
repository:write Write access to all the repositories the authorizing user has access to. 
repository:admin To create repositories 
snippet Read access to all the snippets the authorizing user has access to. 
snippet:write  Write access to all the snippets the authorizing user can edit
Required Bitbucket OAuth2 scopes (Available Scopes)

GitHub scope Description
(no-scope) Implicit read access to public repositories and Gists. 
repo Full access to public and private repositories.
gist Grants write access to Gists. 
Required GitHub OAuth2 scopes (Available scopes)

KIE Sandbox connected accounts 

Once we have a token, we need to configure the KIE Sandbox to make it available in there.  

You can configure the authentication in advance by visiting the Connected Accounts section in the top panel. KIE Sandbox serves as a modal where the user needs to specify required values. In the case of Bitbucket, it is a username and the app password OAuth2 token. This is a difference compared to GitHub, where the token itself carries the user information and is sufficient for authentication on its own. 

After the addition, you should see the account information together with usage statistics in your current instance of KIE Sandbox.  

Once you connect the account, it’s available in your workspaces through the Authentication source section in the Share dropdown. Where you can also connect to another account by using the respective link from the dropdown, which serves as a shortcut to the Connected Accounts section mentioned earlier. 

3 Collaboration is key (KIE) 

It’s always better to share. And with KIE Sandbox sharing is as easy as a single click to synchronize your changes with the remote location. 

KIE Sandbox does not aspire at replacing the interaction with the existing git tools or git vendor UI, rather it simplifies most common operations vital for the smooth experience when modelling your assets. 

Collaborate over an existing repository 

The ability to import projects and later synchronize your local changes back into the original location makes KIE Sandbox collaborative experience a breeze. 

Import from URL 

It all starts with a URL. You can import existing projects on KIE Sandbox main screen by pasting their respective URL into the From URL widget. Once it’s confirmed as supported, the widget itself queries git-related information to be used and presents it to the user allowing to override the identified defaults, e.g., to change a branch to be checked out (click Change… if you want to do so). 

After the project is imported, you’re taken into its workspace which is readily configured with the respective Authentication source, so you’re ready to Push or Pull without any further action. 

Supported import URL options 
Hostname URL Context  /:workspace/:repo  
/snippets/:workspace/:snippet_id/:snippet_name.git  /:org/:repo 
/:org/:repo/tree/:tree/:path* /:org/:repo/:tree/:path* or  /:user/:gistId/ 

Sharing local projects with the world 

Having created a complex project including several models, now you wonder how to get those to your colleagues? No need to download and send by email, just create a brand-new git repository based on your workspace contents. By picking a different Authentication source, you can select between all your connected git vendor accounts. 

Pick an authentication source 

The first step is to decide which Authentication source we’d like to use to share our workspace. Choice defines the actions allowed with the workspace further on. 

Editor toolbar reflects this decision in its Share dropdown, where only actions applicable to your setup are available upon Authentication source selection. 


Once you pick any of these options, your project is transformed into git-based workspace. Though there are some differences in how you can synchronize the contents, see them described below. 

Create a git repository 

Create a repository by clicking on the respective button provided in the Share dropdown. Afterwards a modal appears where you can specify an intended location, repository name, and its visibility. 

Location must be specified using a dynamically populated select field. The list of options is possible to be reload using the sync icon to its right. 

In the case of GitHub, we can choose between creating the repository under our user location and creating in a GitHub organization that we are members of.


In the case of Bitbucket we select from either personal or shared workspaces.

The repository name text field is populated with the value matching your workspace name, so if you’ve configured your workspace thoroughly, you should be all set. Though you are free to specify the name that suits your needs, with just a few limitations on the characters allowed guarded by validation.

The Public and Private checkboxes define the repository visibility. 

After the repository is created, you’re taken back into workspace, which is readily configured with the respective Authentication source, so you’re ready to Push or Pull without any further action. 

Create a Bitbucket Snippet or GitHub Gist 

Do you hesitate to create a separate repository for something you were just doodling? Then share it just as a Bitbucket Snippet or GitHub Gist. Both these options provide you with the ability to push or pull changes, share by URL, etc. 

After clicking the respective button, a new Modal dialog is displayed.

We must specify 

After confirming the dialog, the modal stays displayed until the operation is completed. After that notification alert with the newly created item is displayed.

When the creation succeeds, you’re taken back into the workspace, which is now configured accordingly. 

In comparison to the regular git repository Sync options above, you now have just a single operation listed there – update. 

This action allows you to promote the changes back into the original location. 

There is no choice to pull, i.e., update your workspace based on changes done either in Gist or Snippet. If you need a more flexible approach, let’s head for the following section. 

Turn Gist or Snippet into a regular git repository 

Working with a Snippet or Gist and you’re finally satisfied with the models? Or do you want a more flexible workflow requiring updating your workspace with remote changes? 

Turn your project into a regular git repository – the Share dropdown option is still there for Gist or Snippet–based workspaces. You’re not even limited to the same Authentication source here, e.g., for a GitHub Gist based workspace, you can easily share it as a Bitbucket repository afterwards, given that you have both accounts connected. 


The post Synchronize your KIE Sandbox workspace with Bitbucket or GitHub appeared first on KIE Community.

Leave a Comment

Get the BPI Web Feed

Using the HTML code below, you can display this Business Process Incubator page content with the current filter and sorting inside your web site for FREE.

Copy/Paste this code in your website html code:

<iframe src="" frameborder="0" scrolling="auto" width="100%" height="700">

Customizing your BPI Web Feed

You can click on the Get the BPI Web Feed link on any of our page to create the best possible feed for your site. Here are a few tips to customize your BPI Web Feed.

Customizing the Content Filter
On any page, you can add filter criteria using the MORE FILTERS interface:

Customizing the Content Filter

Customizing the Content Sorting
Clicking on the sorting options will also change the way your BPI Web Feed will be ordered on your site:

Get the BPI Web Feed

Some integration examples