Skip to content

Customizing the Jenkinsfile

Overview of the Jenkinsfile Template

The provided Jenkinsfile template accomplishes the following tasks:

  1. Builds the AS project
  2. Runs the unit tests
  3. Creates an ARsim structure and PIP
  4. Uploads the ARsim structure and PIP to GitHub, and sends them to an MS Teams channel via a chat message
  5. Sends an email with the results of the build

This template is a starting point for your pipeline definition. There are a few things in this file that must be adjusted for it to run properly for your system.

The following information identifies the purpose of each section in the Jenkinsfile and any changes you must make.

There are 6 main sections in the Jenkinsfile pipeline:

  • Variable Definitions – Defines global variables
  • Agent – Defines where the pipeline will run within the Jenkins environment
  • Environment – Defines global environment variables
  • Options – Configures options
  • Stages – Defines the steps in the pipeline. If a stage fails, subsequent stages don’t run
  • Post – Always runs at the end of the pipeline, even if a stage fails

Difference between Variables and Environment Variables

Variables:

  • Defined outside the pipeline, at the top of the file
  • All variables are global

Environment Variables:

  • Defined within an environment{} section, either at the top level of the pipeline (for pipeline global environment variable declarations) or within a stage of the pipeline (for stage local declarations)
  • Global environment variables can also be defined in the configuration of Jenkins. In this case, the variables are accessible to all pipelines
  • There are also some built-in environment variables that can be used throughout any Jenkinsfile (analogous to System Variables in mapp View). A full list of predefined and readily available environment variables in Jenkins is available here.
  • The built-in workspace environment variable (${WORKSPACE}) is not available until the pipeline starts running. Therefore, if the variable you are creating needs to reference the workspace, you must declare it as an environment variable. In our template file, this is why PROJECT_DIR and RELEASE_VERSION are declared as environment variables.

Customization

Variables

Starting at the top of the Jenkinsfile, we will begin by adjusting the global variables. The following table describes each variable. Adjust the values accordingly:

Variable Name Description
TEAMS_CHANNEL_URL Teams channel webhook URL where messages about the pipeline status will automatically be sent. For more details on how to define this, refer to the “Options” section.
CONFIG_NAME Name of the configuration in the AS project that you are running through the pipeline
UNIT_TEST_CONFIG_NAME Name of the unit test configuration in the AS project
REPO_NAME Name of the GitHub repository. Only required if you plan to upload files to GitHub.
REPO_ORGANIZATION Name of the GitHub organization. Only required if you plan to upload files to GitHub.
EMAIL_LIST List of email addresses that you want to send the results to, each separated by a semicolon

Agent

Edit the “agent” line:

  • If you are utilizing the B&R Jenkins server to start, then identify the docker container your pipeline will run in. This simply depends on the AS version of your project
    • Example: AS_412
  • If you have built your own Jenkins server, then specify the agent accordingly.

Environment

The following table describes each environment variable. Adjust the values accordingly:

Variable Name Description
PROJECT_DIR Specify the path within the repository to the AS project (the folder containing the .apj file).
Use \\ for folder separation.
Example: PROJECT_DIR = "$WORKSPACE\\TestProject“
If the project is stored in the root directory, then leave it defined as PROJECT_DIR = "$WORKSPACE"
RELEASE_VERSION Holds the version number of the code in the repo. No changes required.

Options

The “options” section sets up a webhook to an MS Teams channel so that you can automatically send information to that channel. This includes: * Updates on when the pipeline has started / stopped * Whether the pipeline succeeded * The output files of the pipeline (by default in our template, the output files are the zipped up ARsim structure and PIP)

To establish this connection, you need to obtain your Teams channel webhook URL (see next section) and paste it in the value for the TEAMS_CHANNEL_URL variable

Obtaining the Webhook URL

