Service connections for builds and releases

Azure Pipelines | TFS 2018 | TFS 2017 | TFS 2015

Note

Build and release pipelines are called definitions in TFS 2018 and in older versions. Service connections are called service endpoints in TFS 2018 and in older versions.

You will typically need to connect to external and remote services to execute tasks for a build or deployment. For example, you may need to connect to your Microsoft Azure subscription, to a different build server or file server, to an online continuous integration environment, or to services you install on remote computers.

You can define service connections in Azure Pipelines or Team Foundation Server (TFS) that are available for use in all your tasks. For example, you can create a service connection for your Azure subscription and use this service connection name in an Azure Web Site Deployment task in a release pipeline.

You define and manage service connections from the Admin settings of your project.

  • Azure DevOps: https://dev.azure.com/{organization}/{project}/_admin/_services
  • TFS: https://{tfsserver}/{collection}/{project}/_admin/_services

Service connections are created at project scope. A service connection created in one project is not visible in another project.

Create a service connection

  1. In Azure DevOps, open the Service connections page from the project settings page. In TFS, open the Services page from the "settings" icon in the top menu bar.

  2. Choose + New service connection and select the type of service connection you need.

  3. Fill in the parameters for the service connection. The list of parameters differs for each type of service connection - see the following list. For example, this is the default Azure Resource Manager connection dialog:

    Azure Resource Manager connection dialog

  4. Choose OK to create the connection.

You can also create your own custom service connections.

Secure a service connection

You can control who can define new service connections in a library, and who can use an existing service connection. Roles are defined for service connections, and membership in these roles governs the operations you can perform on those service connections.

Role on a library service connection Purpose
User Members of this role can use the service connection when authoring build or release pipelines.
Administrator In addition to using the service connection, members of this role can manage membership of all other roles for the service connection. The user that created the service connection is automatically added to the Administrator role for that service connection.

Two special groups called Service connection administrators and Service connection creators are added to every project. Members of the Service connection administrators group can manage all service connections. By default, project administrators are added as members of this group. This group is also added as an administrator to every service connection created. Members of the Service connection creators group can create new service connections. By default, project contributors are added as members of this group.

To modify the security for a connection:

  1. In Azure DevOps, open the Service connections page from the project settings page. In TFS, open the Services page from the "settings" icon in the top menu bar.

  2. Choose the Roles link to open the security tab.

    Editing the roles

  3. Add users or groups, turn on and off inheritance, or change the role for existing users and groups as required.

Use a service connection

After the new service connection is created:

  • If you are using it in the UI, select the connection name you assigned in the Azure subscription (or the equivalent connection name) setting of your pipeline.

    If you are using it in the UI

  • If you are using it in YAML, copy the connection name into your code as the azureSubscription (or the equivalent connection name) value.

    If you are using it in YAML

You can also create your own custom service connections.

Common service connection types

Azure Pipelines and TFS support a variety of service connection types by default. Some of these are described below:

After you enter the parameters when creating a service connection, validate the connection. The validation link uses a REST call to the external service with the information you entered, and indicates if the call succeeded.

Azure Classic service connection

Defines and secures a connection to a Microsoft Azure subscription using Azure credentials or an Azure management certificate. How do I create a new service connection?

Parameter Description
[authentication type] Required. Select Credentials or Certificate based.
Connection Name Required. The name you will use to refer to this service connection in task properties. This is not the name of your Azure account or subscription. If you are using YAML, use this name as the azureSubscription or the equivalent subscription name value in the script.
Environment Required. Select Azure Cloud, Azure Stack, or one of the pre-defined Azure Government Clouds where your subscription is defined.
Subscription ID Required. The GUID-like identifier for your Azure subscription (not the subscription name). You can copy this from the Azure portal.
Subscription Name Required. The name of your Microsoft Azure subscription (account).
User name Required for Credentials authentication. User name of a work or school account (for example @fabrikam.com). Microsoft accounts (for example @live or @hotmail) are not supported.
Password Required for Credentials authentication. Password for the user specified above.
Management Certificate Required for Certificate based authentication. Copy the value of the management certificate key from your publish settings XML file or the Azure portal.

If your subscription is defined in an Azure Government Cloud, ensure your application meets the relevant compliance requirements before you configure a service connection.


Azure Resource Manager service connection

