Skip to main content
Developer Portal
Mendix

CI/CD Pipeline PLUS

This module will test your code as it pushes it to the next environment.

Documentation

Description

This module is used to move code from one environment to the next. The code is tested before it is moved to the next environment. When the code is being moved to production the module schedules a production deployment at midnight, otherwise it is moved immediately.

Typical Usage Scenario

This module should be used anytime you want to test your code before pushing it. It can also be used to make pushing code dependent on your unit tests passing.

Limitations

This module currently only works for applications with acceptance and production environments. It does not support configurations that include a test environment.

Implementing the Module in Your Project

We'll use several environment constants to provide API credentials and to identify environments. Some of these constants are truly constant, with the "default value" used across every environment. Other constants have environment-specific values. We'll also configure security and a couple other items.

  • Mendix API Config Constants
    Location: Pipeline / Mendix API
    These provide configuration for the Mendix deployment API. The path to these constants is Pipeline / Mendix API. Make the following changes:
    1. Change the "AppId" constant to the name of the cloud node for your app. This is also known as the the subdomain. (For example, byu-mylink.mendixcloud.com has an appId of "byu-mylink")
    2. Change the "username" constant to the email address of the user you want to use for the API
    3. Change the "key" constant to the API key generated for your user
  • Security
    Go into your Project Security, then to User Roles. Edit the Administrator role and give it these module roles:
    • Pipeline.Admin
    • MicroflowScheduler.Configurator
    • UnitTesting.TestRunner

    Give these module roles to any other user role who needs to deploy the pipeline.

  • The Button
    This module comes with a button that calls the main microflow (BTN_Pipeline_Begin), executing the pipeline. We recommend you use this pre-built button when implementing your pipeline. Find, copy, and paste the button from this empty page: USE_ME / Button_Pipeline_Begin. You can always use your own way to call the main microflow. However, this particular button is handy because:
    • It is conditionally visible only in environments "Local" or "Acceptance." It is not visible in Prod because you can't deploy past Prod.
    • Visible only to the Pipeline module role "Admin"
    • It asks for confirmation and then brings up a loading bar
    • When deploying from Acceptance to Prod, it schedules a deployment and then turns into a Cancel button. The Cancel button will cancel that scheduled deployment.
  • Integrate Landing Page
    Go to Pipeline / _Production_Deployment / ACT_ProductionDeployment_Schedule and make the following change:
    1. Go to the box that says "Show 'Admin_Overview'"
    2. Change it to the page that now holds your Pipeline button. This is the page that will be refreshed.
  • Deploy to All Environments
    To proceed, we must deploy what we have in acceptance and production. Then we can change Constants and Scheduled Events, specific to those environments.

  • Change Constant: "Environment_Name"
    Location: (Change only in Mendix Cloud Portal)
    This constant is different in every environment. Its default value is already set as "Local", and we want to change it for Acceptance and Production. That way, we can determine which environment we are in from within microflows.

    To change a constant for a specific environment, the project must first be deployed to all environments, with this module installed (we did this earlier).

    1. Go to Mendix Cloud Portal and under Deploy select Environments.
    2. Click the Details button for one of the environments (We need to configure both). You may receive an error.
      • If you didn't get an error, skip this paragraph. This error means your Mendix account lacks the rights on the team that are required to edit these features. The rights can be granted by your team's Technical Contact or App Contact. Contact information for both team members can be found on the Mendix Developer Portal for your project under Apps/"Your Project"/Settings/General.
    3. Now select Model Options and we'll be editing the Constants.
    4. Make these changes:
      1. In the Production Environment, change the constant Environment_Name to "Production"
      2. In the Acceptance Environment, change the constant Environment_Name to "Acceptance"
  • Scheduled Event: "SE_Scheduler_Q1"
    Important: Only do this in acceptance. Do not enable the scheduled event in production. Still in App Cloud Services, on the same page as "Constants", go to "Scheduled Events". Make the following change:
    1. In the Acceptance Environment, change the scheduled event MicroflowScheduler.SE_Scheduler_Q1 so that it is enabled.

*********************************************

Now you're done implementing! You should be able to test deploying your pipeline now. Refer to "How to Use" for instructions on using the pipeline.

*********************************************