To obtain the webhook URL for a Microsoft Teams Connection, follow these steps:

  • Navigate to the channel in the Team that you want to establish the connection to

  • Click the “…” button, then click "Connectors"

  • Click “Configure” for “Incoming Webhook”

  • Give your webhook a name and click “Create”

  • Afterwards, the URL you need will be populated in the field at the bottom. Copy this link and paste it at the top of the Jenkinsfile as the value of the TEAMS_CHANNEL_URL variable

Stages

The next section in the pipeline is the stages. This is where you define the actions that the build server will perform. This is the “meat and potatoes” of the pipeline.

There are 4 stages set up in the template Jenkinsfile, which we will now go through one by one:

  1. Update Tags
  2. Build AS Project
  3. Unit Tests
  4. Deploy

Stage: Update Tags

  • This stage force-pulls the tags in the repository
  • Note that therefore, at least one tag must exist in the repo
  • This information will be used later to create a version number
  • No changes necessary

Stage: Build AS Project

  • This stage builds the AS project
  • A value of -1 for “max_warnings” means you can have infinite warnings. If you optionally specify a positive value here, the stage will fail if the number of build warnings exceeds this value.

Stage: Unit Tests

  • This stage runs the automated unit tests

  • If the pipeline gets stuck on a unit test for longer than 15 minutes, the tests will fail. Optionally adjust this timeout value as desired.

Stage: Deploy

  • The template separates the deploy stage between release branches and feature/develop branches

  • Therefore, you can trigger different actions depending on what branch you pushed to

  • By default, both stages create the ARsim structure and Project Installation Package

  • If you want to perform another action in either stage, add it accordingly

Post

The code within Post will always run, even if a stage in the pipeline fails.

Within Post, there are 3 subsections:

  1. Always – runs in every single post processing
  2. Success – runs if all unit tests pass
  3. Unstable – runs if any of the unit tests fail. This is classified as “unstable” rather than a failure because the pipeline itself completed, but the tests did not pass.

Post: Always

The “Always” post script converts the B&R Unit test results into a data format that Jenkins can understand what passed/failed.

It archives the ARsim structure and PIP so that they can be used in subsequent pipelines or uploaded to GitHub/Teams.

It als osends an email with the build status to the EMAIL_LIST recipients.

The PIP that gets automatically generated uses the following installation settings:

  • Consistent installation
  • Allow updates without data loss
  • Keep PV values
  • Ignore version
  • Always install
Example of a Successful Build Email Notification

All Tests Passed

Example of an Unstable Build Email Notification

Some Tests Failed

Post: Success, Unstable

Both the “Success” and “Unstable” post scripts do the following:

  • Upload the artifacts to GitHub
  • Send a message to the Teams channel with the status and artifact download links

The only differences between these post scripts are:

  • The color scheme (green for success, yellow for unstable)
  • The text that gets used for the Teams message (“Build Success” vs “Build Unstable”).
Example of MS Teams Messages

Success:

Unstable:

Post: Success, Unstable

Required steps:

  • Comment/uncomment the upload lines depending on whether you want to upload the artifacts to GitHub
  • If you do choose to upload, make sure you have edited the REPO_NAME and REPO_ORGANIZATION variables at the top of the Jenkinsfile accordingly

Verifying your Jenkinsfile

One common complaint when working with a Jenkinsfile is how to verify that the Jenkinsfile is syntactically correct without running it on Jenkins. This can result in build failures simply due to syntax errors in your Jenkinsfile.

There is a Jenkins Pipeline Linter Connector extension to VS Code that allows you to verify you Jenkinsfile without running it on Jenkins.

  • First install the extension in VS Code

  • Create a token in Jenkins to use for authorization

  • Add new API token

  • Be sure to copy the token

  • Setup extension Automation and Build Server - VS Code Settings.png

  • Add token and Jenkins URL to extension settings, URL = http://<jenkins_url>:8080/pipeline-model-converter/validate

  • Run command to verify your Jenkinsfile using the Command Pallete (Ctrl + Shift + P)

  • Errors in your Jenkinsfile will be shown in the output window of VS Code