Azure DevOps CLI service endpoint

2025-06-04

Azure DevOps Services

A service connection allows Azure DevOps to communicate with an external service, such as Azure, Bitbucket, Kubernetes, Maven, and GitHub. With the az devops service-endpoint command, you can create and manage different types of service connections. You can accomplish the following tasks:

Create a service endpoint by using a configuration file
Update a service endpoint
Manage GitHub service endpoints and connections
Manage Azure Resource Manager service endpoints and connections
List service endpoints defined for a project
Get the details of a service endpoint

For detailed command syntax, see az devops service-endpoint. For syntax on the REST API for service endpoints, see Endpoints.

You can use Azure CLI commands to get details, list, delete, and update a service endpoint. See Service endpoints or service connections.

To use the web portal to create and edit service connections, see Manage service connections.

Tip

The examples in this article use service principals in lieu of basic authentication as a more secure method for authentication. For more information, see Use service principals & managed identities in Azure DevOps.

Create service endpoint using a configuration file

To create a service endpoint by using a configuration file, first define the configuration file. The contents of the configuration file differ depending on the type of connection, such as Azure Classic, Azure Data Explorer, Bitbucket Cloud, or Chef.

Configuration file format

The following syntax shows the JSON format for the configuration file.

{
  "data": {},
  "name": "MyNewServiceEndpoint",
  "type": "AzureRM",
  "url": "https://management.azure.com/",
  "authorization": {
    "parameters": {
      "tenantid": "your-tenant-id"
    },
    "scheme": "ManagedServiceIdentity"
  },
  "isShared": false,
  "isReady": true,
  "serviceEndpointProjectReferences": [
    {
      "projectReference": {
        "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
        "name": "TestProject"
      },
      "name": "MyNewServiceEndpoint"
    }
  ]
}

The following table describes each parameter. The type parameter supports creation of any type of service endpoint.

Parameter	Type	Description
`name`	string	Sets the friendly name of the endpoint.
`type`	string	Sets the type of the endpoint.
`url`	string	Sets the url of the endpoint.
`authorization`	EndpointAuthorization	Sets the authorization data for talking to the endpoint.
`isShared`	boolean	Indicates whether the service endpoint is shared with other projects.
`isReady`	boolean	EndPoint state indicator.
`serviceEndpointProjectReferences`	Project Reference	Sets project reference of the service endpoint.

For a list of supported types and their required input parameters, review the following REST API entry:

https://dev.azure.com/{organization}/_apis/serviceendpoint/types?api-version=6.0-preview.1

For a description of service connection types and parameters, see Common service connection types.

Run the `create` command

You create a service endpoint with the az devops service-endpoint create command.

az devops service-endpoint create --service-endpoint-configuration 
                                  [--encoding {ascii, utf-16be, utf-16le, utf-8}]
                                  [--organization]
                                  [--project]

Parameters

service-endpoint-configuration: Required. Name of the json configuration file with service endpoint configuration.
encoding: Optional. Encoding of the input file. Default is utf-8. Accepted values: ascii, utf-16be, utf-16le, utf-8.
organization: Azure DevOps organization URL. You can configure the default organization using az devops configure --defaults organization=ORG_URL. Required if not configured as default.
project: Name or ID of the project. You can configure the default project using az devops configure --defaults project=NAME_OR_ID. Required if not configured as default.

Example

The following command creates a service connection referencing the ServiceConnectionGeneric.json file.

az devops service-endpoint create --service-endpoint-configuration ./ServiceConnectionGeneric.json

After creation, the command assigns an Id to the service endpoint. This example returns the following result.

{
  "administratorsGroup": null,
  "authorization": {
    "parameters": {
      "serviceprincipalid": "your-service-principal-id",
      "serviceprincipalkey": "your-service-principal-key",
      "tenantid": "your-tenant-id"
    },
    "scheme": "ServicePrincipal"
  },
  "createdBy": {
    "descriptor": "aad.OGYxZTFlODEtMGJiNC03N2ZkLThkYzUtYjE3MTNiNTQ2MjQ4",
    "directoryAlias": null,
    "displayName": "Jamal Hartnett",
    "id": "60c83423-4eb6-4c5e-8395-1e71cb4aef4c",
    "imageUrl": "https://dev.azure.com/fabrikam/_apis/GraphProfile/MemberAvatars/aad.OGYxZTFlODEtMGJiNC03N2ZkLThkYzUtYjE3MTNiNTQ2MjQ4",
    "inactive": null,
    "isAadIdentity": null,
    "isContainer": null,
    "isDeletedInOrigin": null,
    "profileUrl": null,
    "uniqueName": "fabrikamfiber4@hotmail.com",
    "url": "https://spsprodwcus0.vssps.visualstudio.com/A0214b8cc-a36c-4b93-abbf-6348473c2f0a/_apis/Identities/60c83423-4eb6-4c5e-8395-1e71cb4aef4c"
  },
  "data": {},
  "description": null,
  "groupScopeId": null,
  "id": "3b6890ef-54b3-47ec-a907-a5d2f96237da",
  "isReady": true,
  "isShared": false,
  "name": "MyNewServiceEndpoint",
  "operationStatus": null,
  "owner": "library",
  "readersGroup": null,
  "serviceEndpointProjectReferences": [
    {
      "name": "MyNewServiceEndpoint",
      "projectReference": {
        "id": "677da0fb-b067-4f77-b89b-f32c12bb8617",
        "name": null
      }
    }
  ],
  "type": "Generic",
  "url": "https://myserver"
}

Create a GitHub service endpoint

To create a GitHub service endpoint, use the az devops service-endpoint github create command:

az devops service-endpoint github create --github-url
                                         --name 
                                         [--organization]
                                         [--project]

In interactive mode, the az devops service-endpoint github create command prompts you for GitHub PAT token. For automation purposes, set the GitHub PAT token using the AZURE_DEVOPS_EXT_GITHUB_PAT environment variable. For more information, see Sign in with a personal access token.

Create an Azure Resource Manager service endpoint

To create an Azure Resource Manager service endpoint, use the az devops service-endpoint azurerm create command.

az devops service-endpoint azurerm create --azure-rm-service-principal-id
                                          --azure-rm-subscription-id
                                          --azure-rm-subscription-name
                                          --azure-rm-tenant-id
                                          --name
                                          [--azure-rm-service-principal-certificate-path] 
                                          [--organization]
                                          [--project]

Use a client secret

In interactive mode, the az devops service-endpoint azurerm create command prompts you for a service principal secret. For automation purposes, set the service principal secret using the AZURE_DEVOPS_EXT_AZURE_RM_SERVICE_PRINCIPAL_KEY environment variable.

export AZURE_DEVOPS_EXT_AZURE_RM_SERVICE_PRINCIPAL_KEY=<your_secret_here>

$env:AZURE_DEVOPS_EXT_AZURE_RM_SERVICE_PRINCIPAL_KEY=<your_secret_here>

Use a client certificate

If the Microsoft Entra application uses certificate for authentication, create a .pem file for the certificate. Pass the path to the .pem file using the --azure-rm-service-principal-certificate-path argument.

You can create a .pem file using OpenSSL:

openssl pkcs12 -in file.pfx -out file.pem -nodes -secret pass:<secret_here>

Share via