{"id":37073554,"url":"https://github.com/cvandijck/azure-devops-tools","last_synced_at":"2026-01-14T08:38:07.700Z","repository":{"id":270755526,"uuid":"908593700","full_name":"cvandijck/azure-devops-tools","owner":"cvandijck","description":"Practical tooling for Azure Devops","archived":false,"fork":false,"pushed_at":"2025-11-27T22:43:06.000Z","size":941,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-21T23:51:08.671Z","etag":null,"topics":["azure-devops","backlog","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cvandijck.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-12-26T13:04:09.000Z","updated_at":"2025-10-20T13:16:24.000Z","dependencies_parsed_at":null,"dependency_job_id":"f6fe213f-03c9-420e-b3fb-d32cb97ca73e","html_url":"https://github.com/cvandijck/azure-devops-tools","commit_stats":null,"previous_names":["cvandijck/azure-devops-tools"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/cvandijck/azure-devops-tools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cvandijck%2Fazure-devops-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cvandijck%2Fazure-devops-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cvandijck%2Fazure-devops-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cvandijck%2Fazure-devops-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cvandijck","download_url":"https://codeload.github.com/cvandijck/azure-devops-tools/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cvandijck%2Fazure-devops-tools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28414668,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T08:31:27.429Z","status":"ssl_error","status_checked_at":"2026-01-14T08:31:19.098Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["azure-devops","backlog","python"],"created_at":"2026-01-14T08:38:07.036Z","updated_at":"2026-01-14T08:38:07.683Z","avatar_url":"https://github.com/cvandijck.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Azure DevOps Practical Tools\n\n\u003c!-- Basic Python --\u003e\n[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)\n[![Development Status](https://img.shields.io/badge/status-alpha-orange.svg)](https://pypi.org/project/adopt/)\n[![PyPI version](https://badge.fury.io/py/adopt.svg)](https://badge.fury.io/py/adopt)\n[![License](https://img.shields.io/badge/license-BSD--3--Clause-green.svg)](https://opensource.org/licenses/BSD-3-Clause)\n\n\u003c!-- Repository --\u003e\n[![GitHub](https://img.shields.io/badge/github-azure--devops--tools-blue.svg)](https://github.com/cvandijck/azure-devops-tools)\n[![CI](https://github.com/cvandijck/azure-devops-tools/workflows/Build,%20Test%20and%20Install/badge.svg)](https://github.com/cvandijck/azure-devops-tools/actions)\n\n\u003c!-- Tooling --\u003e\n[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)\n[![ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)\n[![pytest](https://img.shields.io/badge/pytest-enabled-blue.svg)](https://github.com/pytest-dev/pytest)\n\n![logo](adopt_logo.png)\n\n\u003cbr\u003e\n\n\u003e _To Augustin, a PM with an imperturbable annoyance for all things Azure DevOps.. Without your daily complaints, this project would not exist._\n\n\u003cbr\u003e\n\u003cbr\u003e\n\n**A**zure **D**ev**O**ps **P**ractical **T**ools is a set of tools to automate working with Azure Devops. The tools are developed as a CLI tool `adopt` to easily manage your Azure Devops project. The tool is actively being developed and tools are continuously being added. Suggestions for new tools are always welcome and can be requested via the [GitHub issues](https://github.com/cvandijck/azure-devops-tools/issues) or, even better, by [contributing](#contribute) to the project.\n\n## Installation\n\nThe preferred way to install `adopt` to use as a global CLI tool is to install it via `uv` and run it via `uvx`, the `pipx` variant for the `uv` package manager.\n\nIf you don't have `uv` and `uvx` installed yet, you can install it by running:\n\n```console\nwinget install --id=astral-sh.uv\n```\n\nor by following the instructions on the [uv website](https://docs.astral.sh/uv/).\n\nAfter installing `uv`, you can install `adopt` as a uv tool by running:\n\n```console\nuv tool install adopt@latest\n```\n\nand then run the tool by running:\n\n```console\nuvx adopt\n```\n\nAlternatively, you can install `adopt` as a CLI tool using pip or globally using pipx:\n\n```console\npython -m pip install adopt\n```\n\nOr install it as a global CLI tool using pipx:\n\n```console\npipx install adopt\n```\n\n## Getting Started\n\nAdopt is developed as a CLI tool to easily manage your Azure Devops project. You can discover which tools are available by displaying the help page of the console script:\n\n```console\nadopt --help\n```\n\nFor each command, you need to provide different arguments to connect to your specific Azure Devops project and team.\n\nLuckily, a lot of these arguments can be stored in a configuration file, so you don't have to provide them each time you run a command. More information on how to configure the tool can be found in the [Configuration](#configuration) section.\n\n### Backlog Print\n\nGet a nicely formatted overview of your backlog in your terminal.\n\n```console\nadopt backlog print --url \u003cazure_devops_org_url\u003e --token \u003cazure_devops_personal_token\u003e --project \u003cazure_devops_project\u003e --team \u003cazure_devops_team\u003e --category \u003cazure_devops_backlog_category\u003e\n```\n\n### Backlog Sort\n\nTired of cleaning up your backlog by dragging work items each time you had a backlog refinement or planning session?\nWith this short command you can automatically sort the backlog following the specific order you like.\n\n```console\nadopt backlog sort --url \u003cazure_devops_org_url\u003e --token \u003cazure_devops_personal_token\u003e --project \u003cazure_devops_project\u003e --team \u003cazure_devops_team\u003e --category \u003cazure_devops_backlog_category\u003e --sort_key \u003cazure_devops_work_item_field\u003e\n```\n\nThe `--sort_key` argument determines the order in which the work items will be sorted in the backlog. The value of the `--sort_key` argument should be a string of characters, where each character represents a field of the work item. The order of the characters in the string determines the order in which the work items will be sorted. In lower case, an acending order is used. When capitalized, the item will be sorted in descending order. The following characters are supported:\n\n| Key   | Field                            |\n| ----- | -------------------------------- |\n| **i** | Iteration path of item           |\n| **p** | Priority of item                 |\n| **t** | Title of item                    |\n| **r** | Rank of parents in their backlog |\n\n\nFor example, the default sorting key `Iprt` command will sort the work items in the backlog first by *iteration path* in descending order (bringing the latest iteration on top), then followed by *priority*, *parent rank* and *title* in ascending order, bringing highest prio work items to the top, with additional sorting by parent item ranking and finally title.\n\n### Backlog Check\n\nCheck the backlog for any inconsistencies. The following checks can be performed:\n\n- Check if all work items have a parent\n- Check if all work items have are assigned\n- Check if all work items have story points assigned\n\nEach check can be enabled separately by using the `--check-{option}` argument, or all at once using the `--check-all` argument.\n\n```console\nadopt backlog check --url \u003cazure_devops_org_url\u003e --token \u003cazure_devops_personal_token\u003e --project \u003cazure_devops_project\u003e --team \u003cazure_devops_team\u003e --category \u003cazure_devops_backlog_category\u003e [--check-all] [--check-parent] [--check-assigned] [--check-points]\n```\n\n### Backlog Fix\n\nThe `backlog fix` command can automatically fix inconsistencies in the backlog. The following fixes can be performed:\n\n- Update the parent work item *State* based on the state of the child work items\n- Update the parent work item *Iteration Path* based on the assigned to of the child work items\n\nEach fix can be enabled separately by using the `--fix-{option}` argument, or all at once using the `--fix-all` argument.\n\n```console\nadopt backlog fix --url \u003cazure_devops_org_url\u003e --token \u003cazure_devops_personal_token\u003e --project \u003cazure_devops_project\u003e --team \u003cazure_devops_team\u003e --category \u003cazure_devops_backlog_category\u003e [--fix-all] [--fix-state] [--fix-iteration]\n```\n\n### Debug logging\nEach command has logging functionality built in. The level of logging can be set by using the `--log-level` argument. The default log level is `INFO`.\n\n### Configuration\n\nFor each command, you need to provide different arguments to connect to your specific Azure Devops project and team. To make the (re)execution of `adopt` commands easier and facilitates its use in different environments, multiple pathways are provided to configure the tool.\n\nEach configuration option will load predefined values for the required arguments as environment variables, so the first option to provide the required arguments is by setting these variables in the (local) environment.\n\n\n| Argument    | Environment Variable                  | Description                                               |\n| ----------- | ------------------------------------- | --------------------------------------------------------- |\n| `--token`   | `ADOPT_AZURE_DEVOPS_PAT`              | A personal access token to authenticate with Azure Devops |\n| `--url`     | `ADOPT_AZURE_DEVOPS_ORGANIZATION_URL` | The URL of your Azure Devops organization                 |\n| `--project` | `ADOPT_AZURE_DEVOPS_PROJECT_NAME`     | The name of the project you want to work with             |\n| `--team`    | `ADOPT_AZURE_DEVOPS_TEAM_NAME`        | The name of the team you want to work with                |\n\nThese values can also be loaded, or overwritten, by a local `.env` file in the working directly from which `adopt` is executed.\n\nAlternatively, a TOML-styled configuration file `.adopt` can be used locally in the project directory or globally in the user's home directory to set these required arguments:\n\n```toml\n[adopt]\ntoken = \"\u003cazure_devops_personal_token\u003e\"\nurl = \"\u003cazure_devops_org_url\u003e\"\nproject = \"\u003cazure_devops_project\u003e\"\nteam = \"\u003cazure_devops_team\u003e\"\n```\n\n\u003e [!NOTE]\n\u003e A combination between the configuration file and an environment variable for your *Azure Personal Access Token* is recommended to safely manage these predefined arguments.\n\n## Nightly Backlog Management\nAdopt can be used to automatically manage your backlog on a nightly basis. The easiest way to do this is to add a DevOps pipeline to your project that runs the required `adopt` commands on a nightly basis. An example YAML pipeline to run the `backlog sort` command can be found below:\n\n```yaml\ntrigger: none\n\nparameters:\n- name: logLevel\n  displayName: 'Log Level'\n  type: string\n  default: 'INFO'\n  values:\n  - DEBUG\n  - INFO\n  - WARNING\n  - ERROR\n  - CRITICAL\n\nvariables:\n  url: \"https://dev.azure.com/\u003cyour_organization\u003e\"\n  project: \"\u003cyour_project\u003e\"\n  team: \"\u003cyour_team\u003e\"\n\nschedules:\n- cron: \"0 0 * * *\"\n  displayName: Nightly run\n  branches:\n    include:\n    - main\n\npool:\n  vmImage: 'ubuntu-latest'\n\njobs:\n- job: ManageBacklog\n  displayName: 'Manage Backlog'\n  variables:\n    ADOPT_AZURE_DEVOPS_ORGANIZATION_URL: $(url)\n    ADOPT_AZURE_DEVOPS_PROJECT_NAME: $(project)\n    ADOPT_AZURE_DEVOPS_TEAM_NAME: $(team)\n  steps:\n  - task: UsePythonVersion@0\n    inputs:\n      versionSpec: '3.x'\n      addToPath: true\n    displayName: 'Use Latest Python'\n\n  - script: |\n      python -m pip install --upgrade pip\n      pip install adopt\n    displayName: 'Install latest version of adopt'\n\n  - script: |\n      adopt backlog sort --token $(System.AccessToken) --log-level \"${{ parameters.logLevel }}\" 2\u003e\u00261 | tee adopt_output.log\n\n      exit_code=${PIPESTATUS[0]}\n      if [ $exit_code -ne 0 ]; then\n        echo \"##vso[task.logissue type=error]adopt backlog sort failed with exit code $exit_code\"\n        exit $exit_code\n      elif grep -q \"WARNING\" adopt_output.log; then\n        echo \"##vso[task.logissue type=warning]WARNING detected in adopt backlog sort output\"\n        echo \"##vso[task.complete result=SucceededWithIssues;]WARNING found but continuing pipeline\"\n        exit 0\n      else\n        echo \"No warnings detected - sort completed successfully\"\n        exit 0\n      fi\n    displayName: 'Sort backlog'\n\n  - script: |\n      adopt backlog check --token $(System.AccessToken) --log-level \"${{ parameters.logLevel }}\" 2\u003e\u00261 | tee adopt_check_output.log\n\n      exit_code=${PIPESTATUS[0]}\n      if [ $exit_code -ne 0 ]; then\n        echo \"##vso[task.logissue type=error]adopt backlog check failed with exit code $exit_code\"\n        exit $exit_code\n      elif grep -q \"WARNING\" adopt_check_output.log; then\n        echo \"##vso[task.logissue type=warning]WARNING detected in adopt backlog check output\"\n        echo \"##vso[task.complete result=SucceededWithIssues;]WARNING found but continuing pipeline\"\n        exit 0\n      else\n        echo \"No warnings detected - check completed successfully\"\n        exit 0\n      fi\n    displayName: 'Check backlog'\n```\n\n## Contribute\n\nIn `adopt`, the incredibly fast package manager `uv` is used to setup and manage the project. To get started with the project, you can install `uv` by running:\n\n```console\nwinget install --id=astral-sh.uv\n```\n\nor by following the instructions on the [uv website](https://docs.astral.sh/uv/).\n\nAfter installing `uv`, you can setup the project by running:\n\n```console\nuv sync\n```\nFor convenience, most operations required to contribute or manage this project are available as `make` commands.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcvandijck%2Fazure-devops-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcvandijck%2Fazure-devops-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcvandijck%2Fazure-devops-tools/lists"}