Pipeline task

CharterApply@1 applies a Charter configuration exported from the Charter hub (Download JSON) from a pipeline, using the same code as the Charter hub's Save. It is part of the Charter extension, so there is nothing extra to install. It needs a Charter licence; the trial doesn't cover it.

steps:
  - task: CharterApply@1
    inputs:
      configurationFile: charter/CHARTER_Config.json

Which account the task runs as

The task calls Azure DevOps with the pipeline's job token, so it acts as the pipeline's build identity:

• Project Collection Build Service (organisation) — the usual identity, and the one these instructions assume.
• {Project} Build Service (organisation) — used instead when Limit job authorization scope to current project is on (in the organisation's or the project's Pipelines settings). That token is limited to its own project, so turn the setting off for the project the Charter pipeline runs in. New organisations have it on by default. (Whether that identity can edit processes with the rights below is untested; these instructions assume the setting is off.)

That account needs the rights below. Azure DevOps has no custom roles, so all three options work with security groups. Options 1 and 2 use one organisation-level group, Charter Apply, with the build service as its only member, and Grant-CharterApplyPermissions.ps1 sets either of them up.

Which option

Choose by what the configuration contains. All three options were tested end to end with a configuration covering a work item type, a web hook in every project, an environment check in every project and a service connection check:

• Process management and web hooks only: option 1. It's the recommended setup.
• Checks, or anything outside the pipeline's own project: option 3. Pipelines refuse to change checks on environments and service connections in other projects for options 1 and 2, even though the group has the Administrator role there.
• Without option 3: use the pipeline for processes and web hooks, and apply checks from the Charter hub, which runs as you.

Some rights only exist per project (service hooks, project membership), so with options 1 and 2 a project created later isn't covered until it's granted too: run the script again. Option 3 covers new projects automatically.

Option 1: a group in each project's Project Administrators (recommended)

The Charter Apply group gets Edit process for the organisation and becomes a member of Project Administrators in each project. That covers processes, work item types, web hooks, and checks in the project the pipeline runs in. The build service can't change organisation settings, other processes' permissions, or projects it isn't added to.

With the script:

$env:AZURE_DEVOPS_PAT = "<token>"   # Full access; run as a Project Collection Administrator
./Grant-CharterApplyPermissions.ps1 -Organization <organisation> -WhatIf   # shows what it would do
./Grant-CharterApplyPermissions.ps1 -Organization <organisation>           # all projects
./Grant-CharterApplyPermissions.ps1 -Organization <organisation> -Project Web, Api

By hand:

1. Organisation settings › Permissions › New group: Charter Apply. Under Members, add Project Collection Build Service (organisation).
2. Same page, the group's Permissions › Boards › Edit process: Allow.
3. In each project: Project settings › Permissions › Project Administrators › Members › add Charter Apply.

Option 2: least privilege

The same group, but instead of Project Administrators it gets only the permissions below. It covers processes, work item types and web hooks. Checks aren't covered: with these rights the pipeline is refused on both environment and service connection checks.

./Grant-CharterApplyPermissions.ps1 -Organization <organisation> -Mode LeastPrivilege

What it grants, and where to do it by hand:

The script still grants the Administrator roles, so that the group is ready if Azure DevOps changes how it treats pipeline tokens; remove those two lines from the script if you'd rather not.

Not needed: Create process, Delete process, Delete field from organization and Administer process permissions. The task never creates or deletes a process, and never deletes a field: a field left out of the configuration is only taken off the form.

To limit it to some processes, leave Edit process unset at organisation level and set it per process (Organisation settings › Boards › Process › process › … › Security), and remove step 3 from the script.

Option 3: Project Collection Administrators

Add Project Collection Build Service (organisation) to Project Collection Administrators (Organisation settings › Permissions). One step, new projects are covered, and it's the only option that applies checks in every project. The cost: every pipeline in the organisation that runs as this identity can then do anything an administrator can. Use it in an organisation where only administrators can edit pipelines, or protect the Charter pipeline with branch policies and approvals so nobody can change what it runs.

About the script

Download Grant-CharterApplyPermissions.ps1. It needs PowerShell 7 and a personal access token with the Full access scope, from a Project Collection Administrator: group, membership and permission changes have no narrower scope. It's meant to be safe to run again (it reuses the group and adds to existing permissions), and supports -WhatIf and -Confirm. It's meant to be read and adapted; each step is a short block with a comment.

Licence

Nothing to set up per pipeline. The task reads the licence key the Charter hub stored when it was activated, and checks it the same way the Charter hub does. It needs a Standard or Pro licence; the trial doesn't cover it. Without a licence, or with a Standard licence in an organisation over 20 projects, the task stops before changing anything.

See online subscriptions for the plans.