How to Get Started with Azure DevOps: Setup & Fix Guide
Why Getting Started with Azure DevOps Feels So Confusing
I've helped dozens of developers and project managers get Azure DevOps running for the first time, and nearly every one of them hits the same wall: the platform is genuinely powerful, but the onboarding experience throws a lot at you all at once. You sign up, land on a dashboard with five or six different services listed , Azure Boards, Azure Repos, Azure Pipelines, Azure Test Plans, Azure Artifacts, and suddenly it feels less like a tool and more like an entire software factory you didn't ask to manage.
Here's what's actually happening. Azure DevOps is not a single product. It's a suite of integrated cloud services designed to cover the entire software development lifecycle, from planning a feature to shipping it to production. Microsoft's documentation describes it as an end-to-end platform that supports everything from initial planning through to deployment and monitoring. That's genuinely true, but it also means you can't just "install" Azure DevOps and start coding. You need to understand how the pieces connect before the experience clicks into place.
The most common friction points I see when people try to get started with Azure DevOps include:
- Organization and project structure confusion. Azure DevOps groups everything under an "organization," and projects live inside that organization. New users often don't realize they need to create an organization first, or they accidentally create multiple organizations because the sign-up flow isn't crystal clear.
- Permission and access errors. If you're joining an existing team's Azure DevOps organization rather than creating your own, you've probably seen a message like "You do not have access to this resource" or been dumped on a blank project page with nothing to click. This almost always comes down to how your role was configured, or wasn't configured, by the project administrator.
- Stakeholder vs. Basic access confusion. Azure DevOps has multiple access levels. Free stakeholder access gives you limited interaction with boards and work items. If you try to do something that requires Basic access, like editing pipelines or working in Repos, you'll hit invisible walls without any obvious error message explaining why.
- Which service do I even need? A developer just wants to push code. A project manager just wants to track tasks. A QA engineer needs test plans. But the sign-up flow doesn't ask what you're there to do, it presents everything simultaneously, which is overwhelming if you've never worked in a DevOps toolchain before.
- Connection problems with IDEs and local tools. Azure DevOps supports several client-based connection models, including direct IDE integrations and SSH authentication for Git repos. First-time users often skip the authentication setup and then wonder why their git push fails.
None of these are bugs. They're byproducts of a platform designed for teams of wildly different sizes and needs, from a solo developer using the free tier all the way to enterprise organizations with thousands of users across dozens of projects. The platform scales up gracefully, but that same scalability means it doesn't "just work" without a few intentional setup steps.
I know this is frustrating, especially when you just want to start shipping code. The good news: once you understand the structure, setup is actually fast. Let's fix it. Browse all Microsoft fix guides →
The Quick Fix, Sign Up and Launch Your First Project in 10 Minutes
If you're starting from scratch, no existing organization, no team already using Azure DevOps, this section gets you operational fast. You'll have a working project with code hosting, a task board, and a build pipeline skeleton in about ten minutes. I'll cover the detailed steps in the next section, but here's the sprint version.
Go to dev.azure.com and sign in with your Microsoft account. If you don't have one, create a free Microsoft account first, any email address works, it doesn't need to be an Outlook address. Once you're signed in, Azure DevOps will prompt you to create a new organization. Pick a name, choose your closest geographic region (this affects where your data is hosted and your pipeline build speeds), and hit Continue.
You'll land directly in a new project creation screen. Give your project a name. The two key settings here are Version control (choose Git unless you specifically need TFVC for legacy reasons) and Work item process. For most teams, Agile or Scrum works well. If you're not sure, pick Agile, it gives you User Stories, Bugs, and Tasks without a lot of extra process overhead. Hit Create project.
That's it for the core setup. You now have access to all five Azure DevOps services within that project. From the left navigation rail you'll see icons for Boards, Repos, Pipelines, Test Plans, and Artifacts. Click Repos first, you'll see your empty Git repository with instructions to push your first code. You can clone it via HTTPS right away using the Clone to your computer button and the provided URL.
For team members you want to add, go to Project Settings (the gear icon at the bottom left) → Teams → Add. Or go to Organization Settings → Users to add them to the organization first. They'll receive an email invitation.
Everything in Azure DevOps starts at the organization level. Think of an organization as the top-level container, your projects, users, billing, and settings all live here. You get one free organization with your Microsoft account, and free tier includes unlimited private repositories and up to five users with Basic access. That's genuinely enough to get a small team running without spending a cent.
Navigate to dev.azure.com in your browser. Sign in with your Microsoft account. If your company uses Azure Active Directory (now called Microsoft Entra ID), sign in with your work account, this connects your DevOps organization to your company's identity system, which matters for permission management later.
On first sign-in, you'll see the "Create new organization" prompt. Click New organization. You'll be asked to:
- Accept the Terms of Service
- Confirm your organization name (this becomes part of your URL:
dev.azure.com/yourorgname) - Choose a data hosting region
Organization names must be globally unique across all Azure DevOps. If your preferred name is taken, try adding your company abbreviation or a year. Once created, the name cannot be changed without deleting and recreating the organization, so choose intentionally.
If you're joining an existing organization instead of creating one, you need the organization URL from your admin and an invitation sent to your email. If your admin added you by email address, check your inbox for a subject line like "You've been added to [OrganizationName]". If you don't see it, ask your admin to confirm they used the exact email address tied to your Microsoft account, a common mismatch is corporate email vs. personal Microsoft account.
When setup succeeds, you land on the Azure DevOps homepage showing all projects in your organization. If you see a blank screen instead, your account likely has Stakeholder access, a free tier that restricts certain navigation options. Your organization admin can upgrade you to Basic access from Organization Settings → Users.
Projects are the working containers inside your organization. Each project gets its own Boards, Repos, Pipelines, Test Plans, and Artifacts namespace. For most small teams, one project is enough. Larger organizations often use multiple projects to separate product lines or departments, but don't overthink this early on. You can always restructure later.
From your organization homepage, click the New project button in the top-right corner. Fill in:
- Project name: Keep it short and recognizable. Avoid special characters, the project name appears in URLs.
- Description: Optional, but useful when you have multiple projects.
- Visibility: Private is the default and the right choice for most teams. Public projects are visible to anyone on the internet, useful for open source, but be careful about accidentally exposing internal code or pipeline secrets.
- Version control: Select Git. Team Foundation Version Control (TFVC) is a legacy centralized system that Microsoft still supports but no longer actively develops. New projects should always use Git.
- Work item process: Choose Agile for User Stories and Tasks, Scrum if your team runs formal sprints with Product Backlog Items, or CMMI for change-management-heavy organizations. You can also choose Basic for the simplest possible setup with just Issues and Tasks.
Click Create. Azure DevOps will spin up all five services and redirect you to your new project's summary page. From here, the left navigation rail gives you access to every service. You'll also see a Project Settings gear icon at the bottom of the left rail, this is where you manage teams, service connections, permissions, and more.
To add your first team members, go to Project Settings → Teams → [Your Team Name] → Add. Or for organization-wide user management, use Organization Settings → Users → Add users. Enter email addresses and assign an access level. For most developers, Basic is the right access level. Stakeholder access is appropriate for non-technical stakeholders who only need to view boards and comment on work items.
If your project was created successfully, you'll see the summary page load without errors and all five service links will be active in the left navigation. That's your green light to move on.
Azure Boards is where your team's work lives, user stories, bugs, tasks, epics, sprints. It's the planning layer that connects everything else. A bug found in Azure Test Plans can be linked to a work item in Boards. A commit in Azure Repos can reference a work item ID. A pipeline deployment can automatically move a work item to "Done." That integration is what makes Boards worth setting up properly from the start.
Click Boards in the left navigation. You'll see a few sub-sections: Work Items, Boards, Backlogs, Sprints, and Queries. Start with Backlogs to add your first set of work items.
Click the + New Work Item button at the top of the backlog view. If you chose the Agile process, you'll add User Stories as your top-level work items. Type a brief title and hit Enter, the item is created immediately. Click on it to open the full work item form, where you can set:
- Assigned To: The team member responsible
- State: New → Active → Resolved → Closed
- Iteration: Which sprint this belongs to
- Area: Which team or component area this covers
- Story Points / Effort: For estimation and velocity tracking
To set up your first sprint, go to Boards → Sprints. You'll see a default sprint already created. Click the sprint name to edit its start and end dates. Drag work items from the backlog into the sprint to assign them. Azure Boards will automatically calculate your sprint capacity and show a burndown chart as the sprint progresses, that data populates in real time as your team updates work item states.
The Kanban board view (under Boards → Boards) gives you the column-based drag-and-drop experience. You can customize column names to match your team's actual workflow, for example, adding a "In Review" column between "Active" and "Resolved." Go to Boards settings → Columns to add or rename columns.
Once your backlog has a few items and your sprint is configured, the Boards setup is done. Work items created here will be referenceable from commits and pull requests in Azure Repos using the syntax AB#[work-item-id].
Azure Repos gives your team unlimited private Git repositories inside your project. You get branch policies, pull request workflows with code reviews, and conflict resolution tools, all without needing GitHub or Bitbucket. If your team is already on GitHub, you can still connect Azure Pipelines to a GitHub repo, but if you want everything under one roof, Azure Repos is the way to go.
Click Repos in the left navigation. Your project comes with one Git repository already created, named after your project. You'll see the repository is empty with three options to get started:
- Clone to your computer, copies the empty repo locally so you can push code
- Push an existing repository from command line, for projects you've already started locally
- Import a repository, to pull in code from GitHub, Bitbucket, or another Git host
To clone via HTTPS, click Clone in the top-right corner of the Repos page. Copy the HTTPS URL. In your terminal:
git clone https://dev.azure.com/yourorgname/yourproject/_git/yourrepoYou'll be prompted for credentials. The cleanest option is to use a Personal Access Token (PAT) as your password. Generate one by clicking your profile picture (top-right of the Azure DevOps interface) → Personal Access Tokens → New Token. Give it a name, set an expiration, and under Scopes select Code → Read & Write. Copy the token, you only see it once.
For SSH authentication (which avoids repeated credential prompts), go to User Settings → SSH public keys and add your public key. Then use the SSH clone URL instead of HTTPS. The SSH URL format looks like: git@ssh.dev.azure.com:v3/yourorgname/yourproject/yourrepo.
Once you've pushed your first commit, you can set up branch policies to protect your main branch. Go to Project Settings → Repos → Policies → [your branch]. Turn on Require a minimum number of reviewers and Check for linked work items. These two policies alone dramatically improve your team's code quality without adding much overhead.
When your first push succeeds and you can see the files in the Azure Repos browser interface, this step is complete.
Azure Pipelines is the automation engine of Azure DevOps. Every time someone pushes code to your repo, a pipeline can automatically build the application, run tests, create a deployable artifact, and push it to a staging or production environment. Getting your first pipeline running, even a minimal one, is the moment Azure DevOps starts feeling like a real DevOps platform rather than just a ticket tracker with code hosting.
Click Pipelines in the left navigation, then click Create Pipeline. Azure DevOps will ask where your code lives:
- Azure Repos Git, if your code is in Azure Repos (most likely for new setups)
- GitHub, if your repo is on GitHub
- Bitbucket Cloud, for Bitbucket repos
- Other options for other hosting providers
Select Azure Repos Git, then select your repository. Azure Pipelines will analyze your repo and suggest a YAML template. For a Node.js app, you'll see the Node.js template. For a .NET app, the ASP.NET template. For a generic project, choose Starter pipeline. The starter pipeline gives you a minimal azure-pipelines.yml file like this:
trigger:
- main
pool:
vmImage: ubuntu-latest
steps:
- script: echo Hello, world!
displayName: 'Run a one-line script'
- script: |
echo Add other tasks to build, test, and deploy your project.
echo See https://aka.ms/yaml
displayName: 'Run a multi-line script'Click Save and run. Azure DevOps commits this YAML file to your repository and immediately queues the first pipeline run. You'll be taken to the pipeline run view where you can watch the live log output from the build agent.
The first run uses a Microsoft-hosted agent running Ubuntu. You don't need to provision any servers, Azure DevOps manages the build agent infrastructure for free on the Microsoft-hosted pool (with usage limits on free tier). If you need Windows or macOS agents, change vmImage: ubuntu-latest to windows-latest or macOS-latest.
When the run shows a green checkmark and "Job succeeded," your pipeline is working. From here, you can add real build steps, test runners, and deployment stages. Each stage in a production pipeline typically looks like: Build → Test → Package → Deploy to Staging → Deploy to Production, with approval gates between the last two stages.
Advanced Troubleshooting
Once you've completed basic setup, you'll inevitably hit some trickier problems. Here are the ones I see most often among teams who are a few weeks into Azure DevOps and starting to push the platform harder.
Permission Errors and "TF401019" or "TF30063" Codes
Error TF401019 means "The Git repository with the name or identifier [x] does not exist or you do not have permissions for the operation you are requesting." Error TF30063 is a generic authorization failure. Both of these almost always mean one of two things: either your account doesn't have the right access level, or you're authenticated as the wrong identity.
Check your access level at Organization Settings → Users → [your account]. If you see "Stakeholder," ask your admin to change it to "Basic." If you're already on Basic and still seeing 401s, check that your Personal Access Token hasn't expired, go to your profile → Personal Access Tokens and look for the expiry date. Regenerate if needed.
For domain-joined enterprise machines, there's a subtler issue: your Windows credential manager may be storing an old Azure DevOps credential. Open Windows Credential Manager (search for it in Start), click Windows Credentials, and look for any entries containing dev.azure.com or visualstudio.com. Delete them and re-authenticate.
Pipeline Fails with "No hosted parallelism has been purchased or granted"
This is a very common issue for free tier accounts created after a certain policy change Microsoft made. Free Azure DevOps organizations now need to request free pipeline minutes manually. Go to Organization Settings → Billing and check your parallel jobs allocation. If you see 0 Microsoft-hosted parallel jobs, you need to submit a request to Microsoft for the free grant, there's a form linked directly from the Billing settings page. It typically takes 2-3 business days for approval.
As a workaround in the meantime, you can set up a self-hosted agent on your own machine. Go to Organization Settings → Agent pools → Add pool, then follow the instructions to download and configure the agent on your local machine or a VM. Self-hosted agents have no parallelism limits and run your pipelines locally.
SSH Authentication Failing for Azure Repos
If git push via SSH fails with "Permission denied (publickey)," check the following sequence. First, confirm your SSH key is added under User Settings → SSH public keys in Azure DevOps, not just locally in your SSH config. Second, verify SSH connectivity by running:
ssh -T git@ssh.dev.azure.comYou should see a response like remote: Shell access is not supported., that's actually success. If you see a timeout or "Connection refused," your network may be blocking outbound port 22. In that case, switch to HTTPS authentication with a PAT.
Group Policy and Firewall Restrictions in Enterprise Environments
Enterprise networks with strict egress filtering sometimes block connections to dev.azure.com or the various Azure service endpoints that pipelines need to reach. Azure Pipelines requires outbound HTTPS (port 443) access to *.dev.azure.com, *.vsassets.io, *.visualstudio.com, and several Azure CDN domains. Ask your network team to check the firewall logs for dropped connections to these domains. Microsoft publishes a full list of required IP ranges and FQDNs in the Azure DevOps IP address and URL allowlist documentation.
For Group Policy-controlled machines where users can't install the Azure DevOps CLI or configure local Git credentials, the recommended approach is to use service connections at the organization level rather than individual user credentials for pipeline authentication. Set these up under Project Settings → Service connections.
Prevention & Best Practices
Getting Azure DevOps running is one thing. Keeping it running smoothly as your team grows is a different challenge. After watching teams stumble through the same avoidable problems repeatedly, here's what I consistently recommend setting up before your project is more than a few weeks old.
Set up proper permission groups from day one. Azure DevOps ships with default security groups: Project Administrators, Contributors, and Readers. Assign users to these groups rather than giving individual permissions, it's far easier to manage access when someone changes roles. Go to Project Settings → Permissions → Groups to review and configure these. Adding a new developer? Add them to Contributors. Adding a stakeholder who only needs to review boards? Add them to Readers.
Protect your main branch with policies before you invite anyone. Once multiple people start committing, an unprotected main branch is a liability. Enable Require a minimum number of reviewers (set to at least 1), Check for linked work items, and Check for comment resolution under Project Settings → Repos → Policies. These three policies ensure no code lands on main without a review and a traceable work item.
Use Personal Access Tokens with minimum required scopes. I see a lot of teams generate PATs with "Full access" because it's the easy option. Don't. A leaked full-access PAT can be catastrophic, it gives the holder the same permissions as your account across the entire organization. Give each PAT a specific scope (e.g., Code Read & Write only), set a short expiration (90 days max), and rotate them regularly.
Document your pipeline's service connections and secrets early. When pipelines need to deploy to Azure or connect to external services, those credentials go into Project Settings → Service connections or Pipelines → Library → Variable groups. Write down what each service connection is used for. I've seen teams inherit pipelines they can't touch because the service connection credentials belong to an employee who left the company, and no one documented what they were for.
Create a dashboard for each team. Azure DevOps dashboards let you surface key metrics, build health, sprint burndown, open bugs, in a single view. It takes 15 minutes to set one up under Overview → Dashboards → New dashboard, and it dramatically reduces the "wait how far are we in the sprint?" questions in standups.
- Enable multi-factor authentication for your Microsoft account before you create your Azure DevOps organization, it's your first and most important security layer
- Create a dedicated "Service Account" Microsoft account for pipeline service connections, separate from any individual's personal account, so credentials don't break when someone leaves
- Set a PAT expiration reminder in your calendar, Azure DevOps won't warn you until the day it expires, and a silently failing pipeline at 2 AM is not a fun discovery
- Pin your most-used project to your Azure DevOps organization homepage using the star icon on the project card, saves 2-3 clicks every single day
Frequently Asked Questions
What exactly is Azure DevOps and do I need all five services?
Azure DevOps is Microsoft's cloud platform that bundles five integrated services: Azure Boards (planning and work tracking), Azure Repos (Git code hosting), Azure Pipelines (CI/CD automation), Azure Test Plans (manual and automated testing management), and Azure Artifacts (package feed hosting). You absolutely do not need to use all five from the start, most small teams begin with Boards and Repos, then add Pipelines once they have code worth automating. You can enable or disable services per project under Project Settings → Overview → Azure DevOps services, which also keeps your navigation cleaner while you're getting started.
Is Azure DevOps actually free? What are the real limits on the free tier?
Yes, Azure DevOps has a genuinely usable free tier. You get unlimited private Git repositories, five users with Basic access (which covers Boards, Repos, and basic Pipelines usage), and unlimited Stakeholder access for non-technical team members. Free tier also includes 2 GB of Azure Artifacts storage. The main constraint is pipeline parallelism, you get one free Microsoft-hosted parallel job with 1,800 minutes per month, which is plenty for most small projects. If you exceed that, you can purchase additional parallel jobs through Organization Settings → Billing, where pricing is per-pipeline-job per month.
What is Azure Boards and how is it different from Jira?
Azure Boards is a work item tracking and agile project management tool built directly into Azure DevOps. You can create user stories, bugs, tasks, and epics, organize them into sprints, track progress with Kanban boards and burndown charts, and link every work item to commits and pull requests in Azure Repos. The main difference from Jira is tight, native integration with the rest of the Azure DevOps suite, a commit that mentions AB#1234 automatically updates work item 1234's status, no plugin required. Jira has a broader marketplace ecosystem, but for teams already using Azure Repos and Pipelines, Boards is usually the simpler choice with less setup friction.
What is Azure Pipelines and can I use it with GitHub instead of Azure Repos?
Azure Pipelines is the CI/CD service inside Azure DevOps, it builds, tests, and deploys your application automatically in response to code changes. Yes, it works natively with GitHub repositories, not just Azure Repos. During pipeline creation, you choose your source, GitHub, Azure Repos, Bitbucket Cloud, or other providers. When you connect to GitHub, Azure Pipelines installs itself as a GitHub App and gets notified on push events just like a native GitHub Action would. Many teams run Azure Pipelines on GitHub repos specifically for its deployment gate features and Azure service integration, which can be more powerful than GitHub Actions for complex enterprise deployments.
How do I add users to my Azure DevOps project and what access level should they have?
You add users at two levels: the organization level first, then the project level. Go to Organization Settings → Users → Add users, enter their email address, and set an access level, Basic for developers and most contributors, Stakeholder for product owners or executives who only need to view and comment on boards. After they're added to the organization, they're not automatically in your project; go to Project Settings → Teams → [Team Name] → Add to include them. If someone was added to the organization by email but their account uses a different Microsoft identity (say a personal account vs. a work account), they may not receive the invitation, confirm the exact email address tied to their Microsoft account before assuming they're misconfigured.
What is Azure Test Plans and do small teams actually need it?
Azure Test Plans is the manual and exploratory testing management service inside Azure DevOps. You create test suites, write test cases with step-by-step instructions, execute them on specific builds, capture screenshots and videos of bugs, and generate test result reports, all linked back to work items in Boards and builds in Pipelines. For small teams, the honest answer is that Azure Test Plans is optional. If your team writes automated tests that run in your pipeline, that covers a lot of ground. Test Plans adds real value when you have a dedicated QA role, need formal sign-off before releases, or are building products that require documented evidence of testing for compliance or audit purposes. Note that Azure Test Plans requires a separate license beyond Basic access, it's not included in the free tier.