Service endpoints for Build and Release

VSTS | TFS 2018 | TFS 2017 | TFS 2015

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.

Watch this video on Channel 9 to learn about service endpoints.

You can define endpoints in Visual Studio Team Services (VSTS) or Team Foundation Server (TFS) that are available for use in all your tasks. For example, you can create an endpoint for your Azure subscription and use this endpoint name in an Azure Web Site Deployment task in a release definition.

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

  • VSTS: https://{account}.visualstudio.com/{teamproject}/_admin/_services
  • TFS: https://{tfsserver}/{collection}/{teamproject}/_admin/_services

Service endpoints are created at project scope. An endpoint created in one project is not visible in another team project.

Common endpoint types

VSTS and TFS support a variety of endpoint types by default. Some of these are described below:

After you enter the parameters when creating a service endpoint, 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 endpoint

Defines and secures a connection to a Microsoft Azure subscription using Azure credentials or an Azure management certificate.

Parameter Description
[authentication type] Required. Select Credentials or Certificate based.
Connection Name Required. The name you will use to refer to this endpoint in task properties. This is not the name of your Azure account or subscription.
Environment Required. Select Azure Cloud 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 endpoint.

Azure Resource Manager service endpoint

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

Automated subscription detection.

You cannot use this version of the dialog to connect to an Azure Government Cloud.

Parameter Description
Connection Name Required. The name you will use to refer to this endpoint in task properties. This is not the name of your Azure account or subscription.
Subscription Select an existing Azure subscription. More information.

Manual subscription definition

You must use this version of the dialog when connecting to an Azure Government Cloud.

Parameter Description
Connection Name Required. The name you will use to refer to this endpoint in task properties. This is not the name of your Azure account or subscription.
Environment Required. Select Azure Cloud or one of the pre-defined Azure Government Clouds where your subscription is defined.
Subscription ID Required only if you want to use an existing service principal. The GUID-like identifier for your Azure subscription (not the subscription name). More information.
Subscription Name Required only if you want to use an existing service principal. The name of your Microsoft Azure subscription (account). More information.
Service Principal ID Required only if you want to use an existing service principal. The Azure Active Directory client ID of the account. More information.
Service Principal Key Required only if you want to use an existing service principal. The Azure Active Directory client key of the account. More information.
Tenant ID Required only if you want to use an existing service principal. The ID of the client tenant in Azure Active Directory. More information.

Restricting access rights

By default, the service endpoint will give users read/write permissions as a Contributor to all the resources within the specified subscription. If you prefer to restrict the access rights of users of the service endpoint, you must use the manual approach to creating the endpoint with a service principal. You can give a service principal permissions at the subscription level, resource group level, or resource level. For details of how to restrict a service principal's access rights by using Role-Based Access Control (RBAC) roles, see Use portal to create an Azure Active Directory application and service principal that can access resources.

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

When you start to create the endpoint, the code interrogates Azure for subscriptions that are valid for the credentials you are currently signed into VSTS or TFS with. This applies to both Microsoft accounts and School or Work accounts. It displays a list of these for you to select the one you want to use.

If no subscriptions are shown, or subscriptions other than the one you want to use, you must sign out of VSTS or TFS and sign in again using the appropriate account credentials. See also Troubleshoot Azure Resource Manager service endpoints.

Selecting an existing subscription automatically creates a new Azure service principal that is assigned the Contributor role and so has access to all resources within the subscription. You can edit this service principal in the Azure portal, Subscriptions | Users | Roles section. For more details, see Azure Active Directory for developers.

If you want to use an existing service principal instead of creating a new one:

  1. Download and run this PowerShell script in an Azure PowerShell window. When prompted, enter your subscription name, password, role (optional), and the type of cloud such as Azure Cloud (the default) or an Azure Government Cloud.
  2. Switch from the simplified version of the dialog to the full version using the link in the dialog.

    Opening the full version of the service endpoint dialog

  3. Enter a user-friendly name to use when referring to this service endpoint connection.

  4. Select the Environment name (such as Azure Cloud or an Azure Government Cloud).
  5. Copy these fields from the output of the PowerShell script into the Azure subscription dialog textboxes:
    • Subscription ID
    • Subscription Name
    • Service Principal ID
    • Service Principal Key
    • Tenant ID

See this blog post for details about using service principal authentication.

Azure Service Bus service endpoint

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 endpoint in task properties. This is not the name of your Azure account or subscription.
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.

Azure Service Fabric service endpoint

Defines and secures a connection to a Microsoft Azure Service Fabric cluster.

Parameter Description
[authentication type] Required. Select No authentication, Azure Active Directory credentials, or Certificate based.
Connection Name Required. The name you will use to refer to this endpoint in task properties.
Cluster endpoint Required. The client endpoint of the remote cluster to connect to. Prefix with tcp://.
Username Required for Azure Active Directory authentication. The username to use when connecting to the remote cluster.
Password Required for Azure Active Directory authentication. The password for the specified username.
Client certificate Required for certificate based authentication. The Base64-encoded contents of the client certificate.
Password The password for the certificate when using certificate based authentication.

