Azure Pipeline Agent Plan
Azure Pipelines Agent is a lightweight, powerful tool used to execute jobs in Azure DevOps pipelines. It handles tasks defined in pipeline configuration files (YAML format), such as building, testing, and deploying code. The agent fetches code from the Azure DevOps repository, runs it in a predefined environment, and returns the results to Azure DevOps. For more information, refer to the official Azure Pipelines Agent documentation.
Document Overview
This document provides step-by-step instructions for adding a self-hosted agent to an Azure DevOps pipeline. Self-hosted agents are used to execute jobs on machines that you manage, offering greater control and customization compared to Azure-hosted agents.
Adding a Self-Hosted Agent to a Project
On Azure DevOps, navigate to the project where you want to add the agent.
In the top right corner, click the settings icon, then select Personal Access Tokens.
In the top right corner, select New Token.
Give your token a name, set the expiration date to at least a year, and make sure under “Scopes” you enable Full Access.
Click Create and MAKE SURE YOU SAVE YOUR TOKEN SOMEWHERE. Once the token is generated, you will not be able to access it again unless you have it saved locally.
Setting Up your Agent on MacinCloud
Log in to the MacinCloud Portal.
From the dashboard, navigate to Agents > Azure Pipeline Agent.
Once selecting your agent you will see a page similar to this.
Select the agent under your subscriptions.
Click Actions > Edit Agent and complete the necessary fields:
Agent Name: Choose a name for your runner.
Pool Name: Confirm your available runner groups under Project Settings > Agent Pools. If you want to create a new runner group for better control over your self-hosted runners, follow the instructions in the Azure documentation. Otherwise, you can use the default runner group if available.
Server URL: This should be the organization where you want the agent to be active. (https://dev.azure.com/{yourorganization}).
Version: The latest release version is preselected, but you may choose previous stable releases if necessary.
Access Token: Enter the token generated in Azure earlier when setting up your agent.
Once done, click Update and allow up to 2 minutes for the changes to take effect.
When your agent is successfully configured, you should see the following confirmation.
Verifying Your Agents Connection
On Azure DevOps, navigate to the project where you added the new agent.
Under your project, select Project Settings. This should be on the bottom of the left sidebar.
In the left sidebar, under Pipelines select Agent pools.
Select the Agent pool your runner is associated with. In this example our runner is using the default pool.
Select the Agents tab. This will display all your agents under the default pool.
A green dot next to your runner indicates that it has successfully connected, is online, and ready for jobs.
Troubleshooting your Agent
If your agent has not been successfully configured, it will enter an error state. Below are common examples and steps to resolve the issues:
Wrong Token: VS30063: You are not authorized to access https://dev.azure.com. Please verify that the access token is valid and update the agent with a valid token.
Wrong URL: The resource cannot be found.
Expired Token: Access Denied. The Personal Access Token used has expired. Please replace the expired token with a valid one and update the agent accordingly.
Pool Not Found: Agent pool not found. Please replace the agent pool with a valid one and update the agent accordingly.
These errors typically occur when the repository URL or runner group does not exist or has been incorrectly entered, preventing your Azure agent from connecting to your Azure repository. Additionally, if the register token is incorrectly entered or has expired, the runner will fail to be verified.
Steps to Resolve Wrong Token Error:
Navigate to the runner in the error state and select Actions > Edit Agent.
Verify that the Access Token is entered correctly and matches the one provided by Azure when you created your agent.
If any of the information appears incorrect, please replace it with the correct information and select update.
If all information appears correct, navigate to the runner in the error state and click Actions > Restart.
If restarting the agent does not resolve the issue, please contact support.
Steps to Resolve Wrong URL Error:
Navigate to the runner in the error state and select Actions > Edit Agent.
Ensure the Server URL is entered correctly.
If any of the information appears incorrect, please replace it with the correct information and select update.
If all information appears correct, navigate to the runner in the error state and click Actions > Restart.
If restarting the agent does not resolve the issue, please contact support.
Steps to Resolve Expired Token Error:
Navigate to the runner in the error state and select Actions > Edit Agent.
Verify that the Access Token is entered correctly and matches the one provided by Azure when you created your agent. If that is the case your token is expired and needs to be replaced.
If your access token appears to be expired, please replace it with the new token and select update.
If all information appears correct, navigate to the runner in the error state and click Actions > Restart.
If restarting the agent does not resolve the issue, please contact support.
Steps to Resolve Pool Not Found Error:
Navigate to the runner in the error state and select Actions > Edit Agent.
Verify the Pool Name and ensure the correct group is selected. If you haven't created an agent pool, the default group should be used. If you have created a custom agent pool, make sure it is entered correctly.
If any of the information appears incorrect, please replace it with the correct information and select update.
If all information appears correct, navigate to the runner in the error state and click Actions > Restart.
If restarting the agent does not resolve the issue, please contact support.