Skip to main content

Context7 can index the work items of an Azure DevOps project and keep them in sync. It works with Azure DevOps Services (dev.azure.com) and with Azure DevOps Server 2020 or later.

An admin connects Azure DevOps once under Workspace Settings › Azure DevOps. Then an admin adds libraries from Add source → Azure DevOps. Each library is one project with a set of filters. Each work item becomes one page.

Project wikis and Git repositories in Azure DevOps are Git repositories. Index them through Other Git.

What is indexed#

Each work item page contains:

  • The ID, type, and title.
  • A details line: state and reason, area, iteration, priority, severity, assigned to, tags, parent, created date, and changed date.
  • The rich-text fields: description, acceptance criteria, repro steps, system info, resolution, and the CMMI justification, proposed fix, and analysis fields.
  • Custom fields of your process. Short values go in the details line. Long text and HTML fields get their own section. Context7 uses the display name of each field.
  • The comments, when Include comments is on. Context7 reads up to 200 comments for each work item. Deleted comments are left out.

Context7 does not index:

  • Attachments and images in fields or comments.
  • Work item history and earlier revisions.
  • Links to other work items, except the parent.
  • Work items that the credential cannot read.
  • HTML that a reader of the work item does not see, such as HTML comments and hidden elements.

Azure DevOps hides some work item types, such as test plans, code reviews, and feedback. Context7 also hides these types and disabled types in the type list. If you select no types, the library includes every type. To index only some types, select them.

Set up the connection#

Open Workspace Settings › Azure DevOps. Choose an authentication method, fill in the fields, and choose Test connection. The test shows how many projects the credential can see. Then save.

The organization URL is the part of the browser address before the project name:

DeploymentURL
Azure DevOps Serviceshttps://dev.azure.com/your-organization. An https://your-organization.visualstudio.com URL also works.
Azure DevOps Server 2020 or laterThe collection URL, for example https://server/tfs/DefaultCollection

Context7 stores the credential encrypted. Replace the credential at any time. Your libraries keep working, because they are tied to the organization URL, not to the credential.

A personal access token (PAT) works with Azure DevOps Services and Azure DevOps Server.

Use a service account

Sign in to Azure DevOps as a service account that can read the projects to index. Do not use a personal account. If that person leaves, indexing stops.

Create the token

Open User settings → Personal access tokens and create a token for the organization. Give it only the Work Items (Read) scope.

Connect Context7

Select Personal access token. Enter the organization URL and paste the token. Choose Test connection, then save.

Tokens expire. Paste a new token before the old one expires. On Azure DevOps Services, a service principal does not expire in this way.

Azure DevOps Server#

  • Use version 2020 or later.
  • If the server uses an internal or self-signed certificate, set NODE_EXTRA_CA_CERTS to the path of your CA bundle.
  • Use https://. Context7 refuses http://, because the credential goes with every request. For an internal server without TLS, set AZURE_DEVOPS_ALLOW_HTTP=true. Azure DevOps Services always uses https://.

Add a library#

Click Add source and choose Azure DevOps. Only admins can add Azure DevOps libraries.

Name the library

Enter a title, for example Firmware backlog. Optionally, describe what the work items cover.

Select a project

Choose the Azure DevOps project.

Choose the filters

Leave a filter empty to include everything that it covers.

FilterEffect
Work item typesOnly these types
StatesOnly work items in these states
Area pathsOnly these areas. With Include sub-areas on, also every area under them
Changed in the lastOnly work items changed in this number of days (1–3650)
Include commentsAlso index the comments. This costs one extra request for each changed work item

The Matches row shows how many work items match.

Add the library

Choose Add library. Context7 fetches the work items, converts them to Markdown, and indexes them.

Warning

You cannot edit the filters after you add a library. To change them, add a new library with the new filters, then delete the old library.

Results link to the work item in Azure DevOps. For authority labels, match the area path, for example Firmware Team\Radar.

Limits#

A library indexes at most 20,000 work items by default. If more work items match, Context7 keeps the newest ones (the highest IDs). The library then shows a warning.

To change the limit, open Workspace Settings › Parsing and set Max work items per Azure DevOps library. You can also set AZURE_DEVOPS_MAX_WORK_ITEMS on the server. A value saved in the dashboard wins. The range is 1–200,000, or no limit (0). A better fix is often to narrow the filters.

