{"id":37055851,"url":"https://github.com/tfsaggregator/aggregator-cli","last_synced_at":"2026-01-14T06:18:19.261Z","repository":{"id":36619182,"uuid":"137602779","full_name":"tfsaggregator/aggregator-cli","owner":"tfsaggregator","description":"A new version of Aggregator aiming at Azure DevOps (ex Visual Studio Team Services)","archived":false,"fork":false,"pushed_at":"2024-10-10T05:15:19.000Z","size":1562,"stargazers_count":75,"open_issues_count":33,"forks_count":32,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-08-01T05:02:03.679Z","etag":null,"topics":["aggregator-cli","azure-devops","azure-devops-extension","azure-functions","rule-language","tfs","tfs-aggregator","vsts","vsts-integration"],"latest_commit_sha":null,"homepage":"https://tfsaggregator.github.io/","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tfsaggregator.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-06-16T18:43:12.000Z","updated_at":"2025-04-26T22:18:58.000Z","dependencies_parsed_at":"2023-01-17T03:10:50.442Z","dependency_job_id":null,"html_url":"https://github.com/tfsaggregator/aggregator-cli","commit_stats":null,"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/tfsaggregator/aggregator-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tfsaggregator%2Faggregator-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tfsaggregator%2Faggregator-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tfsaggregator%2Faggregator-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tfsaggregator%2Faggregator-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tfsaggregator","download_url":"https://codeload.github.com/tfsaggregator/aggregator-cli/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tfsaggregator%2Faggregator-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28412194,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T05:26:33.345Z","status":"ssl_error","status_checked_at":"2026-01-14T05:21:57.251Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":["aggregator-cli","azure-devops","azure-devops-extension","azure-functions","rule-language","tfs","tfs-aggregator","vsts","vsts-integration"],"created_at":"2026-01-14T06:18:18.650Z","updated_at":"2026-01-14T06:18:19.252Z","avatar_url":"https://github.com/tfsaggregator.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# aggregator-cli\n\n[![Build status](https://github.com/tfsaggregator/aggregator-cli/workflows/build-and-deploy/badge.svg)](https://github.com/tfsaggregator/aggregator-cli/actions)   [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=tfsaggregator_aggregator-cli\u0026metric=alert_status)](https://sonarcloud.io/dashboard?id=tfsaggregator_aggregator-cli)\n\nAggregator is a Rule Interpreter for Work Items events, allowing dynamic calculation of field values and more.\n\nIt is the successor to renowned TFS Aggregator.\nThe current Server Plugin version (2.x) will be maintained to support TFS.\nThe Web Service flavour will be discontinued in favour of this new tool for two reasons:\n- deployment and configuration of Web Service was too complex for most users;\n- both the Plugin and the Service rely heavily on TFS Object Model which is [deprecated](https://docs.microsoft.com/en-us/azure/devops/integrate/concepts/wit-client-om-deprecation).\n\nAggregator 3.x supports two scenarios:\n 1. Azure DevOps Services with Rules running in Azure Functions.\n 2. Docker container running in the cloud or on-premise. [v1.0]\n\nThe latter permits replacing the Server Plugin after migrating the Rule code.\n\n\u003e *Note*: This README is a synopsis of the documentation available at \u003chttps://tfsaggregator.github.io/docs/v3/\u003e.\n\nYou might also find useful Richard Fennell's post [Getting started with Aggregator CLI for Azure DevOps Work Item Roll-up](https://blogs.blackmarble.co.uk/rfennell/2020/06/12/getting-started-with-aggregator-cli-for-azure-devops-work-item-roll-up/).\n\n\n## Major features\n\n- use of new Azure DevOps REST API\n- simple deployment via CLI tool or Docker container\n- Rule language similar to TFS Aggregator v2\n\n\n### Planned features (post v1.0)\n\n- Support for Deployment Slots for blue/green-style deployments\n- OAuth support to avoid maintain access tokens\n- Additional Azure DevOps events and objects (e.g. Git)\n\n\n## Requirements\n\nTo write a Rule is required some basic knowledge of C# language and Azure Boards.\nIn addition you need:\n- an Azure DevOps Services Project\n- a Personal Access Token with sufficient permissions on the Project\n\n### CLI \u0026 Azure\nThe CLI scenario has two additional requirements:\n- an Azure Subscription\n- a Service Principal with, at least, Contributor permission on a Resource Group of the Subscription\n\n### Docker\nThe Docker scenario requires:\n- an SSL Certificate\n- an host for Docker containers (Windows or Linux)\n\n\n## How the CLI works with Azure Functions\n\nAs the name implies, this is a command line tool: you download the latest aggregator-cli*.zip appropriate for your platform from GitHub [releases](https://github.com/tfsaggregator/aggregator-cli/releases) and unzip it on your client machine.\nRead more below in the [Usage](#usage) section.\n\nThrough the CLI you create one or more Azure Functions in your Subscription. The Functions use a library named Aggregator **Runtime** to run your **Rules**.\nA Rule is code that reacts to one or more Azure DevOps event; currently, the only language for writing rules is C#.\n\nThe CLI automatically checks GitHub Releases to ensure that you use the more recent version of Aggregator Runtime available. To avoid automatic upgrades, specify the Runtime version or point to a specific Runtime package file, using an `http:` or `file:` URL.\n\nAfter you setup the Rules in Azure, you must add at least one **Mapping**. A mapping is an Azure DevOps Service Hook that send a message to the Azure Function when a specific event occurs. Currently we support only Work Item events.\nWhen triggered, the Azure DevOps Service Hook invokes a single Aggregator Rule i.e. the Azure Function hosting the Rule code. Azure DevOps saves the Azure Function Key in the Service Hook configuration.\n\nYou can deploy the same Rule in different Instances, map the same Azure DevOps event to many Rules or map multiple events to the same Rule: you choose the best way to organize your code.\n\n\n\n## CLI Authentication\n\nYou must instruct Aggregator which credential to use.\nTo do this, run the `login.azure` and `login.ado` commands.\n\nTo create the credentials, you need an Azure Service Principal and a Azure DevOps Personal Access Token. Full details in the [Setup](https://tfsaggregator.github.io/docs/v3/setup/) section.\n\nAggregator stores the logon credentials locally and expires them after 2 hours.\n\nThe PAT is also stored in the Azure Function settings: **whoever has access to the Resource Group can read it!**\n\nThe Service Principal must have Contributor permission to the Azure Subscription or, in alternative, pre-create the Resource Group in Azure and give the service account Contributor permission to the Resource Group.\n![Permission on existing Resource Group](https://tfsaggregator.github.io/docs/v3/setup/contributor-on-rg.png)\nIf you go this route, remember add the `--resourceGroup` to all commands requiring an instance.\n\nFor Docker only Azure DevOps logon is required.\n\n\n\n## CLI Usage\n\nDownload and unzip the latest CLI.zip file from [Releases](https://github.com/tfsaggregator/aggregator-cli/releases).\nIt requires [.Net Core 3.1](https://dotnet.microsoft.com/download/dotnet-core/3.1) installed on the machine.\nTo run Aggregator run `aggregator-cli.exe` (Windows), `aggregator-cli` (Linux) or `dotnet aggregator-cli.dll` followed by a verb and its options.\n\n### CLI Verbs\n\nThere are about 20 commands described in detail at [Commands](https://tfsaggregator.github.io/docs/v3/commands/).\n\nThey can be grouped in a few categories:\n* Authentication to logon into Azure and Azure DevOps.\n* Instance creation, configuration and update.\n* Rule deployment, configuration and update.\n* Mapping from Azure DevOps to Rules.\n* Informational commands, to read configuration.\n* Testing commands to validate configuration.\n\nMost commands manage Azure Function, but a few can be used in the Docker scenario.\n\nWe collected some usage scenarios at [Command Examples](https://tfsaggregator.github.io/docs/v3/commands/command-examples/).\n\n\n\n## How the Docker image works\n\nPull the latest image from [Docker Hub](https://hub.docker.com/repository/docker/tfsaggregator/aggregator3). It works on Linux and Windows.\nStart a container with the image, setting configuration through environment variables.\nThe Rules are simply files on a Docker volume that the container uses.\nThe container must expose a port reachable from your Azure DevOps instance, either Server or Service.\nAdd one or web hook to Azure DevOps using the container URL. Use one Aggregator API Key to authenticate the call. You may use the CLI to add these mappings.\n\nMore details at [Docker configuration](https://tfsaggregator.github.io/docs/v3/setup/docker/)\n\n## Rule language\n\nCurrently we offer only C# as the language to write Rules. The Rules can access a few objects:\n* The Current Work Item.\n* Work Item Store to retrieve additional Work Items.\n* The Event which triggered the Rule.\n* Project information.\n* A Logger object to track Rule steps.\n\nSee [Rule Language](https://tfsaggregator.github.io/docs/v3/rules/) for a list of objects and properties to use.\nFor examples see [Rule Examples](https://tfsaggregator.github.io/docs/v3/rules/rule-examples-basic/).\n\n\n\n## Maintenance\n\nAggregator stores the PAT in the Azure Function configuration. Before the PAT expire you should refresh it from Azure DevOps or save a new PAT using the `configure.instance` command.\n\nRead [Production Configuration and Administration](https://tfsaggregator.github.io/docs/v3/setup/production/) for recommendations on running Aggregator in production.\n\n\n## Troubleshooting\n\nUse the Application Insight instance that was created aside the Azure Function.\n\n\n## Contributing\n\nDetails on building your own version and testing are in the [Contribute](contrib/) section.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftfsaggregator%2Faggregator-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftfsaggregator%2Faggregator-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftfsaggregator%2Faggregator-cli/lists"}