You can use the following PowerShell script to obtain a Base64-encoded representation of a certificate:

[System.Convert]::ToBase64String([System.IO.File]::ReadAllBytes("path-to-certificate-file\certificate.pfx"))

Bitbucket service endpoint

Defines a connection to a Bitbucket server.

Parameter Description
Connection Name Required. The name you will use to refer to this endpoint in task properties. This is not the name of your account or subscription with the service.
User name Required. The username to connect to the service.
Password Required. The password for the specified username.

Chef service endpoint

Defines and secures a connection to a Chef automation server.

Parameter Description
Connection Name Required. The name you will use to refer to this endpoint in task properties. This is not the name of your account or subscription with the service.
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.

Docker Host service endpoint

Defines and secures a connection to a Docker host.

Parameter Description
Connection Name Required. The name you will use to refer to this endpoint in task properties. This is not the name of your account or subscription with the service.
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.

Docker Registry service endpoint

Defines and secures a connection to a Docker registry.

Parameter Description
Connection Name Required. The name you will use to refer to this endpoint in task properties. This is not the name of your account or subscription with the service.
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.

External Git service endpoint

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

Parameter Description
Connection Name Required. The name you will use to refer to this endpoint in task properties. This is not the name of your account or subscription with the service.
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.

Generic service endpoint

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 endpoint in task properties. This is not the name of your account or subscription with the service.
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.

GitHub service endpoint

Defines a connection to a GitHub repository. Note that there is a specific endpoint for other Git servers.

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 endpoint in task properties. This is not the name of your GitHub account or subscription.

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 account name at the right of the VSTS 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.

Jenkins service endpoint

Defines a connection to the Jenkins service.

Parameter Description
Connection Name Required. The name you will use to refer to this endpoint in task properties. This is not the name of your account or subscription with the service.
Server URL Required. The URL of the service.
Accept untrusted SSL certificates Set this option to allow Jenkins 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.

Also see VSTS Integration with Jenkins and Artifact sources.

Kubernetes service endpoint

Defines and secures a connection to a Kubernetes automation account.

Parameter Description
Connection Name Required. The name you will use to refer to this endpoint in task properties. This is not the name of your account or subscription with the service.
Server URL Required. The URL of the Kubernetes automation service.
Kubeconfig The contents of the kubectl configuration file.

npm service endpoint

Defines and secures a connection to an npm server.

Parameter Description
Connection Name Required. The name you will use to refer to this endpoint in task properties. This is not the name of your account or subscription with the service.
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 VSTS. The token to use to authenticate with the service. Learn more.

NuGet service endpoint

Defines and secures a connection to a NuGet server.

Parameter Description
Connection Name Required. The name you will use to refer to this endpoint in task properties. This is not the name of your account or subscription with the service.
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 VSTS. 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.

Service Fabric service endpoint

Defines and secures a connection to a Service Fabric cluster.

Parameter Description
Connection Name Required. The name you will use to refer to this endpoint in task properties. This is not the name of your account or subscription with the service.
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.

SSH service endpoint

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 endpoint in task properties.
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.

Also see SSH task and Copy Files Over SSH.

Subversion service endpoint

Defines and secures a connection to the Subversion repository.

Parameter Description
Connection Name Required. The name you will use to refer to this endpoint in task properties. This is not the name of your account or subscription with the service.
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 definition, use this parameter to specify the realm containing the credentials specified for this endpoint.
User name Required. The username to connect to the service.
Password Required. The password for the specified username.

Team Foundation Server / VSTS service endpoint

Defines and secures a connection to another TFS or VSTS account.

Parameter Description
(authentication) Select Basic or Token Based authentication.
Connection Name Required. The name you will use to refer to this endpoint in task properties. This is not the name of your account or subscription with the service.
Connection URL Required. The URL of the TFS or VSTS 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 VSTS only). The token to use to authenticate with the service. Learn more.

Use the Verify connection link to validate your connection information.

See also Authenticate access with personal access tokens for VSTS and TFS.

Visual Studio Mobile Center service endpoint

Defines and secures a connection to Visual Studio Mobile Center.

Parameter Description
Connection Name Required. The name you will use to refer to this endpoint in task properties. This is not the name of your account or subscription with the service.
API Token Required. The token to use to authenticate with the service. Learn more.

Extensions for other endpoints

Other service endpoint types and tasks can be installed in VSTS and Team Foundation Server as extensions. Some examples of service endpoints currently available through extensions are:

  • TFS artifacts for Release Management. Deploy on-premises TFS builds with VSTS Release Management through a TFS service endpoint connection and the Team Build (external) artifact, even when the TFS machine is not reachable directly from VSTS. 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 endpoint, 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.

For information about creating your own custom extensions, see Overview of extensions for VSTS.

Endpoint security

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

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

A special group called Endpoint administrators is added to every team project. Members of this group can create new endpoints. By default, project administrators are added as members of this group. This group is also added as an administrator to every endpoint created.

Help and support