How to Set up Azure DevOps Linux Runner as a systemd Service

This guide outlines the steps to configure an Azure DevOps Linux runner as a systemd service, ensuring it starts automatically on boot and can be easily managed.

Prerequisites

• A Linux machine (e.g., Ubuntu, Debian, CentOS)
• An Azure DevOps organization and project
• The Azure DevOps agent package downloaded and extracted (refer to Azure DevOps documentation)
• sudo privileges

Steps

1. Create a dedicated user for the runner:

   sudo useradd -m -d /home/azagent azagent
   sudo passwd azagent  # Set a password for the azagent user
   sudo chown -R azagent:azagent /opt/azagent #If the agent is installed on /opt/azagent

   Replace /home/azagent and `/opt/azagent` with your desired home and agent installation directories respectively.

2. Install necessary dependencies:

   Ensure that any dependencies required by your build pipelines are installed on the machine. This might include tools like Node.js, .NET SDK, Python, etc.

   Example for installing .NET SDK:

   sudo apt-get update
   sudo apt-get install -y dotnet-sdk-6.0

3. Configure the Azure DevOps agent:

   sudo su - azagent
   cd /opt/azagent #Navigate to the agent installation directory
   ./config.sh --url 'YOUR_AZURE_DEVOPS_ORGANIZATION_URL' --auth PAT --token 'YOUR_PERSONAL_ACCESS_TOKEN' --pool 'YOUR_AGENT_POOL_NAME' --agent 'YOUR_AGENT_NAME' --work '_work' --acceptTeeEula --runasservice

   Replace the placeholders (YOUR_AZURE_DEVOPS_ORGANIZATION_URL, YOUR_PERSONAL_ACCESS_TOKEN, YOUR_AGENT_POOL_NAME, YOUR_AGENT_NAME) with your actual Azure DevOps values. Make sure to configure your PAT with the needed permission. Usually agent pool (read, manage) is needed.

   During configuration, you might be prompted for further details, such as the work directory and agent name. The --runasservice flag is important as it generates the systemd service file.

4. Verify systemd service file:

   The config.sh script (with --runasservice) creates a systemd service file. The location may vary, but it’s often in /etc/systemd/system/. Look for a file named something like vstsagent.azagent.YOUR_AGENT_NAME.service.

   Example:

   ls /etc/systemd/system/vstsagent.azagent.*.service

5. Start and enable the systemd service:

   sudo systemctl start vstsagent.azagent.YOUR_AGENT_NAME.service
   sudo systemctl enable vstsagent.azagent.YOUR_AGENT_NAME.service

   Replace YOUR_AGENT_NAME with the actual agent name used during configuration.

6. Check the service status:

   sudo systemctl status vstsagent.azagent.YOUR_AGENT_NAME.service

   Verify that the service is running without errors. Check the output for details about the current status, any issues, and recent logs.

Troubleshooting

• Service fails to start:
  • Check the service file for errors (typos, incorrect paths).
  • Verify that the azagent user has the necessary permissions to access the agent directory and associated files.
  • Examine the service logs (using journalctl -u vstsagent.azagent.YOUR_AGENT_NAME.service) for detailed error messages.
• Agent not appearing in Azure DevOps:
  • Ensure the agent is correctly registered and configured with the correct organization URL, PAT, and agent pool name.
  • Check the agent logs in the _diag directory within the agent installation directory for connection errors.
  • Verify that the machine has network connectivity to Azure DevOps.

Notes

• Regularly update the agent software to benefit from bug fixes and new features. This can be done by downloading a new version from Azure DevOps and re-running the configuration scripts.
• Consider using a dedicated firewall rule to allow only necessary communication to/from the agent machine.
• Customize the systemd service file if needed (e.g., adjusting resource limits).