Defines and secures a connection to a Microsoft Azure subscription using Service Principal Authentication (SPA). The dialog offers two modes:

  • Automated subscription detection. In this mode, Azure Pipelines and TFS will attempt to query Azure for all of the subscriptions and instances to which you have access using the credentials you are currently logged on with in Azure Pipelines or TFS (including Microsoft accounts and School or Work accounts). If no subscriptions are shown, or subscriptions other than the one you want to use, you must sign out of Azure Pipelines or TFS and sign in again using the appropriate account credentials.

  • Manual subscription pipeline. In this mode, you must specify the service principal you want to use to connect to Azure. The service principal specifies the resources and the access levels that will be available over the connection. Use this approach when you need to connect to an Azure account using different credentials from those you are currently logged on with in Azure Pipelines or TFS. This is also a useful way to maximize security and limit access.

For more information, see Create an Azure service connection

NOTE: If you don't see any Azure subscriptions or instances, or you have problems validating the connection, see Troubleshoot Azure Resource Manager service connections.


Azure Service Bus service connection

Defines and secures a connection to a Microsoft Azure Service Bus queue.

Parameter Description
Connection Name Required. The name you will use to refer to this service connection in task properties. This is not the name of your Azure account or subscription. If you are using YAML, use this name as the azureSubscription or the equivalent subscription name value in the script.
Service Bus ConnectionString The URL of your Azure Service Bus instance. More information.
Service Bus Queue Name The name of an existing Azure Service Bus queue.

How do I create a new service connection?


Bitbucket service connection

Defines a connection to a Bitbucket server.

Parameter Description
Connection Name Required. The name you will use to refer to this service connection in task properties. This is not the name of your Azure account or subscription. If you are using YAML, use this name as the azureSubscription or the equivalent subscription name value in the script.
User name Required. The username to connect to the service.
Password Required. The password for the specified username.

How do I create a new service connection?


Chef service connection

Defines and secures a connection to a Chef automation server.

Parameter Description
Connection Name Required. The name you will use to refer to this service connection in task properties. This is not the name of your Azure account or subscription. If you are using YAML, use this name as the azureSubscription or the equivalent subscription name value in the script.
Server URL Required. The URL of the Chef automation server.
Node Name (Username) Required. The name of the node to connect to. Typically this is your username.
Client Key Required. The key specified in the Chef .pem file.

How do I create a new service connection?


Docker Host service connection

Defines and secures a connection to a Docker host.

Parameter Description
Connection Name Required. The name you will use to refer to this service connection in task properties. This is not the name of your Azure account or subscription. If you are using YAML, use this name as the azureSubscription or the equivalent subscription name value in the script.
Server URL Required. The URL of the Docker host.
CA Certificate Required. A trusted certificate authority certificate to use to authenticate with the host.
Certificate Required. A client certificate to use to authenticate with the host.
Key Required. The key specified in the Docker key.pem file.

Ensure you protect your connection to the Docker host. Learn more.

How do I create a new service connection?


Docker Registry service connection

Defines and secures a connection to a Docker registry.

Parameter Description
Connection Name Required. The name you will use to refer to this service connection in task properties. This is not the name of your Azure account or subscription. If you are using YAML, use this name as the azureSubscription or the equivalent subscription name value in the script.
Docker Registry Required. The URL of the Docker registry. A default value is provided.
Docker ID Required. The identifier of the Docker account user.
Password Required. The password for the account user identified above.
Email Optional. An email address to receive notifications.

How do I create a new service connection?


External Git service connection

Defines and secures a connection to a Git repository server. Note that there is a specific service connection for GitHub and GitHub Enterprise connections.

Parameter Description
Connection Name Required. The name you will use to refer to this service connection in task properties. This is not the name of your Azure account or subscription. If you are using YAML, use this name as the azureSubscription or the equivalent subscription name value in the script.
Server URL Required. The URL of the Git repository server.
User name Required. The username to connect to the Git repository server.
Password/Token Key Required. The password or access token for the specified username.

Also see Artifact sources.

How do I create a new service connection?


Generic service connection

Defines and secures a connection to any other type of service or application.

Parameter Description
Connection Name Required. The name you will use to refer to this service connection in task properties. This is not the name of your Azure account or subscription. If you are using YAML, use this name as the azureSubscription or the equivalent subscription name value in the script.
Server URL Required. The URL of the service.
User name Required. The username to connect to the service.
Password/Token Key Required. The password or access token for the specified username.

How do I create a new service connection?


GitHub service connection

Defines a connection to a GitHub repository. Note that there is a specific service connection for External Git servers and GitHub Enterprise connections.

