title | linktitle | url | category | description | tags | |||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
Implement a Simple CI/CD Pipeline with Mendix APIs |
CI/CD Pipeline for Mendix Cloud |
/howto/integration/implement-cicd-pipeline/ |
Integration |
Describes how you can use the available Mendix APIs with any mainline orchestrators to build a simple CI/CD pipeline. |
|
This how-to describes how to use the available Mendix APIs with any mainline orchestrators (Jenkins, Visual Studio Team Services, etc.) to build a simple CI/CD pipeline.
This is not meant to be a step-by-step guide. Its purpose is to indicate which APIs to use and to provide some examples of how to use them. The tool used in the examples is Postman.
Before starting this how-to, make sure you are familiar with the following:
- CI/CD
- Using REST services
- Unit Testing (if used in your application)
- Application Test Suite (if used in your application)
The basic process for building a CI/CD pipeline is described below. The process involves setting up API keys and rights, building the deployment package, and deploying to the next environment. In most cases, it also involves running tests once the package is deployed and the environment is restarted.
For access to Mendix Cloud environments, an authorized user is needed when executing the APIs. With Mendix APIs, this is achieved via API keys. To create a Mendix API key and set the required authentication headers, follow the steps in Authentication.
To be able to use the Mendix APIs to access your environment, the user who is going to access the APIs needs API rights.
To grant API rights, open your app in the Developer Portal, then go to the Permissions tab of the app's Environments page and select the API Rights option for the user for whom you created an API key in the User API Key step, above. For more details on how to configure permissions, see Node Permissions.
To build the deployment package, use the Team Server API and the Build API. In this example, a package will be built for the latest revision, but you can use whatever version you wish.
To get the latest revision, use the Retrieve Branch API call to get the LatestRevisionNumber
from the output.
An example of how to do this call is below. Be aware that <AppId>
is not a GUID, but the actual name of the cloud node. In the example below, the <AppId>
is ukservices
.
{{< figure src="/attachments/howto/integration/implement-cicd-pipeline/02GetLatestRevision.png" class="no-border" >}}
After getting the version you want to build the package for, you need to build the package. To do this, use the Start Building a Deployment Package API call.
This is a POST
call, so you will need to pass the relevant fields in the body (as described in Start Building a Deployment Package).
{{< figure src="/attachments/howto/integration/implement-cicd-pipeline/03StartBuildingPackage.png" class="no-border" >}}
Before proceeding to the next step, you need to wait for the build of the deployment package to be successful. To do this, use the Retrieve Package API call. This scenario needs to use the PackageId
(output from the previous call) and check if the status is Succeeded
(the other possible statuses are Queued, Building, Uploading, and Failed).
{{< figure src="/attachments/howto/integration/implement-cicd-pipeline/04RetrievePackageStatus.png" class="no-border" >}}
After building the deployment package, you can deploy the new package to the next environment (such as Test or Acceptance). To do this, use the Deploy API.
First, check if the environment to which you want to deploy is running. To do this, use the Retrieve Environment API call and check the status.
{{< figure src="/attachments/howto/integration/implement-cicd-pipeline/05GetEnvironment.png" class="no-border" >}}
If the environment is running, you need to stop it before deploying the new deployment package to it. To do this, use the Stop Environment API call.
To deploy/transport a package to the environment, use the Transport a Deployment Package to an Environment API call.
For this action, you need the PackageId
from the Building the Package section.
{{< figure src="/attachments/howto/integration/implement-cicd-pipeline/06TransportDeploymentPackageToEnvironment.png" class="no-border" >}}
After a successful deployment, the next step is starting the environment. Use the Start Environment API call to do this.
{{< figure src="/attachments/howto/integration/implement-cicd-pipeline/07StartEnvironment.png" class="no-border" >}}
Before proceeding to any next steps, confirm that the environment has started. To do that, use the Get Environment Status API call with the JobId
(output of the previous call). The environment is ready when the status is Started.
{{< figure src="/attachments/howto/integration/implement-cicd-pipeline/08StartEnvironmentStatusStarting.png" class="no-border" >}}
After deploying the package to the environment and starting it, you are ready to run tests. This is not a mandatory step in a CI/CD pipeline, but it is usually part of it.
The sections below show you how to execute unit and ATS (UI) tests remotely. There can also be other tests (for example, load tests), but these are not covered in this how-to.
One way of doing unit tests in a Mendix app is by using the Unit Testing module available from the Mendix Marketplace. This module already exposes an API to execute remote calls.
First, start the tests.
{{< figure src="/attachments/howto/integration/implement-cicd-pipeline/10StartUnitTests.png" class="no-border" >}}
When the tests are completed (check the status for when completed is true
), you can see how many tests ran, how long they took to run, how many failed, which ones failed, and what the reasons for failure were.
{{< figure src="/attachments/howto/integration/implement-cicd-pipeline/11UnitTestsStatus.png" class="no-border" >}}
{{% alert color="info" %}} You can also (manually) create a web service that exposes the standard unit structure from the data available in the Unit Testing module. {{% /alert %}}
ATS has its own API for CI/CD. To use this ATS API, follow the steps in the ATS and CI/CD section of How to Use ATS in Combination with CI/CD.
If you need to promote to another environment, repeat the steps in the Deploying to the Next Environment section.
The sections below present examples of how to call a Mendix API with Jenkins (using a Groovy script) and Visual Studio Team Services (VSTS).
To call a REST service with Jenkins (using a Groovy script), install the HTTP Request Plugin. If you also want to bind credentials to variables (see withCredentials
in the code snippet below), install the Credentials Binding Plugin. The Mendix-Username
and Mendix-ApiKey
will be set in a customHeaders
array.
This code snippet example gets the latest revision number so it can be used when building the deployment package:
{{< figure src="/attachments/howto/integration/implement-cicd-pipeline/12Jenkins.png" class="no-border" >}}
To call a REST service with VSTS, use the Invoke REST API task. Use it in an agentless phase, and set up a Generic endpoint first. The Mendix-Username
and Mendix-ApiKey
go in the Headers section. You can set Success criteria (under the Advanced section) to define what makes the task successful.
The example below checks the status of the acceptance environment. The task will succeed if the environment is running.
{{< figure src="/attachments/howto/integration/implement-cicd-pipeline/13RestExampleVSTS_cut.png" class="no-border" >}}