BYU Deploy App
Automate and schedule the process to build and deploy BYU Mendix apps
Overview
Build deployment pipelines in the BYU Deploy app to automate the process of building a package for a BYU Mendix application from a branch, running unit tests, and deploying to an environment, as well as creating the Request For Change in ServiceNow (from a Standard Change template), and closing the RFC when the deployment has succeeded. You can run the process at a scheduled time or have it initiate on a "trigger," for example, when you commit to a branch.
1. Set up Mendix API Key and Personal Access Token
This is done once, then the API Key and PAT are used in all your Mendix apps and the BYU Deploy app.
1. Sign in to Mendix, go to your User Profile (icon in the upper right), and go to Developer Settings.
2. Create an API Key or use an existing one. Be sure to save the generated API Key somewhere safe. You can't go back in and see the key. It's only displayed when you first create it.
3. Create a Personal Access Token with the proper scope to use the BYU Deploy app, which uses Mendix APIs to monitor the Git repositories, use webhooks, view and create pipelines, and deploy to the Mendix Cloud. Like the API Key, be sure to save the generated Personal Access Token somewhere safe. You can't go back in and see it. It's only displayed when you first create it.
The image below is a summary of the permissions you need.
Note: The Pipelines feature and its API are in Beta so these permissions may need to be updated in the future. New features may be added by Mendix that require additional scope. You can't add new scope to an existing Personal Access Token. You have to create a new one with the scope that you need, then register the updated one in the BYU Deploy app and each of your Mendix applications.
2. Set API Permissions in Your Mendix App
In the Environments page of your application's Deployment console at cloud.home.mendix.com, under the Permissions tab, make sure you have API Rights.
3. Register API Key and PAT in Your Mendix App
On the Pipelines page of your application's Deployment console at cloud.home.mendix.com, under the Settings tab, set up access to its pipelines.
If there are no pipelines yet, you will have to design one before you can see the Settings page to set up your API Key and PAT. See Step 5 below.
Click on the Setup button and enter your API Key and PAT (see Step 1 above).
4. Register API Key and PAT in the BYU Deploy App
This is done only once in the BYU Deploy app.
On the Home page of the Mendix Deploy app, select the Manage API Info button and enter the API Key and PAT from Step 1 above, and your Mendix username, which is usually an email address, like myuser@byu.edu.
5. Design a Pipeline on Your Mendix App
Design a pipeline on the Pipelines page of your application's Deployment console at cloud.home.mendix.com. After you've built it, you will copy the Pipeline ID into a new pipeline that you will build in the BYU Deploy app (Step 6 below). You will run the pipeline from the BYU Deploy app (Step 7 below).
See the following Mendix documentation about managing and designing pipelines and using the Pipeline API.
6. Create a Pipeline in the BYU Deploy App
In the Applications tab, select an application.
Click the blue plus button to add a new pipeline. Give the pipeline a name and add the pipeline ID from the Mendix Pipeline.
Next, navigate to the Pipelines subtab
Create a new pipeline by clicking the new button or double-click an existing pipeline to edit it.
Name the pipeline. NOTE: Local time and UTC time are used for reference when setting the trigger time below.
Select the type of trigger and branch to deploy:
- Scheduled: a scheduled deployment made through the Deploy App (more common)
- TeamServer Push: An automatic deployment triggered by committing to main (less common)
If it is a scheduled deployment, be sure to set the deployment time using the drop-downs. Be sure to set the trigger time in UTC. See Local and UTC time for reference when converting.
At the time of writing, the job type should always be set to immediate.
This pipeline is capable of creating a package from main, deploying it to acceptance, testing it and deploying to production. If you would like to transport a package from one environment to another in addition to the pipeline created through Mendix, check the transfer needed box and add the destination and source environments. Otherwise, leave Transfer needed unchecked.
If an RFC is necessary for this deployment, add a Template ID. Standard Change Templates can be found in ServiceNow by clicking the All navigation tab and searching for Standard Change Templates. Find the app that you wish to deploy for and copy its Alias into the Template ID field.
Be sure to add a description.
If no RFC is required for the deployment, select No RFC Needed.
Click save.
7. Run a Deployment Pipeline in the BYU Deploy App
Navigate back to the Pipeline/Runs subtab
Deployments can either be triggered immediately using the green play button or scheduled using the blue timer button.
Set the deployment time and hit save.
NOTE: When scheduling a pipeline, the deployment time must be set in both the pipeline/runs and pipelines tab. This means that the trigger time (set by the dropdowns in the previous step) must be manually upd.ated each time a deployment is scheduled. This is used in linking webhook alerts to a specific pipeline defined in Mendix Deploy. If this is not done, Unit testing, RFC creation, and transporting to different environments will not be possible.
8. Check Job Status
Navigate to the Jobs subtab.
Here you will see a list of current and past jobs. If you double-click on a job, you can check details like its status, associated RFC number, and what stage the deployment is in. If the Job is marked as failed, notes in the stages section should be helpful for debugging.