Parameter Description
Choose authorization Required. Either Grant authorization or Personal access token. See notes below.
Token Required for Personal access token authorization. See notes below.
Connection Name Required. The name you will use to refer to this service connection in task properties. This is not the name of your Azure account or subscription. If you are using YAML, use this name as the azureSubscription or the equivalent subscription name value in the script.

How do I create a new service connection?

Note

If you select Grant authorization for the Choose authorization option, the dialog shows an Authorize button that opens the GitHub login page. If you select Personal access token you must obtain a suitable token and paste it into the Token textbox. The dialog shows the recommended scopes for the token: repo, user, admin:repo_hook. See this page on GitHub for information about obtaining an access token. Then register your GitHub account in your profile:

  • Open your profile from your organization name at the right of the Azure Pipelines page heading.
  • At the top of the left column, under DETAILS, choose Security.
  • In the Security tab, in the right column, choose Personal access tokens.
  • Choose the Add link and enter the information required to create the token.

Also see Artifact sources.


GitHub Enterprise service connection

Defines a connection to a GitHub repository. Note that there is a specific service connection for External Git servers and standard GitHub service connections.

Parameter Description
Choose authorization Required. Either Personal access token or Username and Password. See notes below.
Connection Name Required. The name you will use to refer to this service connection in task properties. This is not the name of your Azure account or subscription. If you are using YAML, use this name as the azureSubscription or the equivalent subscription name value in the script.
Server URL Required. The URL of the service.
Accept untrusted SSL certificates Set this option to allow clients to accept a self-signed certificate instead of installing the certificate in the TFS service role or the computers hosting the agent.
Token Required for Personal access token authorization. See notes below.
User name Required for Username and Password authentication. The username to connect to the service.
Password Required for Username and Password authentication. The password for the specified username.

How do I create a new service connection?

Note

If you select Personal access token you must obtain a suitable token and paste it into the Token textbox. The dialog shows the recommended scopes for the token: repo, user, admin:repo_hook. See this page on GitHub for information about obtaining an access token. Then register your GitHub account in your profile:

  • Open your profile from your account name at the right of the Azure Pipelines page heading.
  • At the top of the left column, under DETAILS, choose Security.
  • In the Security tab, in the right column, choose Personal access tokens.
  • Choose the Add link and enter the information required to create the token.

Jenkins service connection

Defines a connection to the Jenkins service.

Parameter Description
Connection Name Required. The name you will use to refer to this service connection in task properties. This is not the name of your Azure account or subscription. If you are using YAML, use this name as the azureSubscription or the equivalent subscription name value in the script.
Server URL Required. The URL of the service.
Accept untrusted SSL certificates Set this option to allow clients to accept a self-signed certificate instead of installing the certificate in the TFS service role or the computers hosting the agent.
User name Required. The username to connect to the service.
Password Required. The password for the specified username.

How do I create a new service connection?

Also see Azure Pipelines Integration with Jenkins and Artifact sources.


Kubernetes service connection

Defines and secures a connection to a Kubernetes automation account.

Parameter Description
Connection Name Required. The name you will use to refer to this service connection in task properties. This is not the name of your Azure account or subscription. If you are using YAML, use this name as the azureSubscription or the equivalent subscription name value in the script.
Server URL Required. The URL of the Kubernetes automation service.
Kubeconfig The contents of the kubectl configuration file.

How do I create a new service connection?


npm service connection

Defines and secures a connection to an npm server.

Parameter Description
Connection Name Required. The name you will use to refer to this service connection in task properties. This is not the name of your Azure account or subscription. If you are using YAML, use this name as the azureSubscription or the equivalent subscription name value in the script.
Registry URL Required. The URL of the npm server.
Username Required when connection type is Basic authentication. The username for authentication.
Password Required when connection type is Basic authentication. The password for the username.
Personal Access Token Required when connection type is External Azure Pipelines. The token to use to authenticate with the service. Learn more.

How do I create a new service connection?


NuGet service connection

Defines and secures a connection to a NuGet server.

Parameter Description
Connection Name Required. The name you will use to refer to this service connection in task properties. This is not the name of your Azure account or subscription. If you are using YAML, use this name as the azureSubscription or the equivalent subscription name value in the script.
Feed URL Required. The URL of the NuGet server.
ApiKey Required when connection type is ApiKey. The authentication key.
Personal Access Token Required when connection type is External Azure Pipelines. The token to use to authenticate with the service. Learn more.
Username Required when connection type is Basic authentication. The username for authentication.
Password Required when connection type is Basic authentication. The password for the username.

How do I create a new service connection?