How to Use

  • Pull Request
    1. Before deploying to acceptance, you must have your code reviewed.
      1. If you have made major changes you must have the code reviewed by a supervisor.
        • For example if your changes affect multiple parts of the website, change something fundamental, there is high risk of errors, or they deal with sensitive data.
      2. If your change is minor you should have the code reviewed by a nearby team member.
        • For example if it only touches an isolated part of the website, or it is non-fundamental or cosmetic.
    2. Make any necessary changes.
    3. After this process, you may deploy to acceptance.
  • Local to Acceptance
    1. The pipeline only deploys from the main line. If you are on a branch, merge and commit before deploying.
      • Important: When the pipeline executes from local, it will deploy the most recently committed version. When you are ready, you commit and then immediately click Deploy to Acceptance on your running local environment. If you wait ten minutes before deploying another person could commit their code. Clicking Deploy to Acceptance will deploy both commits.
    2. When you click Deploy to Acceptance the site will display a loading bar, and gray out the rest of the screen. It may take a few minutes.
      • If unit tests fail it will stop everything and tell you to ensure that the unit tests pass.
      • If tests pass it will continue with the pipeline process.
      • Pipeline errors will produce an error message.
      • If it finishes with no errors you will see a success message
  • Acceptance-to-Production
    1. This grabs the package currently on Acceptance, and deploys the package to production.
    2. When you click Deploy to Production it will run unit tests like before. When these are complete, it schedules the rest of the deployment to occur at midnight.
      • When the microflow ends, it shows a message, and there will be nothing else on the screen to see for now.
      • The deployment microflow will occur at midnight.

Architecture

This is an overview of how the microflows work together and how the project file structure is ordered.

  1. Microflow Structure
    1. Preparation
      • The microflow that calls the pipeline is: 1_Pipeline Begin / BTN_Pipeline_Begin.
      • It checks value of the constant "environment" and executes a different microflow, depending on each environment.
    2. Deployment
      • Local-to-Acceptance (2_Acceptance Deployment / ACT_Acceptance Deploy):
        • Gets the most recent revision number of the code
        • Runs unit tests
        • Builds package
        • Deploys
      • Acceptance-to-Production (2_Production Deployment / ACT_Production Deploy):
        • Gets package ID of the package on Acceptance (for deployment)
        • Gets package ID of the package on Production (in case of rollback)
        • Runs unit tests
        • Schedules another microflow, which will deploy at midnight.
        • At midnight, the scheduled microflow deploys the package.
    3. Rollback
      • If deployment fails, it will initiate rollback (2 Rollback / ACT_Environment_Rollback)
      • It always rolls back to the package previously on that environment
    4. Cancelling
      • This microflow will cancel a scheduled deployment: ACT_PipelineSchedule_Cancel
      • It simply deletes the first "Schedule" object with attribute "enabled" as "true". There should always be only one "enabled" schedule object at a time.
  2. File Structure
    There are two main folders:
    1. "USE_ME" (or "Implementation")
      • Holds the button and the microflow it calls.
    2. "Pipeline"
      • Holds all the microflows and resources used by the main microflow.
    3. There is a folder for each function performed, and each "function folder" contains sub-folders for "Microflows", "Pages", "Resources", and so forth.

Set Up

Make sure you are familiar with importing modules from a package and from the Mendix App Store before beginning the set up.

Dependencies

There are a few external modules that must be part of your project because the Pipeline uses them. Below we will show you how to configure these modules.

  • Microflow Scheduler
    Once you have imported it, go into its domain model. Make the following changes:
    1. Add attributes to MicroflowScheduler.Schedule
      • "PackageId_Acceptance" (String (200))
      • "PackageId_Production" (String (200))
      • "Result" (Enumeration)
        • Set the Enumeration as Pipeline / Package Deploy / Enumerations / DeploymentResult
      • "FinishedTime" (Date and Time)
      • "Pipeline" (Boolean, set default to 'false')
    2. Add an association between [Pipeline.Environment] * and 1 [MicroflowScheduler.Schedule]
      • You'll have to start from Pipeline.Environment domain model, to complete this action
  • UnitTesting
    This may already be included in your project. If it isn't, go into the CONFIG folder in the UnitTesting module. Make the following change:
    1. Set the constant RemoteApiEnabled to true.
  • Community Commons Function Library
  • Mx Model Reflection
  • Atlas UI Resources

When all of these modules are set up, go into your Project Settings > Runtime > After Startup. Set the microflow to: [UnitTesting._USE ME / Microflows / Startup]. If you already have a startup microflow, and you now need to call both, then create a microflow that calls both of them and use this as your startup microflow.

Resolve Errors

Some of your newly installed modules may contain deprecated elements. These will show up as errors. None of the pages listed above are directly used in the Pipeline module. Delete these pages or if you want to keep them, copy the "good" elements to your own blank page, and delete the old pages.

Installation

  1. Download the module here. It will save as Pipeline.mpk
    1. Note: If you are using Mendix Studio Pro 8.8.* or 8.9.* downloading private app store modules/widgets was turned off due to security concerns. All the BYU Private App Store content can still be downloaded from the Company Content page in the Mendix App Store and then imported into those versions of Studio Pro. Upgrading to a newer version of Mendix Studio Pro fixes the problem.
  2. After the download finishes, import CI/CD Pipeline Plus into your project.
    1. Right click on your Project Explorer
    2. Select Import Module Package
    3. Select the module you just downloaded and click Open

More Resources

Learn how to install a module in Mendix.

Slack

For additional help, refer to the appropriate slack channels in their respective workspaces:

  1. BYU-OIT workspace
    1. #api-management
    2. #mendix
  2. BYU-Web workspace
    1. #mendix-user-group