This article is outdated, you can access the most current version here: https://doc.onedata.de/apps/apps-docs/odml-documentation/AppBuilder/git-management/Git.html#set-your-app-git-managed

Article Content

1. Set your App Git Managed
2. Logging into GitLab
3. Structure of app repositories
4. Working with branches in the App Builder
5. Making changes to a git-managed app
6. Merging your work into develop
   • Compare two Versions
7. Making changes to an app from a local repository

The Git Introduction and GitLab articles covered the basics of Git and discussed the most important features of the git-management software GitLab. This article will show how you can use the Git-integration of ONE DATA Apps in combination with GitLab.

Set your App Git Managed

ONE DATA Apps features basic versioning out-of-the-box by saving versions of the app's configuration that can be accessed through the app history. With the Git-integration it is possible to leverage the advantages and possibilities of Git during app development. This requires you to enable Git-management for your app. All configurations created starting at that point will then be reflected in a Git repository as a commit and support for branching will be available in the App Builder.

To enable Git-management for an app, you need to be admin of that app. For details about the access roles in Apps please confer to the documentation about access roles. Also, it is necessary that GitLab is set up and your ONE DATA instance is configured to use it. If it is not, the option to set the app git-managed will not be shown.

As admin open the app you want to set git-managed in the App Builder and go to the app settings (1) via the left sidebar. There you can choose to manage your app with Git (2).

When you activate the toggle for the first time, a project with the name of your app will be created at the connected GitLab instance. The master-branch will be initialized with the app configuration that is currently published to the app viewer. The latest valid configuration will be pushed to the develop-branch. Please make sure that your configuration is valid to prevent losing changes when activating Git-management.

Via that toggle, it is also possible to remove the git-management from the app again. In this case, the git-support will not be available anymore and subsequent modifications to the app's configuration will not be reflected in the repository. When you reenable Git-management, the app will be connected to the already existing repository again and the latest published/valid configuration will be pushed to master/develop respectively.

When you set an app git-managed, the users having access to it and their access roles will be reflected in the GitLab project. Please note that only users given access to the app via the User Access option are also added as members to the GitLab project. Users having access to the app via Group Access or Global Access will not be able to access the GitLab project. The members are assigned a GitLab permission level based on their role in the app. The ONE DATA Apps access roles translate to the GitLab permission levels as follows:

In case an OAuth2 authentication provider is configured (see here) the GitLab user accounts for ONE DATA users are identified by their linked ONE DATA ID. Otherwise, users are identified by their e-mail address. If a user who has access to the app does not have a GitLab account, a new account is created with his/her user data. If an OAuth authentication provider for ONE DATA is configured, the newly created user is also linked to his/her ONE DATA account.

Logging into GitLab

If your GitLab server is configured to use OAuth2 authentication with ONE DATA, you can login to GitLab with your ONE DATA credentials. In this case, a respective option is shown on the login page of GitLab.

To login with your ONE DATA credentials choose Onedata (1) in the section Sign in with instead of using the login form above. If your instance does not support the OAuth2 login, a GitLab admin needs to create an account for you with the same e-mail address that you use in ONE DATA. In this case, you need to login with the login form at the top.

Structure of app repositories

The repository of a git-managed app contains the app's configuration split up into multiple JSON-files. The directory structure reflects the structure of the JSON in the RAW-tab of the App Builder.

Arrays like datasources, elements, etc. that have elements with an id are represented as separate JSON-files in the respective folder. The name of these files is always their ID, e.g. elements/welcomeTitle.json. Elements of the app configuration that do not have an ID (e.g. version and screens) are put as JSON-files into the root-directory. Apart from that, there is also a _index.json at the root of the repository. This file is used by ONE DATA Apps internally and should not be modified manually.
If the configuration is not valid JSON, it can't be split up. In this case, the raw JSON will be stored in "invalid.json".

Working with branches in the App Builder

When working with a git-managed app, you can make use of branching support provided by the App Builder. When you open a git-managed app, you will see a dropdown at the top of your file-tree. It is also shown in the history tab accessible via the left sidebar.

In the branch-dropdown you can see the currently checked out branch (1). The editor shows the app configuration in the version of this branch. Furthermore, the configuration history shows only the history of the checked-out branch. To change the branch click on the dots to open the dropdown. 

There you can create a new branch (2) that originates from develop. After you chose a name for the branch, the new branch is checked out by the App Builder and changes to the app configuration will be reflected as commits to that branch. Please note that it is recommended to use the GitFlow naming scheme for your branches, i.e. starting the branch-name with "feature/" followed by the name of the feature. In the branch-dropdown you can also search and select existing branches (3). When you choose a branch from the list, the app configuration and history will be adapted to that branch and you can start working on it. If you want to explore the changes made on a branch, you can click the button (4) next to the branch name to open the GitLab Files page for that branch in a new tab.

Making changes to a git-managed app

When you have checked out your branch via the branch-dropdown, you can start making changes to the app's configuration with the editor of the App Builder as you would do in a non-git-managed app. Please note that users with Builder permission can only modify feature-branches. Only app admins can modify develop directly.

Whenever you make a change to the app configuration in the App Builder and save it, a commit on the checked-out branch is created. It will receive the version number (e.g. #123) as commit message. Please note that while it is possible to change the name of the configuration version in the App Builder, this will currently not reword the respective commit.

You can also directly jump to an older commit of your branch by using the configuration history. It only lists the commits that are on the current branch. Please note that the numbers assigned to the versions are chosen uniquely across all branches to prevent identical names once a branch is merged. This means that some numbers of the version can be missing in the history if a commit was made on another branch in the meantime.

When you publish a version of your app to the App Viewer, this will also be reflected in the git repository. The master branch always contains the version of the app that is currently published to the viewer. So when you publish a version through the app settings or the app history, the develop-branch up to that version will be merged into master. Please note that this is done via a force-push overwriting any changes that have been previously on master.

Merging your work into develop

Once you are done with your work on your feature-branch, you can create a merge request to merge it back to develop. Open the GitLab project of your app and select Merge Requests in the left sidebar. There you can create a merge request as described here. Once the merge request is merged by the assignee, the changes are available at the target branch in the App Builder after a few seconds. If a merge commit was necessary to merge the changes, this will also show up as a configuration version with the name of the MR in the app history.

Compare two Versions

With Git you can compare any revisions in the history of your project. This can be useful if you want to check what has changed since a specific version or for example if you want to check what parts of the code are affected by a specific feature. To compare two revisions you can use the Compare page in GitLab that is accessible via the Repository menu in the left sidebar. On this page you can select a source revision that will be used as the basis for the diff. The target is the revision you want to compare the source revision to. For the source and target you can enter any branch, tag, or commit. A commit can be chosen by entering its commit hash in the input field of the respective dropdown (please note that you need to press Enter afterwards).

Once you click Compare a comparison similar to the one in merge requests is shown. At the top you can see the commits that were made to get from the source revision to the target revision. Below the changes between the versions are shown. The red lines exist in the source version, but not in the target version. The green lines are present in the target version, but not in the source version.

Making changes to an app from a local repository

You can also clone the repository of an app to your machine and make changes locally. This can be useful if you for example want to resolve complicated conflicts with your preferred merge tool. You can clone the repository by following the steps described here. Then you can make changes in your local copy of the repository, like resolving the merge conflicts. Afterwards, you create a commit with the following command and push the changes. Alternatively, you can use a tool like SourceTree.

git add --all
git commit -m "Your commit message"
git push origin feature/your-branch