Service Fabric service connection

Defines and secures a connection to a Service Fabric cluster.

Parameter Description
Connection Name Required. The name you will use to refer to this service connection in task properties. This is not the name of your Azure account or subscription. If you are using YAML, use this name as the azureSubscription or the equivalent subscription name value in the script.
Cluster Endpoint Required. The TCP endpoint of the cluster.
Server Certificate Thumbprint Required when connection type is Certificate based or Azure Active Directory.
Client Certificate Required when connection type is Certificate based.
Password Required when connection type is Certificate based. The certificate password.
Username Required when connection type is Azure Active Directory. The username for authentication.
Password Required when connection type is Azure Active Directory. The password for the username.
Use Windows security Required when connection type is Others.
Cluster SPN Required when connection type is Others and usiong Windows security.

How do I create a new service connection?


SSH service connection

Defines and secures a connection to a remote host using Secure Shell (SSH).

Parameter Description
Connection Name Required. The name you will use to refer to this service connection in task properties. This is not the name of your Azure account or subscription. If you are using YAML, use this name as the azureSubscription or the equivalent subscription name value in the script.
Host name Required. The name of the remote host machine or the IP address.
Port number Required. The port number of the remote host machine to which you want to connect. The default is port 22.
User name Required. The username to use when connecting to the remote host machine.
Password or passphrase The password or passphrase for the specified username if using a keypair as credentials.
Private key The entire contents of the private key file if using this type of authentication.

How do I create a new service connection?

Also see SSH task and Copy Files Over SSH.


Subversion service connection

Defines and secures a connection to the Subversion repository.

Parameter Description
Connection Name Required. The name you will use to refer to this service connection in task properties. This is not the name of your Azure account or subscription. If you are using YAML, use this name as the azureSubscription or the equivalent subscription name value in the script.
Server repository URL Required. The URL of the repository.
Accept untrusted SSL certificates Set this option to allow the client to accept self-signed certificates installed on the agent computer(s).
Realm name Optional. If you use multiple credentials in a build or release pipeline, use this parameter to specify the realm containing the credentials specified for this service connection.
User name Required. The username to connect to the service.
Password Required. The password for the specified username.

How do I create a new service connection?


Team Foundation Server / Azure Pipelines service connection

Defines and secures a connection to another TFS or Azure DevOps organization.

Parameter Description
(authentication) Select Basic or Token Based authentication.
Connection Name Required. The name you will use to refer to this service connection in task properties. This is not the name of your Azure account or subscription. If you are using YAML, use this name as the azureSubscription or the equivalent subscription name value in the script.
Connection URL Required. The URL of the TFS or Azure Pipelines instance.
User name Required for Basic authentication. The username to connect to the service.
Password Required for Basic authentication. The password for the specified username.
Personal Access Token Required for Token Based authentication (TFS 2017 and newer and Azure Pipelines only). The token to use to authenticate with the service. Learn more.

How do I create a new service connection?

Use the Verify connection link to validate your connection information.

See also Authenticate access with personal access tokens for Azure DevOps and TFS.


Visual Studio App Center service connection

Defines and secures a connection to Visual Studio App Center.

Parameter Description
Connection Name Required. The name you will use to refer to this service connection in task properties. This is not the name of your Azure account or subscription. If you are using YAML, use this name as the azureSubscription or the equivalent subscription name value in the script.
API Token Required. The token to use to authenticate with the service. Learn more.

How do I create a new service connection?


Extensions for other service connections

Other service connection types and tasks can be installed in Azure Pipelines and Team Foundation Server as extensions. Some examples of service connections currently available through extensions are:

  • TFS artifacts for Release Management. Deploy on-premises TFS builds with Azure Pipelines Release Management through a TFS service connection connection and the Team Build (external) artifact, even when the TFS machine is not reachable directly from Azure Pipelines. For more information, see External TFS and this blog post.

  • TeamCity artifacts for Release Management. This extension provides integration with TeamCity through a TeamCity service connection, enabling artifacts produced in TeamCity to be deployed by using Release Management. See TeamCity for more details.

  • SCVMM Integration. Connect to a System Center Virtual Machine Manager (SCVMM) server to easily provision virtual machines and perform actions on them such as managing checkpoints, starting and stopping VMs, and running PowerShell scripts.

  • VMware Resource Deployment. Connect to a VMware vCenter Server from Visual Studio Team Services or Team Foundation Server to provision, start, stop, or snapshot VMware virtual machines.

You can also create your own custom service connections.

Help and support