Share a Bonita project with Git

Bonita offers the possibility to share projects with Git. Sharing a project allows to improve teamwork effectiveness.

Git

Prerequisites

Git integration in Studio

Bonita Studio Git integration is based on the EGit Eclipse plugin.

Git commands available in the studio interface:

  • Share with Git
    This action connects the current project to Git and shares it on a remote. To configure the remote, see the following Egit user guide or the Share on GitHub howto.

  • Clone
    Create a new Studio project from an existing Git repository (that must contain a proper Bonita project). If the remote project version is lower than the studio, a migration will be applied on the cloned project. Be careful before pushing a migrated project back to the remote: all contributors will have to use the proper studio version.

If you used Bonita on Git before Bonita 7.7.0, you might want to clone it from the studio.
Be careful though: we cannot guarantee that cloning a Git repository not created with Bonita Studio will work properly.
However, to do so, first check that your project on GitHub is "Bonita compliant":

 * The Git repository content must includes a Bonita project (and not a Bonita workspace)
 * The .project file must be present
 * It is highly recommended to use the .gitignore file generated by Bonita when you share a Bonita project from the studio.

Still, the best way to proceed is to export the project from the older version of the studio (as a .bos file) and import it in the new studio, and then share this project on Git, although with this procedure, the history of revisions will be lost.

  • Commit…​
    Shortcut action to add, commit and push the local changes.

  • Push to Upstream
    Send the local committed changes to the configured upstream remote repository. You should make a pull before pushing.

  • Fetch from Upstream
    Download new data from the upstream remote repository. It doesn’t integrate any of this new data into your working files. Fetch is great for getting a fresh view on all the things that happened in a remote repository.

  • Push branch…​
    Send the local committed changes to a specific branch on the remote repository. If the push fails, you may need to use make force push with the command line tool.

  • Pull
    Fetch and try to integrate the remote changes of the current branch. This operation can put your repository in conflicting state. Use the Git staging view and provided merge tool to resolve the conflicts. You can abort the merge with a hard reset with the command line tool or the Reset... action.

  • Switch branch
    Change current branch, checkout a new branch from remote or create a new branch.

  • Merge
    Merge the content of a branch into current branch. Reference article

  • Reset
    Reset the content of the working tree to the head reference (latest commit).

  • Rebase…​
    Like a merge, you can retrieve the content of another using a rebase. It replay all commits of a selected branch into the current branch. Reference article

  • Git staging view
    This view display the current status of your repository. From this view you can stage/unstage your changes, commit and even commit and push. You can access to the compare editor using the contextual menu. More information available in EGit user guide.

  • History view
    This view display the commit history of the repository. More information available in EGit user guide.

  • Status This gives you connection information with the remote as well as the current status (ahead or behind) compared to the remote. This information is also available at the top of Bonita Studio window, as well as at the top of the Git Staging view.

Those commands can be found in the GIT entry in the coolbar.

Conflict management

The use of Git often lead to conflicts when contributions are merged. There is different ways to manage conflicts, with a diff tool, in a text editor…​
Bonita Studio integrates the default merge tool of EGit. Here are some hints on how to resolve conflicts using EGit: Manage conflicts using EGit.

Advanced Git commands

Git workflow offers a lot of other features that are not directly integrated in Bonita Studio. You can still use them using the command line interface (available here). To retrieve the location of your project on your filesystem do a right click on the project name in the project explorer and select Show in system explorer (default location of your project would be: /workspace/).

Authentication

The following authentication methods are supported:

  • Login and password

  • Login and token - use the password field for the token value

  • Ssh Key

Github requires a personal access token as credentials password when using HTTPS protocol.

Troubleshooting

  • My diagram has many validation issues after a clone / a switch branch operation: Keep in mind that Bonita artifacts (Business Data Model, Organization, Profiles, Applications, Pages …​) are not redeployed when you perform a clone or a switch branch operation. So, if you switch from a branch A to a branch B, you may need for example to deploy manually your BDM to ensure that all the business objects specific to the branch B are available.

  • My git history view is empty: The history view is based on the active editor or the current selection (in Eclipse, a selection is a file selected in a package explorer). Sometimes you can manage to open the history view without having any active editor and nothing selected (which is often the case in Bonita because we only provide a package explorer in the REST API extensions editor) -> the history view does not display anything. Just open a diagram for example and then re-open your history view.

  • Cloning a repository hosted on Azure DevOps When authentication to azure dev ops git repository uses SSO, cloning using https and Microsoft dedicated eclipse plugin is not supported (e.g. https://user@dev.azure.com/organization/repository/_git/repository). Use SSH URL instead (e.g. git@ssh.dev.azure.com:v3/user/organization/repository)/

  • I try to use git with HTTPS, but I have authentication issues (not authorized) This might happen if you have enabled the two factor authentication on your GitHub account. You must use an access token to be able to use HTTPS with the two factor authentication activated. Once the token is created, use it instead of your password. An other solution is to use ssh.

  • I have invalid privatekey issues when I try to use Git with ssh on macOs: Since the macOs mojave update, the ssh-keygen default export format has changed. The new format isn’t compatible with all eclipse versions. Use the following command to force ssh-keygen to export the private key as PEM format if you face this issue: ssh-keygen -m PEM -t rsa -b 4096 -C "your_email@example.com".