Deploy an agent on macOS

VSTS | TFS 2018 | TFS 2017 | TFS 2015

To build and deploy Xcode apps or Xamarin.iOS projects, you'll need at least one macOS agent. This agent can also build and deploy Java and Android apps.

Before you begin:

  • If your build and release definitions are in VSTS and a Microsoft-hosted agent meets your needs, you can skip setting up a private macOS agent.
  • Otherwise, you've come to the right place to set up an agent on macOS. Continue to the next section.

Learn about agents

If you already know what an agent is and how it works, feel free to jump right in to the following sections. But if you'd like some more background about what they do and how they work, see Build and release agents.

Check prerequisites

Make sure your machine is prepared with our macOS system prerequisites.

Prepare permissions

If you're building from a Subversion repo, you must install the Subversion client on the machine.

Decide which user you'll use

Decide which user account you're going to use to register the agent.

Authenticate with a personal access token (PAT) to VSTS or TFS 2017 or newer

  1. Sign in with the user account you plan to use in either your VSTS account (https://{your-account}.visualstudio.com) or your Team Foundation Server web portal (https://{your-server}:8080/tfs/).

  2. From your home page, open your profile. Go to your security details.

    test

  3. Create a personal access token.

    test

  4. For the scope select Agent Pools (read, manage) and make sure all the other boxes are cleared. If it's a deployment group agent, for the scope select Deployment group (read, manage) and make sure all the other boxes are cleared.

  5. Copy the token. You'll use this token when you configure the agent.

Authenticate as a user of TFS 2017 or newer

You can use either a domain user or a local Windows user on each of your TFS application tiers.

Authenticate as a user of TFS 2015

(Applies only to macOS and Linux.) We recommend that you create a local Windows user on each of your TFS application tiers and dedicate that user for the purpose of deploying build agents.

Confirm the user has permission

Make sure the user account that you're going to use has permission to register the agent.

Is the user you plan to use is a VSTS account owner or a TFS server administrator? If so, then skip these steps. Otherwise you might see a message like this: Sorry, we couldn't add the identity. Please try a different identity.

  1. Open a browser and navigate to the Agent pools tab for your VSTS account or TFS server:
    • VSTS: https://{your_account}.visualstudio.com/_admin/_AgentPool
    • TFS 2018: https://{your_server}/DefaultCollection/_admin/_AgentPool
    • TFS 2017: https://{your_server}/tfs/DefaultCollection/_admin/_AgentPool
    • TFS 2015: http://{your_server}:8080/tfs/_admin/_AgentPool

    The TFS URL doesn't work for me. How can I get the correct URL?

  2. Click the pool on the left side of the page and then click Roles.
  3. If the user account you're going to use is not shown, then get an administrator to add it. The administrator can be an agent pool administrator, a VSTS account owner, or a TFS server administrator. If it's a deployment group agent, the administrator can be an deployment group administrator, a VSTS account owner, or a TFS server administrator. You can add a user to the deployment group adminstrator role in the Security tab on the Deployment Groups page of the Build & Release hub.

Q: I'm concerned about security. How is this account used? A: Agent communication.

Download and configure the agent

VSTS and TFS 2017 and newer

  1. Log on to the machine using the account for which you've prepared permissions as explained above.
  2. In your web browser, sign on to VSTS or TFS, and navigate to the Agent pools tab:
    • VSTS: https://{your_account}.visualstudio.com/_admin/_AgentPool
    • TFS 2018: https://{your_server}/DefaultCollection/_admin/_AgentPool
    • TFS 2017: https://{your_server}/tfs/DefaultCollection/_admin/_AgentPool
    • TFS 2015: http://{your_server}:8080/tfs/_admin/_AgentPool

    The TFS URL doesn't work for me. How can I get the correct URL?

  3. Click Download agent.
  4. On the Get agent dialog box, click OS X.
  5. Click the Download button.
  6. Follow the instructions on the page.

TFS 2015

  1. Browse to the latest release on GitHub.

  2. Follow the instructions on that page to download the agent.

  3. Configure the agent.

    ./config.sh
    

Server URL

VSTS: https://{your-account}.visualstudio.com

TFS 2017 and newer: https://{your_server}/tfs

TFS 2015: http://{your_server}:8080/tfs

Authentication type

VSTS

Choose PAT, and then paste the PAT token you created into the command prompt window.

Note

When using PAT as the authentication method, the PAT token is used only for the initial configuration of the agent. Learn more at Communication with VSTS or TFS.

TFS

Important

Make sure your server is configured to support the authentication method you want to use.

When you configure your agent to connect to TFS, you've got the following options:

  • Alternate Connect to TFS using Basic authentication. After you select Alternate you'll be prompted for your credentials.

  • Integrated Not supported on macOS or Linux.

  • Negotiate (Default) Connect to TFS as a user other than the signed-in user via a Windows authentication scheme such as NTLM or Kerberos. After you select Negotiate you'll be prompted for credentials.

  • PAT Supported only on VSTS and TFS 2017 and newer. After you choose PAT, paste the PAT token you created into the command prompt window. Use a personal access token (PAT) if your TFS instance and the agent machine are not in a trusted domain. PAT authentication is handled by your TFS instance instead of the domain controller.

Note

When using PAT as the authentication method, the PAT token is used only for the initial configuration of the agent on newer versions of TFS. Learn more at Communication with VSTS or TFS.

Run interactively

For guidance on whether to run the agent in interactive mode or as a service, see Agents: Interactive vs. service.

To run the agent interactively:

  1. If you have been running the agent as a service, uninstall the service.

  2. Run the agent.

    ./run.sh
    

Run as a launchd service

We provide the ./svc.sh script for you to run and manage your agent as a launchd LaunchAgent service. The service has access to the UI to run your UI tests.

Note

If you prefer other approaches, you can use whatever kind of service mechanism you prefer. See Service files.

Tokens

In the section below, these tokens are replaced:

  • {agent-name}

  • {tfs-name}

For example, you have configured an agent (see above) with the name our-osx-agent. In the following examples, {tfs-name} will be either:

  • VSTS: the name of your account. For example if you connect to https://fabrikam.visualstudio.com , then the service name would be vsts.agent.fabrikam.our-osx-agent

  • TFS: the name of your on-premises TFS AT server. For example if you connect to http://our-server:8080/tfs, then the service name would be vsts.agent.our-server.our-osx-agent

Commands

Change to the agent directory

For example, if you installed in the myagent subfolder of your home directory:

cd ~/myagent$

Install

Command:

./svc.sh install

This command creates a launchd plist that points to ./runsvc.sh. This script sets up the environment (more details below) and starts the agent's host.

Start

Command:

./svc.sh start

Output:

starting vsts.agent.{tfs-name}.{agent-name}
status vsts.agent.{tfs-name}.{agent-name}:

/Users/{your-name}/Library/LaunchAgents/vsts.agent.{tfs-name}.{agent-name}.plist

Started:
13472 0 vsts.agent.{tfs-name}.{agent-name}

The left number is the pid if the service is running. If second number is not zero, then a problem occurred.

Status

Command:

./svc.sh status

Output:

status vsts.agent.{tfs-name}.{agent-name}:

/Users/{your-name}/Library/LaunchAgents/vsts.{tfs-name}.{agent-name}.testsvc.plist

Started:
13472 0 vsts.agent.{tfs-name}.{agent-name}

The left number is the pid if the service is running. If second number is not zero, then a problem occurred.

Stop

Command:

./svc.sh stop

Output:

stopping vsts.agent.{tfs-name}.{agent-name}
status vsts.agent.{tfs-name}.{agent-name}:

/Users/{your-name}/Library/LaunchAgents/vsts.{tfs-name}.{agent-name}.testsvc.plist

Stopped

Uninstall

You should stop before you uninstall.

Command:

./svc.sh uninstall

Automatic log on and lock

The service runs when the user logs in. If you want the agent service start when the machine restarts, you can configure the machine it to automatically log on and lock on startup. See Auto Logon and Lock.

Update environment variables

When you configure the service, it takes a snapshot of some useful environment variables for your current logon user such as PATH, LANG, JAVA_HOME, ANT_HOME, and MYSQL_PATH. If you need to update the variables (for example, after installing some new software):

  1.  

    ./env.sh 
    
  2.  

    ./svc.sh stop
    
  3.  

    ./svc.sh start
    

The snapshot of the environment variables is stored in .env file under agent root directory, you can also change that file directly to apply environment variable changes.

Run instructions before the service starts

You can also run your own instructions and commands to run when the service starts. For example, you could set up the environment or call scripts.

  1. Edit runsvc.sh.

  2. Replace the following line with your instructions:


# insert anything to setup env when running as a service

Service Files

When you install the service, some service files are put in place.

.plist service file

A .plist service file is created:

~/Library/LaunchAgents/vsts.agent.{tfs-name}.{agent-name}.plist

For example:

~/Library/LaunchAgents/vsts.agent.fabrikam.our-osx-agent.plist

sudo ./svc.sh install generates this file from this template: ./bin/vsts.agent.plist.template

.service file

./svc.sh start finds the service by reading the .service file, which contains the path to the plist service file described above.

Alternative service mechanisms

We provide the ./svc.sh script as a convenient way for you to run and manage your agent as a launchd LaunchAgent service. But you can use whatever kind of service mechanism you prefer.

You can use the template described above as to facilitate generating other kinds of service files. For example, you modify the template to generate a service that runs as a launch daemon if you don't need UI tests and don't want to configure automatic log on and lock. See Apple Developer Library: Creating Launch Daemons and Agents.

Replace an agent

When you configure an agent using the same name as an agent that already exists, you're asked if you want to replace the existing agent. If you answer Y, then make sure you remove the agent (see below) that you're replacing. Otherwise after a few minutes of conflicts, one of the agents will shut down.

Remove and re-configure an agent

To remove the agent:

  1. Stop and uninstall the service as explained above.

  2. Remove the agent.

    ./config.sh remove
    
  3. Enter your credentials.

After you've removed the agent, you can configure it again.

Help on other options

To learn about other options:

./config.sh --help

The help provides information on authentication alternatives and unattended configuration.

Capabilities

Your agent's capabilities are cataloged and advertised in the pool so that only the builds and releases it can handle are assigned to it. See Build and release agent capabilities.

In many cases after you deploy an agent you'll need to install software or utilities. Generally you should install on your agents whatever software and tools you use on your dev machine.

For example, if your build includes the npm task, then the build won't run unless there's a build agent in the pool that has npm installed.

Important

After you install new software on a agent, you must restart the agent for the new capability to show up in the pool so that the build can run.

Q & A

Where can I learn more about how the launchd service works?

Apple Developer Library: Creating Launch Daemons and Agents

launchd.plist manpage

I'm running a firewall and my code is in VSTS. What URLs does the agent need to communicate with?

If you're running an agent in a secure network behind a firewall, make sure the agent can initiate communication with the following URLs:

https://login.microsoftonline.com
https://app.vssps.visualstudio.com 
https://{accountname}.visualstudio.com
https://{accountname}.vsrm.visualstudio.com
https://{accountname}.pkgs.visualstudio.com
https://{accountname}.vssps.visualstudio.com

How do I run the agent with self-signed certificate?

Run the agent with self-signed certificate

How do I run the agent behind a web proxy?

Run the agent behind a web proxy

How do I configure the agent to bypass a web proxy and connect to VSTS?

If you want the agent to bypass your proxy and connect to VSTS directly, then you should configure your web proxy to enable the agent to access the following URLs:

  • https://management.core.windows.net

  • *.visualstudio.com

  • https://login.microsoftonline.com

  • https://app.vsspsext.visualstudio.com

Note

This procedure enables the agent to bypass a web proxy. Your build definition and scripts must still handle bypassing your web proxy for each task and tool you run in your build.

For example, if you are using a NuGet task, you must configure your web proxy to support bypassing the URL for the server that hosts the NuGet feed you're using.

I'm using TFS and the URLs in the sections above don't work for me. Where can I get help?

Web site settings and security

I use TFS on-premises and I don't see some of these features. Why not?

Some of these features are available only on VSTS and not yet available on-premises. Some features are available on-premises if you have upgraded to the latest version of TFS.