Skip to end of metadata
Go to start of metadata

Plugin Information

View Azure IoT Edge on the plugin site for more information.

Azure IoT Edge Plugin makes it easy to setup a CI/CD pipeline for developing an IoT Edge solution on Jenkins, by providing following functionalities:

  • Continuous integration(build and push docker image)
  • Continuous deployment(create Edge deployment on Azure)


  • If you encounter any bugs with this plugin please leave comment in Wiki page or file an issue in Jenkins JIRA under component azure-iot-edge-plugin.

  • You can also contact this Email group for issues Azure IoT Tooling Support.


This is the work flow for Azure IoT Edge solution CI/CD pipeline.


How to Install


Install following tools on Jenkins host.

Install extension

You can install/update this plugin in Jenkins update center (Manage Jenkins -> Manage Plugins, search Azure IoT Edge Plugin).

You can also manually install the plugin if you want to try the latest feature before it's officially released. To manually install the plugin:

  1. Clone the repo and build. (The integration test need about 30 minutes to run, you can skip by following command):
    mvn package -Dmaven.test.skip=true
  2. Open your Jenkins dashboard, go to Manage Jenkins -> Manage Plugins.
  3. Go to Advanced tab, under Upload Plugin section, click Choose File.
  4. Select azure-iot-edge.hpi in target folder of your repo, click Upload.
  5. Restart your Jenkins instance after install is completed.

Before using extension

To use this plugin to build and deploy Azure IoT Edge solution, first you need to have an Azure Service Principal in your Jenkins instance.

  1. Create an Azure Service Principal through Azure CLI or Azure portal. Make sure in order to use Service Principal for CI/CD, you need to create the role at least Contributor. Otherwise it doesn't have enough permission to create deployment on IoT Hub.
  2. Open Jenkins dashboard, go to Credentials, add a new Microsoft Azure Service Principal with the credential information you just created.
  3. If you use common docker registry credential(like docker hub), you may also add a new Username with passwordcredential.
  4. Existing Azure IoT Hub and docker registry are needed in CI/CD.

Create a project

In Jenkins, there are two types of project.

  • Freestyle project: Config through UI
  • Pipeline project: Config through code

Create a Freestyle project

Build and Push task


  1. In Build section, click Add build step, then choose Azure IoT Edge Build and Push.
  2. Set Solution Root Path, in most cases it's where deployment.template.json located.
  3. Set Bypass modules, it is the list of modules to bypass when building, use comma delimited list of modules. Example "ModuleA,ModuleB". You can leave this field empty to build all modules.
  4. Choose docker registry in Docker Credential Configuration.
  • For Azure Container Registry, you need to use the Azure Service Principal created above to authenticate.
  • For other types of registry(docker hub), you need to specify Docker registry URL and then a credential with type Username with password.

Deploy task


  1. In Build section, click Add build step, then choose Azure IoT Edge Deploy.
  2. Set Solution Root Path, in most cases it's where deployment.template.json located.
  3. Choose Azure IoT Hub.
  4. Set deployment configurations. You can click help button after the input box to get detailed explanation of the item.

Create a Pipeline project

You can also use this plugin in pipeline (Jenkinsfile). Here are some samples to use the plugin in pipeline script, there is also an example for pipeline project.

Project config on Jenkins


Customize pipeline: Build and Push task

Use Azure Container Registry
azureIoTEdgePush dockerRegistryType: 'acr', acrName: '<acr_name>', bypassModules: '', azureCredentialsId: '<azure_credential_id>', resourceGroup: '<resource_group_name>', rootPath: '<solution_root_path>'
Use common Container Registry
azureIoTEdgePush dockerRegistryType: 'common', dockerRegistryEndpoint: [credentialsId: '<credential_id>', url: '<url>'], bypassModules: '', resourceGroup: '<resource_group_name>', rootPath: '<solution_root_path>'

Customize pipeline: Deploy task

For single device
azureIoTEdgeDeploy azureCredentialsId: '<azure_credential_id>', deploymentId: '<deployment_id>', deploymentType: 'single', deviceId: '<device_id>', iothubName: '<iothub_name>', priority: '<priority>', resourceGroup: '<resource_group_name>', rootPath: '<solution_root_path>', targetCondition: ''
For multiple devices using target condition
azureIoTEdgeDeploy azureCredentialsId: '<azure_credential_id>', deploymentId: '<deployment_id>', deploymentType: 'multiple', targetCondition: '<target_condition>', iothubName: '<iothub_name>', priority: '<priority>', resourceGroup: '<resource_group_name>', rootPath: '<solution_root_path>', targetCondition: ''

For advanced options, you can use Jenkins Pipeline Syntax tool to generate a sample script.


Does ARM platform supported?

If you would like to build ARM platform image, you'll need to setup an ARM build agent. And for the Prerequisites, they also need to be setup on build agent.


Azure IoT Edge Plugin for Jenkins collects usage data and sends it to Microsoft to help improve our products and services. Read our privacy statement to learn more.
You can turn off usage data collection in Manage Jenkins -> Configure System -> Azure -> Help make Azure Jenkins plugins better by sending anonymous usage statistics to Azure Application Insights.


Version 1.0.0

  • Initial release

A bulk of the documentation for this plugin is in the GitHub

  • No labels

1 Comment

  1. I’m getting a strange issue with the Jenkins Azure IoT Edge Plugin where it fails after the “iotedgedev genconfig” setup. The plugin complains the file is not present, but the file is present and accessible to the user on the slave where it is being executed. This is being built on a Jenkins slave executor, is it possible the Jenkins plugin is hunting for this file on the master when it should be on the slave?

    Here’s the tail end of my output:

    [testedge] $ iotedgedev genconfig
    ======== ENVIRONMENT VARIABLES ========
    .env file not found on disk. Without a file on disk, you must specify all Environment Variables at the system level. (<snip>/.env)
    Expanding 'deployment.template.json' to 'config/deployment.json'
    FATAL: <snip>/config/deployment.json (No such file or directory) <snip>/./config/deployment.json (No such file or directory)
           at Method)
           at hudson.tasks.BuildStepCompatibilityLayer.perform(
           at hudson.tasks.BuildStepMonitor$1.perform(
           at hudson.model.AbstractBuild$AbstractBuildExecution.perform(
           at hudson.model.Build$
           at hudson.model.Build$BuildExecution.doRun(
           at hudson.model.AbstractBuild$
           at hudson.model.Run.execute(
           at hudson.model.ResourceController.execute(
    Finished: FAILURE