Harnessing Azure DevOps CLI for On-Prem Azure DevOps Server Automation

Unlocking the Power of Azure DevOps CLI on Your On-Prem Azure DevOps Server​

Microsoft’s Azure DevOps ecosystem continues to evolve—even for on-premises installations. If you’re running Azure DevOps Server (formerly known as TFS) in your organization and want to streamline your development workflow using the Azure CLI, you’ve come to the right place. This article takes you through the process of setting up and using the Azure DevOps Extension for Azure CLI with Azure DevOps Server. Whether you’re automating builds, managing repositories, or creating work items on the fly, read on to learn how to get started with a few easy-to-follow steps.

---

Introduction​

In an era where rapid development and continuous deployment are the norms, automation is key. Azure CLI, known for its versatility and simplicity, becomes an even more powerful tool when armed with the Azure DevOps extension. While many associate Azure DevOps commands with cloud-based environments, on-premises deployments have their own unique advantages—and challenges. One significant challenge is authentication, since Azure DevOps Server does not support the standard Azure login, requiring the use of Personal Access Tokens (PATs).
In this article, we will cover:

• Installing the Azure CLI and verifying your installation
• Adding the Azure DevOps extension
• Configuring your CLI specifically for an on-prem Azure DevOps Server instance
• Authenticating using a Personal Access Token (PAT)
• Running common Azure DevOps CLI commands
• Troubleshooting common issues

By the end of this guide, you’ll have a complete picture of how to harness the power of Azure CLI for your Azure DevOps Server environment—allowing you to automate repetitive tasks and improve overall productivity.

---

Setting Up Your Environment​

Before diving into the commands and configurations, it’s crucial to ensure that your environment is set up properly. This involves installing Azure CLI and the Azure DevOps extension. Let’s break down the steps.

1. Installing Azure CLI​

The Azure CLI is a cross-platform command-line tool that allows you to manage Azure resources efficiently. Even if you’re working with on-prem Azure DevOps Server, the CLI is an indispensable tool.
Steps:

• Download and Install:
  Visit the official Microsoft documentation for the Azure CLI Installation Guide and follow the instructions for your operating system. The installation process is straightforward and typically just requires a few clicks.
• Verification:
  Once installed, open your command prompt or terminal and run:
  az --version
  This command prints the version of Azure CLI installed on your system. It’s a quick way to confirm that the installation has been successful.

Key Point:
A correctly installed Azure CLI is the groundwork for everything that follows.

2. Installing the Azure DevOps Extension​

With the CLI in place, the next step is to extend its capabilities via the Azure DevOps extension. This extension adds a suite of commands specific to Azure DevOps, making it a potent tool irrespective of whether you’re operating in the cloud or on-premises.
Steps:

• Add the extension:
  In your command prompt or terminal, run:
  az extension add --name azure-devops
  This command downloads and integrates the Azure DevOps commands into your CLI environment.
• Verify installation:
  To ensure that the extension has been added successfully, execute:
  az extension list
  You should see the azure-devops extension in the list of available extensions.

---

Configuring the CLI for an On-Prem Azure DevOps Server​

Azure DevOps Server is a self-hosted solution, meaning that it resides on your internal network rather than in the cloud. Consequently, you must configure your CLI with a custom URL that points to your server instance.

Setting Your Defaults​

Customizing the Azure DevOps CLI’s default settings means that you don’t have to specify your server URL and project with every command. Instead, you set these parameters once, and they persist throughout your CLI session.
Command to set defaults:
az devops configure --defaults organization=[url]https://your-server-url/collection-name[/url] project=your-project-name
For example, if your on-prem server is hosted at devops.mycompany.com with the collection named “DefaultCollection” and you’re working on a project called “MyProject,” your command would look like this:
az devops configure --defaults organization=[url]https://devops.mycompany.com/DefaultCollection[/url] project=MyProject
Tip:
Ensure that your URL precisely matches your server’s configuration. An incorrect URL can lead to errors such as “Invalid organization.”
Why This Matters:
By setting your defaults, you save time and reduce the risk of typographical errors in every command. This is particularly useful in environments where multiple projects or collections exist.

---

Authenticating with Azure DevOps Server Using a Personal Access Token (PAT)​

Unlike Azure’s cloud services, Azure DevOps Server does not support the standard Azure login, so you must authenticate using a Personal Access Token. PATs offer a secure and straightforward method of authenticating your CLI sessions.

Generating a PAT in Azure DevOps Server​

Before you can authenticate, you need to generate a PAT. Here’s how:

1. Access the Azure DevOps Server UI:
   Log in to your on-prem Azure DevOps Server.
2. Navigate to User Settings:
   Click on the user icon (often represented by a gear or profile icon) and select the “User Settings” option.
3. Access the Personal Access Tokens Section:
   Within the settings menu, find the “Personal Access Tokens” area. Click on it to start generating your new token.
4. Create a New Token:
   • Click on “New Token.”
   • Choose the necessary scopes. For instance, if you need to read and write code or manage work items, select the corresponding permissions, such as Code (Read & Write) or Work Items.
   • Note: It is important to select the minimum necessary permissions to maintain the security of your server.
5. Copy Your Token:
   Once the token has been created, make sure to copy and store it securely. You will not be able to view it again after this step.

Authenticating via the CLI​

