Teams, Roles and Permissions Management

Teams, Roles and Permissions Management

Matt Fellows

As you scale your microservice architecture, grow your engineering team and increase your adoption of contract testing, you start to run into certain challenges that weren't present when you first started out.

Take for instance our PactFlow demo account; there are 518 applications and 247 contracts (integrations) covered by pact tests.

Dashboard for our demo PactFlow account

Most of the time, you're only interested in a subset of applications or integrations at any given moment, usually related to a project or team that you work in. Having to wade through hundreds of integrations each time can be a bit of a pain, and the pact filter can be used to reduce that noise. It would be better, however, to only see integrations related to your current team or project by default.

More importantly, if you're relying on PactFlow to gate your releases with our can-i-deploy feature, you don't want an accident where somebody in another team is able to change something, such as deleting a contract. In fact, this happened recently where I was removing an test integration point before a demo - but instead deleted a real one resulting in this unhappy exchange:

Allowing anybody to delete things means bad things can happen (but at least our audit trail showed what happened 🤦‍♂️)

In many cases, this can be easily resolved by simply re-publishing any contracts - but it's not always that easy, and it would be better to not allow it to happen in the first place!

Let's talk about how we can address these issues with new features in PactFlow.


Teams are a way to organise applications and people into logical groupings, and can be used in conjunction with roles to apply permissions that are scoped to a team context. By default, all users and applications are assigned to the Default team, and inherit permissions (see below) that enable users to perform common tasks like publishing and tagging a contract.

Example team summary view

Administrators can create or delete teams, and assign users and applications to them:

Creating a Team

TeamAwesome currently has 6 users associated with it:

Assigning users to a Team

Once you're in a team, you'll see a drop-down box in the top left-hand corner where you can select your default team view. This will filter the integrations shown on your dashboard, de-cluttering the noise (note: the team selected is "PactFlow Demos" and only 5 pacts are shown in the panel):

Team filtered home page view

Read more about our teams feature.

Roles and Permissions

Grouping resources into Teams is useful, but it becomes much more powerful when combined with our team scoped, role based access model, allowing you to specify who can do what across our platform.

The Test Maintainer (default) role applies write and delete permissions according to team membership.

For example, users who are assigned this role belonging to Team A can publish, tag and delete contracts for applications assigned to Team A, but cannot for applications that are not.

Administrators however, have globally scoped permissions that enable them to operate across the entire platform.

PactFlow ships with a set of predefined Roles which cover off the key use cases for most customers - such as for CI usage and developer read-only access. However, you can create your own Role that combines any of the Permissions to suit your needs.

Let's talk about the most common setup.

Example: Team based access

Let's walk through an example with 2 teams, 3 applications and 3 users, one of whom is the platform administrator. Here is our team setup:

Team Applications Users
A Foo, Bar Sally
B Bar, Baz Billy

Our users have the following roles and team assignments. The final "Access Rights" column shows which applications each User is able to manage based on the policy:

User Team Role Access Rights
Sally A Test Maintainer Foo, Bar
Billy B Test Maintainer Bar, Baz
Kevin - Administrator All

Shown on a Venn diagram, the application of permissions can be better understood:

Permissions venn diagram

The actions of Sally and Billy are scoped to the applications of their respective teams, however Kevin - an Administrator - is able to operate on any part of the platform.

If Sally was to attempt to publish a contract for application Baz, she would receive an error like the following (or 403 error code from the API):

Failed to tag versions due to error: PactBroker::Client::Error - Authorization failed (insufficient permissions): Forbidden. Either you are using a read only token for a request that requires a write token (the most likely cause), or you do not have the required permissions.
One or more pacts failed to be published
Permissions failure publishing to a contract managed by a different team

To help you get started with teams quickly, every new PactFlow account is set up with a special, system defined Default team. All new users and applications are automatically added to this team on creation and are assigned the Test Maintainer role.

For secure setups, you may wish to remove the default team and explicitly add team members into user-defined teams, to prevent them from being able to impact existing teams. Read more about the default team.

Example: Bulk operations

Remember my blunder from above? Well, this problem can also be solved with Roles and/or Teams.

If I wasn't assigned to a team that managed the application I deleted, and I wasn't an Administrator (specifically, if I lacked the contract_data:bulk_delete:* permission), I would not have been able to delete the integration - the UI even helpfully tells me why:

Non-administrators can't delete everything by default

This makes complete sense - the application I removed was not something I should have had any access to in the first place, let alone delete, and now that is possible.

Using these features

The complete set of features - teams, roles and permissions - is available to all customers on Enterprise plans. Customers on a free Starter plan or paid Team plan have access to the team function only.

These extensions to our administration functionality completes the foundational work of our security model, further supporting our goal of enabling large, distributed teams to work side by side securely within our platform, whilst operating at speed.

arrow-up icon