CI/CD API (Old)
Version 1
This document describes the guidelines to use Version 1 of the CI/CD API of MTA in a pipeline.
Version 1 of the CI/CD API is deprecated and will be discontinued in the next release.
Please use Version 2.
Enable CI/CD
Where regular test runs are executed on the Test Configuration level, CI/CD enabled test runs are executed on the Application level. When testing an Application, all Test Configurations that use that Application, and are CI/CD enabled are executed. Keep in mind, that also other Test Applications could be affected, if one of those Test Configurations use more than one.
If you want to include a Test configuration in testing, you need to enable it by editing it from the Test design page.
- Edit the Test Configuration that you want to execute and set "CI/CD enabled" to TRUE.
- Now open the Test Settings for the Test Configuration and set a Test Setting as My Preference.
Check App status
The CI/CD API can be used in a pipeline that performs deployments of a Mendix Application. But the CI/CD API does not check if the deployment is done.
Before executing a CI/CD testrun, check that the deployment is completed and the status of the Application Instance is "Running".
Execute a testrun from CI/CD
The base URL for the CI/CD API is:
{your mta node}/rest/cicdservice/v1/CiCd/
The CI/CD API knows two REST requests.
- POST testruns
This request executes a new CI/CD testrun - GET testrunsresult
This request returns the result for a previously executed CI/CD testrun
The contents of these requests are described next.
POST testruns
Executes a new CI/CD testrun asynchronously and immediately returns an ExecutionId that can be used to poll for results.
To use this request you need a Project ID for your Mendix App. You can find this by navigating to Applications and clicking on the icon for the respective app.
As of MTA version 2.0, MTA will no longer detect and download a matching revision from Teamserver. Therefore it is advisable to always download the revision in the MTA frontend, before the CI/CD run starts.
URL
/rest/cicdservice/v1/CiCd/testruns
Example: https://mta-menditect-9fo2p.mendixcloud.com/rest/cicdservice/v1/CiCd/testruns
Authorization
| Authorization | Basic |
|---|---|
| Username: | [the CiCd username in MTA] |
| Password: | [the CiCd password in MTA] |
Input body
| Parameter | |
|---|---|
| ProjectId | [the Mendix project ID for the Mendix App you want to execute] |
Example:
{
"ProjectId":"48224593-2187-448d-abe9-9202e1b3a870"
}
As of MTA version 2.0, you only have to provide the Project ID. MTA will determine which Application Instance to execute on, by the Test Setting that is set as Preferred by the provided CI/CD user.
Output (if http response = 200/OK)
| Parameter | |
|---|---|
| ExecutionId | [an ID that is generated by MTA to uniquely identify the test run] |
Example: {"ExecutionId":"ddf0954e-b5df-40cd-879a-eeaa74a19013"}
GET testrunsresult
As of MTA version 2.0, this request will also show detailed information and not just whether the run has passed or failed.
After a CiCd execute, use this request to poll MTA to check if the testrun is finished.
This request returns the result for a previously executed CI/CD testrun, in a JSON format.
URL
/rest/cicdservice/v1/CiCd/testrunsresult
Example: https://mta-menditect-9fo2p.mendixcloud.com/rest/cicdservice/v1/CiCd/testrunsresult
Authorization
| Authorization | Basic |
|---|---|
| Username: | [the CiCd username in MTA] |
| Password: | [the CiCd password in MTA] |
Input parameters
| Parameter | |
|---|---|
| ExecutionId | [the Execution ID for a previously created CiCd testrun] |
Output (if http response = 200/OK)
| Parameter | |
|---|---|
| Result | {} if the test is still running, otherwise a JSON containing results] |
Example:
{
"ExecutionId": "53138dae-3f52-462a-8c29-03868fedca9a",
"Result": "Pass",
"TestRunResults": [{
"TestConfigurationName": "Test",
"TestRunResult": "Pass",
"TestRunUrl": "http://mta-menditect-9fo2p.mendixcloud.com/link/testrun/3",
"TestSuiteRunResults": [{
"TestSuiteSequence": 1,
"TestSuiteName": "Test",
"TestSuiteRunResult": "Pass",
"TestsuiteRunUrl": "http://mta-menditect-9fo2p.mendixcloud.com/link/testsuiterun/3",
"TestCaseRunResults": [{
"TestCaseSequence": 1,
"TestCaseName": "Test",
"TestCaseRunResult": "Pass",
"TestCaseRunResultMessage": "",
"TestCaseRunUrl": "http://mta-menditect-9fo2p.mendixcloud.com/link/testcaserun/3"
}
]
}
]
}
]
}
Powershell script
It is possible to invoke the CI/CD REST service via a Powershell script in Windows if you have local Administrative privileges.
That script looks like this:
# --------------- Configuration ------------------
#
# ALTER PARAMETERS BELOW FOR YOUR CI/CD CONFIGURATION
$TestAppProjectId = "yourprojectidhere"
$MtaUrl = "yourmtaurlhere"
$MtaCiCdUser = "yourusernamehere"
$MtaCiCdUserPassword = "yourpasswordhere$"
# --------------- Script ---------------
#
# DO NOT ALTER CODE BELOW
$Body = @{
ProjectId = $TestAppProjectId
}
$Parameters = @{
Method = "POST"
Uri = $MtaUrl + "/rest/cicdservice/v1/CiCd/testruns"
Body = ($Body | ConvertTo-Json)
ContentType = "application/json"
}
$Pass = ConvertTo-SecureString $MtaCiCdUserPassword -AsPlainText -Force
$Cred = New-Object System.Management.Automation.PSCredential ($MtaCiCdUser, $Pass)
Invoke-RestMethod @Parameters -Credential $Cred
To use above script:
- open Notepad or another text exitor
- copy above script with the copy button on the top right, and paste it into the text editor
- replace the 4 parameters with your own settings
- save the file as
cicd.ps1 - open Windows Powershell to the folder that you saved the file to
- execute the file using this command
powershell -ExecutionPolicy Bypass -File cicd.ps1
Cleanup testruns
Currently, every night a scheduled event cleans CI/CD test runs. MTA only keeps CI/CD test runs associated with the last two executions for a single Application.
Troubleshooting
- Problem: I have configured everything but the CI/CD run does not execute or raises an error message.
- Solution: make sure that the Test Application Instance is running and that the provided CI/CD user credentials are correct. Also make sure that the CI/CD user has both roles as desribed (CI/CD user and Test).
- Problem: the CI/CD run executes with an ExecutionID, but also raises an error message.
- Solution: make sure that all the Test Configurations that are CI/CD enabled for the ProjectID that is passed, have a Prefered Test Setting, and also make sure that there is at least one Test Configuration with CI/CD enabled=TRUE.
Feedback?
Missing anything? Let us know!
Last updated 18 september 2022