Once your PAT is ready, use the following command to log in:
az devops login --organization [url]https://your-server-url/collection-name[/url]
When you run this command, you will be prompted to enter your PAT. Alternatively, you can include the token directly in your command:
az devops login --organization [url]https://your-server-url/collection-name[/url] --pat <YOUR_PERSONAL_ACCESS_TOKEN>
Best Practice:
Avoid embedding your PAT directly in scripts. Instead, use environment variables or other secure methods to handle sensitive information.
Key Consideration:
Using a PAT for authentication ensures that your operations are securely linked to your permissions. This method stands as a robust security measure in environments where Azure’s native login isn’t available.

---

Running Azure DevOps CLI Commands: A Few Examples​

With your environment set up and authentication in place, you can now leverage the powerful commands offered by the Azure DevOps extension. Here are a few examples to get you started:

Listing Repositories​

To view all repositories in your current project, simply run:
az repos list
This command will return a list of all repositories in the configured project, providing useful details such as repository names and identifiers.

Creating a Work Item​

Suppose you need to quickly log a bug—there’s no need to navigate through the UI. You can create a work item directly from the command line:
az boards work-item create --title "Fix bug in login" --type Bug
This command not only creates a work item with a clear title but also categorizes it as a bug, ensuring that your team can prioritize it accordingly.

Queueing a Build​

When it’s time to trigger a build, the following command does the trick:
az pipelines run --name MyPipeline
This command queues a build for the specified pipeline, kicking off your automated build process almost instantly.
Real-World Case:
Imagine a scenario where a developer commits a crucial fix, and the CI/CD pipeline needs to start running immediately. With these commands, the process is automated—saving time and reducing manual intervention.

---

Troubleshooting Common Errors​

Even the best-laid plans can encounter bumps. Here’s how to handle some common issues you may face.

“Invalid Organization” Error​

• Cause:
  This error often occurs when the organization URL does not exactly match your Azure DevOps Server URL.
• Solution:
  Double-check your URL. It should include the correct server address, collection name, and port (if applicable).

Authentication Issues​

• Cause:
  Incorrect or expired PATs can prevent successful login.
• Solution:
  Generate a new PAT if necessary and ensure that it has the proper permissions. Always verify that you’re using the valid token when executing the command.

“Command not found” Error​

• Cause:
  Often due to the Azure CLI or the Azure DevOps extension not being installed or configured properly.
• Solution:
  Confirm that you have installed both the Azure CLI and the Azure DevOps extension using the commands provided earlier. Running “az extension list” can help verify that the extension is present.

Tip for Smooth Sailing:
Keep your CLI and its extensions updated. Microsoft frequently releases updates and bug fixes, ensuring that you have the latest functionality and security improvements. Use:
az upgrade
to ensure you’re running the newest version.

---

Best Practices and Tips​

In any technical environment, efficiency and security are paramount. Here are some best practices to consider when using the Azure DevOps CLI with your on-prem Azure DevOps Server:

• Automate Routine Tasks:
  Use shell scripts or batch files to automate repetitive tasks. This is especially useful for tasks such as repository management and build automation.
• Keep Your PAT Secure:
  Treat your Personal Access Token like a password. Never expose it in public repositories or unsecured scripts.
• Leverage Defaults to Save Time:
  Setting global defaults for your organization and project streamlines your workflow. This prevents the need to repeatedly specify these parameters.
• Regularly Update Tools:
  Always use the latest versions of Azure CLI and its extensions. This not only gives you access to new features but also patches critical security vulnerabilities.
• Document Your Process:
  Maintain an internal knowledge base or wiki that documents the steps and commands you use frequently. Over time, this documentation can significantly ease onboarding for new team members.
• Test Changes in a Safe Environment:
  Before integrating new commands into your core processes, test them in a development environment to avoid unintended disruptions.

---

Conclusion​

Integrating the Azure DevOps Extension for Azure CLI with your on-prem Azure DevOps Server is a game-changing strategy for modern development workflows. By following these easy steps—installing the Azure CLI, adding the Azure DevOps extension, configuring your defaults, securing your connection with a Personal Access Token, and learning essential commands—you can harness the full potential of automation in your development processes.
Using automation to manage repositories, create work items, and trigger pipelines not only saves time but also reduces human error. As you become more comfortable with these commands, you’ll discover endless possibilities to streamline operations, improve collaboration among development teams, and maintain a secure and efficient development environment.
Do you ever wonder how much time you could save if manual server management tasks were automated? With the Azure DevOps CLI approach, that future is already here. Embrace the change, update your workflows, and take your on-prem Azure DevOps Server to new heights.
For further discussions on automating Windows environments, optimizing your development pipelines, and troubleshooting common issues, explore more topics on WindowsForum.com. Happy automating!

---

Summary of Key Points​

• Installation:
  Start by installing Azure CLI, verify with “az --version”, and then add the Azure DevOps extension using “az extension add.”
• Configuration:
  Set your on-prem Azure DevOps Server defaults (organization URL and project) using “az devops configure --defaults.”
• Authentication:
  Generate a Personal Access Token (PAT) from the Azure DevOps Server UI and authenticate using “az devops login.”
• Command Execution:
  Run commands such as “az repos list”, “az boards work-item create”, and “az pipelines run” to interact with your server.
• Troubleshooting:
  Tackle common errors like “Invalid organization”, authentication issues, or missing commands by verifying your configuration and updating your tools.

By incorporating these practices into your workflow, you ensure that your on-prem Azure DevOps Server is not only operational but optimized for the modern demands of software development.

---

Source: Medium