Navigation: Home > Tutorials > Connect to Azure DevOps
This tutorial walks you through the process of connecting to Azure DevOps using the Azure DevOps Node API. By the end of this guide, you'll be able to establish a connection and verify that it works correctly.
Before you begin, make sure you have:
First, create a new directory for your project and initialize it:
mkdir azure-devops-connection
cd azure-devops-connection
npm init -y
Install the azure-devops-node-api package:
npm install azure-devops-node-api
Create a new file named config.js to store your Azure DevOps connection information:
// config.js
module.exports = {
orgUrl: "https://dev.azure.com/your-organization",
token: process.env.AZURE_DEVOPS_PAT || "your-personal-access-token"
};
Replace your-organization with your organization name and your-personal-access-token with your PAT.
🔒 Security Note: In a real application, you should store sensitive information like tokens in environment variables or a secure vault, not in your code files.
Create a new file named connect.js with the following code:
// connect.js
const azdev = require("azure-devops-node-api");
const config = require("./config");
/**
* Establishes a connection to Azure DevOps and verifies it works
* @returns {Promise<object>} The WebApi connection object
*/
async function connect() {
try {
console.log("Creating connection to Azure DevOps...");
// Create authentication handler using Personal Access Token
const authHandler = azdev.getPersonalAccessTokenHandler(config.token);
// Create WebApi instance with organization URL and auth handler
const connection = new azdev.WebApi(config.orgUrl, authHandler);
// Connect and get connection data to verify connection works
console.log("Connecting...");
const connectionData = await connection.connect();
console.log("Connection successful!");
console.log(`Connected to organization: ${connectionData.instanceId}`);
console.log(`API Version: ${connectionData.apiVersion}`);
console.log(`Server deployment type: ${connectionData.deploymentType}`);
return connection;
} catch (error) {
// Handle specific error types
if (error.statusCode === 401) {
console.error("Authentication failed. Check your Personal Access Token.");
} else if (error.statusCode === 404) {
console.error("Organization not found. Check your organization URL.");
} else if (error.message && error.message.includes("certificate")) {
console.error("SSL Certificate error. You may need to configure SSL options.");
} else {
console.error("Connection failed:", error.message);
}
throw error;
}
}
// Self-executing async function to run the example
(async () => {
try {
// Establish connection to Azure DevOps
const connection = await connect();
// Get a client for a specific API area
const workItemTrackingApi = await connection.getWorkItemTrackingApi();
console.log("Work Item Tracking API client created successfully");
// List some projects to verify the connection works
const projects = await workItemTrackingApi.getProjects();
console.log("\nProjects in your organization:");
// Display up to 5 projects
projects.slice(0, 5).forEach(project => {
console.log(`- ${project.name}`);
});
// If there are more than 5 projects, indicate how many more
if (projects.length > 5) {
console.log(` ... and ${projects.length - 5} more projects`);
}
} catch (error) {
console.error("Error:", error.message);
process.exit(1);
}
})();
Run the script to test your connection:
node connect.js
If everything is set up correctly, you should see output similar to:
Creating connection to Azure DevOps...
Connecting...
Connection successful!
Connected to organization: 01234567-89ab-cdef-0123-456789abcdef
API Version: 7.1
Server deployment type: Hosted
Work Item Tracking API client created successfully
Projects in your organization:
- Project Alpha
- Project Beta
- Project Gamma
...
You can try different authentication methods by modifying your connection code:
// Using username and password (not recommended for production)
const username = "your-username";
const password = "your-password";
const basicAuthHandler = azdev.getBasicHandler(username, password);
const connection = new azdev.WebApi(config.orgUrl, basicAuthHandler);
// Using bearer token
const bearerToken = "your-bearer-token";
const connection = azdev.WebApi.createWithBearerToken(config.orgUrl, bearerToken);
// Using NTLM for on-premises Azure DevOps Server
const username = "domain\\username";
const password = "your-password";
const ntlmAuthHandler = azdev.getNtlmHandler(username, password);
const connection = new azdev.WebApi(config.orgUrl, ntlmAuthHandler);
You can configure various connection options to customize the behavior of the WebApi client:
// Proxy settings
const options = {
proxy: {
proxyUrl: "http://proxy-server:8080",
proxyUsername: "proxy-user",
proxyPassword: "proxy-password",
proxyBypassHosts: ["localhost"]
}
};
const connection = new azdev.WebApi(config.orgUrl, authHandler, options);
// SSL settings
const options = {
ignoreSslError: false, // Set to true to ignore SSL errors (not recommended for production)
cert: {
caFile: "/path/to/ca.pem",
certFile: "/path/to/cert.pem",
keyFile: "/path/to/key.pem",
passphrase: "certificate-passphrase"
}
};
const connection = new azdev.WebApi(config.orgUrl, authHandler, options);
// HTTP settings
const options = {
socketTimeout: 30000, // 30 seconds
allowRetries: true,
maxRetries: 3
};
const connection = new azdev.WebApi(config.orgUrl, authHandler, options);
If you encounter any issues, here are some common problems and solutions:
ignoreSslError: true or configure the appropriate certificates.Now that you've successfully connected to Azure DevOps, you can:
Check out the other tutorials and API references for more information on working with specific Azure DevOps services.
Here's a complete example that puts everything together:
const azdev = require("azure-devops-node-api");
require("dotenv").config(); // Load environment variables from .env file
// Get configuration from environment variables
const orgUrl = process.env.AZURE_DEVOPS_ORG_URL;
const token = process.env.AZURE_DEVOPS_TOKEN;
if (!orgUrl || !token) {
console.error("Please set AZURE_DEVOPS_ORG_URL and AZURE_DEVOPS_TOKEN environment variables");
process.exit(1);
}
async function connectToAzureDevOps() {
try {
// Create authentication handler using Personal Access Token (PAT)
const authHandler = azdev.getPersonalAccessTokenHandler(token);
// Connection options
const options = {
allowRetries: true,
maxRetries: 2
};
// Create WebApi instance
const connection = new azdev.WebApi(orgUrl, authHandler, options);
// Connect and verify
const connectionData = await connection.connect();
console.log(`Connected to ${connectionData.instanceId}`);
// Example: Get Git API client
const gitApi = await connection.getGitApi();
console.log("Git API client created successfully");
// Example: Get Work Item Tracking API client
const workItemTrackingApi = await connection.getWorkItemTrackingApi();
console.log("Work Item Tracking API client created successfully");
// Example: Get Build API client
const buildApi = await connection.getBuildApi();
console.log("Build API client created successfully");
return {
connection,
gitApi,
workItemTrackingApi,
buildApi
};
} catch (error) {
console.error("Failed to connect to Azure DevOps", error);
throw error;
}
}
// Usage
(async () => {
try {
const { gitApi, workItemTrackingApi, buildApi } = await connectToAzureDevOps();
// Now you can use these API clients to interact with Azure DevOps
// Example: List repositories
const repositories = await gitApi.getRepositories();
console.log(`Found ${repositories.length} repositories`);
// Example: List work items
const workItems = await workItemTrackingApi.getWorkItems([1, 2, 3]);
console.log(`Retrieved ${workItems.length} work items`);
// Example: List build pipelines
const buildPipelines = await buildApi.getDefinitions("YourProject");
console.log(`Found ${buildPipelines.length} build pipelines`);
} catch (error) {
console.error("Error:", error.message);
}
})();