Sync#

The default schedule is daily at 03:30 in the server timezone. Change or disable it under Workspace Settings › Azure DevOps, or choose Sync all now. From a library, choose Refresh to sync it alone. Only admins can sync Azure DevOps libraries.

Each sync lists the matching work items again:

  • Context7 fetches and indexes only the work items that changed since the last sync.
  • A work item that no longer matches the filters leaves the index. This includes deleted work items and work items that the credential can no longer read.
  • A new work item that matches the filters joins the index.

To fetch and index every work item again, choose Refresh and select Re-index all work items.

When a sync fails#

Context7 keeps the indexed content when a sync fails:

  • The listing fails. For example, the credential expired or the project is gone. The library keeps its indexed work items and shows the error. Context7 retries after 15 minutes, 1 hour, and 6 hours.
  • A work item fails. It keeps its last indexed version. It retries on the next sync. The Azure DevOps card lists the failed work items. Choose Export failures as CSV for the full list.
  • A sync would remove too many work items. If the filters did not change, and a sync would remove all work items, or more than half of a library with 20 or more work items, Context7 stops the sync and keeps the index. This usually means that the credential lost access to part of the project. Check the access of the credential. If the removal is expected, choose Refresh with Re-index all work items.

Context7 retries throttled requests (HTTP 429) and server errors. It waits as long as Azure DevOps asks, up to 2 minutes for each retry.

If you change the connection to a different organization, existing libraries stop syncing and keep their content. Add the libraries again for the new organization. Disconnecting Azure DevOps also stops syncs and keeps the content. Delete a library to stop serving it.

Access#

The credential controls what Context7 can read. Library access rules control who can query the indexed work items.

A new Azure DevOps library starts restricted to admins. Grant access to the groups or users who need it before members can query it. A sync never changes the access you set.

Network#

Allow outbound HTTPS from Context7 to:

  • Your organization URL: dev.azure.com, or your Azure DevOps Server.
  • login.microsoftonline.com, for a service principal.

Wikis and repos#

The work item connector does not index wikis or repositories. A project wiki and a Git repository in Azure DevOps are Git repositories. Index them through Other Git with a personal access token.

Create a token

Create a personal access token with the Code (Read) scope, for a service account that can read the wiki or the repository.

Configure Other Git

Open Workspace Settings › Other Git and select HTTPS. Enter dev.azure.com as the host (or the host of your Azure DevOps Server). Enter any user name, for example the name of the service account. Paste the token as the password.

Add the wiki or repository

Click Add source, choose Other Git, and enter the clone URL:

  • A project wiki: https://dev.azure.com/<organization>/<project>/_git/<wiki>.wiki
  • A repository: https://dev.azure.com/<organization>/<project>/_git/<repository>

To get the wiki URL, open the wiki in Azure DevOps and choose ••• → Clone wiki. A project wiki is not in the list of repositories.

A project name can contain spaces. Encode them as %20 in the URL, for example https://dev.azure.com/acme/Firmware%20Team/_git/Firmware-Team.wiki. A wiki that you publish from a repository (“publish code as wiki”) is a normal repository. Add that repository.

Results link back to Azure DevOps. A wiki page links to the rendered wiki page. A repository file links to the file in the repository.

Note

Other Git stores credentials for one host. If you already use Other Git for a different host, you cannot also use it for Azure DevOps with HTTPS credentials.

Troubleshooting#

  • “Azure DevOps rejected the token”: The PAT is wrong or expired. Paste a new token.
  • “Azure DevOps denied access”: Give the PAT the Work Items (Read) scope. For a service principal, add it to the Readers group of the project.
  • “Azure DevOps rejected the service principal”: Add the app to the organization under Organization settings → Users.
  • “Microsoft Entra ID refused the service principal”: Check the tenant ID, the client ID, and the client secret. The error includes the reason from Entra ID, for example an expired secret.
  • “The service principal can see no projects”: Add the app to the projects to index.
  • “Use https://”: See Azure DevOps Server.
  • “The connection now points to a different organization”: Add the library again.
  • “Only the first N matching work items were indexed”: See Limits.