When developing Mendix applications, changes to these applications are stored in a version control system. This system is called Team Server and is part of the Mendix Platform. This means that the application’s files are stored in the Mendix online environment. For more information, see the Version Control Reference Guide.
While using Team Server is the recommended for most Mendix developers, you may prefer to store your application’s files in a system controlled by your own organization. For version control, Mendix uses the Subversion system (also known as SVN) and Git. This how-to describes how to work with Git version control system.
This how-to will not describe how to set up a Git server from scratch; typically, this will be taken care of by the IT department of your organization.
You will not be able to use Mendix Studio for collaborative development if you use an on-premises version control server. Collaborative development between Studio and Studio Pro will only work if you use the Mendix Team Server.
This how-to will teach you how to do the following:
- Configure your Mendix app projects to work with Git (on-premises) version control system
Before starting this how-to, make sure you have completed the following prerequisites:
- Make sure you have the right server provider. We currently only support Git Private Server. For more information, see the Preparing Your Repository section.
- You have a feature flag enabled. For more information, see the Enabling a Feature Flag section.
- You have an unversioned Mendix app project. For more information, see the Creating an App section.
3 Supported Authentication Mechanisms
Currently, we only support HTTP Basic authentication for Git service providers. With most providers this takes the form of using of Personal Access Tokens (PATs).
To use PAT (or another equivalent), you need to specify it in the Password field when Studio Pro requests credentials for the version control server:
For instruction on how to set up Personal Access Tokens, see the Supported Git Service Providers section below.
3 Supported Git Service Providers
3.1 Azure Repos and Azure DevOps Server
We support both Microsoft’s Azure Repos hosted Git service, and Azure DevOps Server (former Team Foundation Server) which is an on-premises solution for hosting your Git repos on private infrastructure.
To get a PAT for your user account, see the Use personal access tokens instructions in the Microsoft documentation.
Code (full) permission for your token.
We support GitHub’s hosting solutions, including the free GitHub.com cloud-hosted service and GitHub Enterprise, both hosted (Enterprise Cloud) and on-premises (Enterprise Server).
To get a PAT for your user account, see the Creating a personal access token instructions in the GitHub documentation.
repo permissions for your token.
We support all tiers of GitLab’s service, including GitLab.com, GitLab Community Edition, and GitLab Enterprise Edition.
To get a PAT for your user account , see the Personal access tokens instructions in the GitLab documentation.
write_repository permission for the token.
We support all tiers of Atlassian’s BitBucket service, including BitBucket.org, BitBucket Server, and BitBucket Data Center on-premises solutions.
On BitBucket.org, the Personal Access Tokens are called App Passwords.
To setup an App Password for your BitBucket.org account, see the App passwords instructions.
BitBucket Server and BitBucket Data Center, on the other hand, still use the term Personal Access Tokens. To set up a personal access token, see Personal access tokens instructions.
In both cases you need
repository write permission.
3.5 AWS CodeCommit
We have a known compatibility issue with AWS CodeCommit in Git Technology Preview for Studio Pro. We are working to resolve the issue in the next release.
4 Setting Up the Environment
This section describes how to configure a Git versioned app in Studio Pro. You need a Git server and an initially unversioned Mendix app project.
4.1 Preparing Your Repository
Studio Pro is able to use the following Git server providers:
- Azure DevOps Server
- Azure Repos
- GitHub Enterprise Edition
- GitLab EE
- GitLab CE
- BitBucket Server
- BitBucket Data Center
You need to create a private repository in the selected provider and create a Personal Access Token (PAT) to provide access to it. The PAT is used as a password.
To interact with this private repository from Studio Pro, you need a link to the repository and a PAT.
For more information on PAT, see the Supported Git Service Providers section above.
4.2 Enabling a Feature Flag
To use Git, you need to start Studio Pro with a specific feature flag. Navigate to the directory where Studio Pro is located, specifically where the studiopro.exe file is. There are two ways to enable the feature flag:
The command-line method – Open the command line at that location (or navigate to it from the command line) and type the following command:
The shortcut method – do the following:
Right-click the file and click Create shortcut. If you are asked to save it on the Desktop, click Yes.
Once the shortcut is created, right-click it and select Properties.
At the end of the Target field, add the feature flag
--enable-git-supportafter a space:
Start Studio Pro by double-clicking the shortcut.
Once Studio Pro is opened, go to Edit > Preferences > Version Control and make sure to activate private version control for Git. The name and email values will be used to identify your commit:
Studio Pro now is set up to support Git.
4.3 Creating an App
Create an unversioned app in Studio Pro:
Once the app is created, you can upload it to your private Git repository. For more information on how to upload it, see the Uploading to the Private Git Server section below.
4.4 Downloading from a Private Repository
Now that you have a Git app on your server, you can download it to another directory or one of your team members can download it on their machine. Follow the steps below:
- Under Version Control > Download from Version Control Server, select the Private server option and enter the URL of your repository, which contains the app you want to download. If you are not sure what URL to use, you can find this info in your Git server.
If you have both Subversion and Git enabled for the private version control in your preferences in Studio Pro, specify which version control system your repository uses. For this case, enable the Git radio button:
Enter the link to the repository in the App repository address and click Connect. Now you will have the option to change the directory where the app is downloaded to:
In the Sign In dialog box, enter your credentials:
Enter username (it can be anything except empty) and use the PAT you saved earlier as the password.
The app is downloaded and ready to be used with version control.
4.5 Opening the Existing Git App Project
There are a few ways to open a Git Mendix app project, as long as you have Studio Pro started up with the git feature flag.
4.5.1 Recent Apps List
In your Recent Apps list, you can click the app name and the app will open.
4.5.2 Recent Projects Menu
Under File > Recent Projects you can select the app and open it.
4.5.3 Open App Form
The Open App form is accessible from two different places: * Open App button on the My Apps tab * Under menu File > Open Project
In a form, there are two ways to open a Git app, by opening it from a previous checkout or by opening it locally on disk:
For the previous checkout method do the following:
- Open from previous checkout.
- Enable the Private server radio button and enter the link to the repository.
- Click Connect.
If you have checked out the app at least once, you can then pick one of the existing locations on disk and the app will open (shown here with two previous checkouts):
For the previous local disk method do the following:
- Select the Locally on disk option.
In a file browser dialog box, browse to the directory containing your app and double-click the .mpr file (or select it and click Open):
4.6 Uploading to the Private Git Server
Once you have an unversioned app project, you can upload it to your private team server.
The repository has to be completely empty (including README.md and. gitignore files), or the upload will fail.
To upload your app project, do the following:
Open the app project in Studio Pro and go to Version Control > Upload to Version Control Server:
In the Upload to Version Control Server dialog box, select Private server.
Select Git as the private server type (if you have both Subversion and Git enabled in the Preferences Form).
Enter the link to the repository you want to upload this app to and click OK:
It might ask you to sign into the server, depending on whether you have previously signed in and choose to stay logged in.
You can see the upload process in the Upload Project to Team Server pop-up window:
The project is uploaded successfully. You can check on your private server and see that the app is now on the selected repository:
4.7 Moving a Subversion App Project to Git
If you already have an existing versioned app project (with Subversion) that you would like to upload to your Git private server instead, you can export it, then re-import it, and uploading it to your server. Follow the steps below:
- Once the app is opened, go to File > Export Project Package.
In the Export Project Package dialog box, browse to the location you would like to save the .mpk (Mendix Package) file, or accept the default location, a new packages folder in the root of the application folder. Take note of this location, as you will need it later. You can also rename the .mpk file (e.g.MyGitApp.mpk) and the app will be named that way once you import it and upload it to the Git server:
The Progress pop-up window appears, and once it is completed, you can close the project in Studio Pro:
Now you can import the project package again, and from there you can choose to upload it to your Git private server. Go to File > Import Project Package:
Once the file browser dialog box is open, navigate to the location you save the .mpk file during the export process.
In the Import Project Package dialog box, select Private server option in the Where should we store your App? section.
In the Private Server Type option, select Git (if you have both Subversion and Git enabled in the Preferences form).
Enter the link to the private repository in the address textbox and click OK. Remember, the repository must be completely empty, or Studio Pro will not be able to upload a project to it:
After the import process is completed, your previous Subversion app will be now versioned using Git.
Note that your previous app still exists, Studio Pro will simply make an unversioned copy and upload it to your private Git server. So, in your Recent Apps list, you will still see both: