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:
| Deployment | URL |
|---|---|
| Azure DevOps Services | https://dev.azure.com/your-organization. An https://your-organization.visualstudio.com URL also works. |
| Azure DevOps Server 2020 or later | The 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.
A Microsoft Entra service principal works with Azure DevOps Services only. Context7 gets short-lived tokens for it. No employee account is involved.
Create an app registration
In the Microsoft Entra admin center, create an app registration. Add a client secret. If Context7 runs on AKS with Azure workload identity, add a federated credential instead.
Check the tenant
In Azure DevOps, open Organization settings → Microsoft Entra. Make sure that the organization is connected to the tenant of the app registration.
Add the app to the organization
Open Organization settings → Users. Add the app as a user with Stakeholder access. Stakeholder access has no license cost. Then add the app to the Readers group of each project to index.
Connect Context7
Select Service principal (Entra ID). Enter the organization URL, the directory (tenant) ID, and the application (client) ID. Paste the client secret. With workload identity, leave the secret empty. Choose Test connection, then save.
The secret field accepts an empty value only when the deployment has workload identity, that is, when AZURE_FEDERATED_TOKEN_FILE is set. Context7 gets tokens from https://login.microsoftonline.com. For a sovereign cloud, set AZURE_AUTHORITY_HOST.
Azure DevOps Server#
- Use version 2020 or later.
- If the server uses an internal or self-signed certificate, set
NODE_EXTRA_CA_CERTSto the path of your CA bundle. - Use
https://. Context7 refuseshttp://, because the credential goes with every request. For an internal server without TLS, setAZURE_DEVOPS_ALLOW_HTTP=true. Azure DevOps Services always useshttps://.
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.
| Filter | Effect |
|---|---|
| Work item types | Only these types |
| States | Only work items in these states |
| Area paths | Only these areas. With Include sub-areas on, also every area under them |
| Changed in the last | Only work items changed in this number of days (1–3650) |
| Include comments | Also 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.
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.
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.