Start a build and passing variables through Azure DevOps Rest API

Question

I would like to start a Azure Pipelines build through the REST API. There is an API for queuing builds but I couldn't find a way to define variables.

Matthews

Answer 1

The accepted answer does not really answers the question when you need to set a value at queue time. The solution is actually pretty simple you just have to add a parameters field to the json payload. The content should be a json string (not directly an object) containing the parameters Ex :

{
    "parameters":  "{\"ReleaseNumber\":  \"1.0.50\", \"AnotherParameter\":  \"a value\"}",
    "definition":  {
                       "id":  2
                   }
}

EDIT : This feature is now properly documented as an optional stringified dictionary. See https://www.visualstudio.com/fr-fr/docs/integrate/api/build/builds#queue-a-build

Tomkins

Nice! I'm curious how you found this, since the docs (as linked in the question) don't seem to mention it. Is it just an undocumented feature? – Pedrick

The good thing is that the current portal uses the same rest apis as we do, so chrome developer tools or fiddler are very helpful when it comes out to finding how to do things :). You may upvote the answer if it helped you ;). – Tomkins

Note for others: when kicking off builds via API, you can also add a reason field, but note that while the docs specify "buildCompletion" is one of the string options, the call will fail. The real list of available reasons is here -- learn.microsoft.com/en-us/azure/devops/extend/reference/client/… – Latria

Placing a parameters section when queueing a build in api 5.1 for azure devops fails pretty hard. – Jupon

Answer 2

Variables are included in definitions, you can update your build definition to set the variables via build-definition api first and then queue the build.

Following is the variable section get via build-definition api:

  "variables": {
    "system.debug": {
      "value": "false",
      "allowOverride": true
    },
    "BuildConfiguration": {
      "value": "release",
      "allowOverride": true
    },
    "BuildPlatform": {
      "value": "any cpu",
      "allowOverride": true
    }
  },

Holmann

Thanks, setting variables first and then queue might be a possible workaround. But this changes build definition on each run and clutters history. Since it is possible to set variables while queue a build from UI it would be nice if the same feature is available from REST API. – Matthews

Passing in variables at least for me appear to not be working as advertised either. – Jupon

This option might not work well if you want to call this API multiple times in a row, you might not get it saved before calling the queue build. I need to call it 50 times in a row with different parameters each time. So I will use the accepted answer even if its not as pretty. – Uninterested

Answer 3

For anyone looking this, I was able to make it work with 'templateParameters', which allow you to send an Object instead of a String on version 7.1.

• Method: POST
• URL: https://dev.azure.com/{organization}/{project}/_apis/build/builds?api-version=7.1-preview.7
• Body: JSON example:

  {
    "sourceBranch":"Development",
    "definition": {
      "id": 5
    }
    "templateParameters": {
      "PARAMETER1": "value1",
      "parameter2": "valuex"
    }
  }
  

Docs: https://learn.microsoft.com/en-us/rest/api/azure/devops/build/builds/queue?view=azure-devops-rest-7.1

Squash

how can we access the parameter in shell script? – Armlet

This worked for me as well. I was facing an issue with directly achieving this with parameters. But with TemplateParamaters, I was able to pass the parameters to another pipeline by queueing it using Azure devops rest API version 7.0 – Piracy

Answer 4

For anyone having problems with this (I did), there is a difference in APIs used since the accepted answer (which to me didn't work at all). But following Cyprien Autexier's advice, I took a look under the hood (Firefox Dev Tools) and I noticed the portal does not use the Builds API anymore. It uses the Pipelines one (https://learn.microsoft.com/en-us/rest/api/azure/devops/pipelines/runs/run-pipeline?view=azure-devops-rest-6.1). With this, worked flawlessly.

Rifling

Answer 5

Seems it works with 5.1. All you need to do is define the variables you pass in as parameters within the pipeline variables and ensure the checkbox "Settable at queue time" is checked. If you have same variable in any library make sure you remove those references as library variables are seen to override those set via API.

Note I use Azure Devops Server 2019

API: https://learn.microsoft.com/en-us/rest/api/azure/devops/build/builds/queue?view=azure-devops-rest-5.1

Navigating to set variables: Edit the YAML pipeline -->click on the 3 dots near "Run" button --> Variables --> Variables TAB

Hope it helps someone

Rad