A new version of Aggregator aiming at Azure DevOps (ex Visual Studio Team Services)
Switch branches/tags
Clone or download
Permalink
Failed to load latest commit information.
art ICO file Jul 8, 2018
doc Updated docs Nov 17, 2018
out added a simple option to fix runtime version Oct 24, 2018
src Add test to cleanup Nov 17, 2018
.gitignore doc edit Nov 11, 2018
LICENSE Initial commit Jun 16, 2018
README.md Updated docs Nov 17, 2018

README.md

aggregator-cli

Build status: master Build status

This is the successor to TFS Aggregator. The current Server Plugin version (2.x) will be maintained to support TFS. The Web Service flavor will be discontinued in favor of this (its deployment and configuration was too complex for most users).

The main scenario for Aggregator (3.x) is supporting Azure DevOps and the cloud scenario. It will work for TFS as long as it is reachable from Internet.

This is an early version (beta): we might change verbs and rule language before the final release! Note: The documentation is limited to this page and the content of the doc folder.

Major features

  • use of new Azure DevOps REST API
  • simple deployment via CLI tool
  • Rule object model similar to v2

Planned features

  • Support for Deployment Slots for blue/green-style deployments
  • OAuth support to avoid maintain access tokens
  • Additional Azure DevOps events
  • Additional Azure DevOps objects

How it works

An Aggregator Instance is an Azure Function Application in its own Resource Group, sharing the same Azure DevOps credential. You can have only one Application per Resource Group. If the Resource Group does not exists, Aggregator will try to create it. Note: The Instance name must be unique amongst all Aggregator Instances in Azure!

Each Aggregator Rule becomes an Azure Function in the above instance. The Rule code is parsed and run on-the-spot using Roslyn. To work, it uses an Aggregator Runtime. Aggregator checks its latest GitHub Release to ensure that Aggregator Runtime is up-to-date before uploading the function. Note: We use Azure Functions Runtime 2.0 for C# which is still in Preview.

An Aggregator Mapping is a Azure DevOps Service Hook for a specific work item event that invokes an Aggregator Rule i.e. the Azure Function hosting the Rule code. Azure DevOps saves the Azure Function Key in the Service Hook configuration.

You can deploy the same Rule in many Instances or map the same Azure DevOps event to many Rules: it is up to you choosing the best way to organize.

Authentication

You must instruct Aggregator which credential to use. To do this, run the login.azure and login.ado commands.

To create the credentials, you need an Azure Service Principal and a Azure DevOps Personal Access Token.

These documents will guide you in creating the credentials

Logon credentials are stored locally and expire after 2 hours.

The PAT is also stored in the Azure Function settings: whoever has access to the Resource Group can read it!

The 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. Permission on existing Resource Group If you go this route, remember add the --resourceGroup to all commands requiring an instance, otherwise the instance parameter adds an aggregator- prefixe to find the Resource Group.

Usage

Download and unzip the latest CLI.zip file from Releases. It requires .Net Core 2.1. To run Aggregator use dotnet aggregator-cli.dll followed by the verb and the options.

Verbs

Verb Use
logon.azure Logon into Azure.
logon.ado Logon into Azure DevOps.
list.instances Lists Aggregator instances.
install.instance Creates a new Aggregator instance in Azure.
uninstall.instance Destroy an Aggregator instance in Azure.
configure.instance Configures an existing Aggregator instance.
list.rules List the rule in existing Aggregator instance in Azure.
add.rule Add a rule to existing Aggregator instance in Azure.
remove.rule Remove a rule from existing Aggregator instance in Azure.
configure.rule Change a rule configuration.
update.rule Update a rule code and/or runtime.
invoke.rule Executes a rule locally or in an existing Aggregator instance.
list.mappings Lists mappings from existing Azure DevOps Projects to Aggregator Rules.
map.rule Maps an Aggregator Rule to existing Azure DevOps Projects.
unmap.rule Unmaps an Aggregator Rule from a Azure DevOps Project.
help Display more information on a specific command.
version Display version information.

You can see a few Command examples in Sample Aggregator CLI usage, see also Manual Tests.

Rule language

See Rule Language for a list of objects and properties to use. For examples see Rule Examples.

Troubleshooting

View live Aggregator log messages

In Azure Portal, open the Resource Group hosting the Instance (aggregator- followed by name of instance). Open the App Service hosting the Instance (instance name followed by aggregator). Switch to the Platform features tab and click on Log streaming like in the picture. Log streaming