Managing access for toolchains in resource groups

Toolchains that you create in your account might not be visible to other users by default. Access to toolchains in resource groups for users in your account is controlled by IBM Cloud Identity and Access Management (IAM). You can assign access to new users and existing users in your account.

User access for Continuous Delivery service instances is managed separately. For more information about managing user access to Continuous Delivery service instances in resource groups, see Managing user access to Continuous Delivery with Identity and Access Management.

Every user that accesses toolchains in your account must be assigned an IAM access policy. The policy determines which toolchains the user can access and what actions the user is allowed to take.

Policies enable access to be granted at different levels or scopes, including, but not limited to:

Access across all toolchains in your account
Access across all toolchains in a resource group in your account
Access to a specific toolchain in your account

After you define the scope of the access policy, you assign a role. The role defines which actions the user is allowed to take. The following table lists the IAM platform access roles and the available toolchain actions for each role.

IAM platform roles
Platform Role	Description of Actions	Example Actions
Viewer	View toolchains and delivery pipelines.	Click a toolchain to open its Overview page.
Operator	View toolchains and delivery pipelines. Run delivery pipelines. Send client bespoke toolchain events.	Click a toolchain to open its Overview page. Click the Run Stage icon of the stage that your pipeline job is in. Invoke the POST /toolchains/{toolchain_id}/events API.
Editor, Administrator	Create, view, update, and delete toolchains and delivery pipelines. Run delivery pipelines. Send client bespoke toolchain events.	From the IBM Cloud console, click the Menu icon > Platform Automation > Toolchains. On the Toolchains page, click Create a Toolchain. From the IBM Cloud console, click the Menu icon > Platform Automation > Toolchains. On the Toolchains page, click the toolchain to delete. Click the Actions menu, then select Delete. From the IBM Cloud console, click the Menu icon > Platform Automation > Toolchains. On the Toolchains page, click the toolchain to open its Overview page. Click Add tool, and then select the tool integration that you want to add. From the IBM Cloud console, click the Menu icon > Platform Automation. On the Pipeline page, click the Stage Configuration icon, and then click Configure Stage. Click the Run Stage icon of the stage that your pipeline job is in. Invoke the POST /toolchains/{toolchain_id}/events API.

The following table lists the IAM service access roles and the available actions for each role.

IAM service access roles
Service Role	Description of Actions	Example Actions
EventSender	Send client bespoke toolchain events.	Invoke the POST /toolchains/{toolchain_id}/events API.
PipelineRunner	Run delivery pipelines.	Click the Run Stage icon of the stage that your pipeline job is in.

EventSender access grants only the ability to send client bespoke toolchain events. To take other actions against a toolchain, other roles such as Viewer, Operator, Editor, or Administrator are required.

PipelineRunner access grants only the ability to run a delivery pipeline. To view a pipeline from the UI, an extra role such as the Viewer role is required.

The following table lists and describes the available actions for toolchains:

Service actions and operations
Action	Operation on Service	Role
resource-controller.instance.create	Create a toolchain in a resource group.	Administrator, Editor
resource-controller.instance.update	Update a toolchain or a tool integration that is bound to a toolchain in a resource group. For example, rename the toolchain. Change delivery pipelines that are bound to toolchains in a resource group.	Administrator, Editor
resource-controller.instance.update_plan	Not applicable.	Administrator, Editor
resource-controller.instance.delete	Delete a toolchain from a resource group.	Administrator, Editor
resource-controller.instance.retrieve	View the details for a toolchain or for a tool integration that is bound to a toolchain in a resource group.	Administrator, Editor, Operator, Viewer
toolchain.event.send	Send a client bespoke toolchain event.	Administrator, Editor, EventSender, Operator
toolchain.instance.create-bindings	Add a tool integration to a toolchain in a resource group.	Administrator, Editor
toolchain.instance.delete-bindings	Remove a tool integration from a toolchain in a resource group.	Administrator, Editor
toolchain.instance.read-properties	Reserved for future use.	Administrator, Editor, Viewer
toolchain.instance.update-properties	Reserved for future use.	Administrator, Editor
toolchain.pipeline-run.create	Run a delivery pipeline.	Administrator, Editor, Operator, PipelineRunner

Assigning access to new users

You can assign a new user access to all of the toolchains in your resource group.

From the IBM Cloud console, click Manage > Access (IAM), and select Users.
Click Invite users.
Specify the email address of the user that you want to invite.
In the How do you want to assign access? section, click Access Policy.
Choose to assign access to the Toolchain service.
Scope the access to Specific resources. Select the Resource group attribute type and enter a resource group.
In the Resource group access section, select Viewer (or higher) access to provide the user with access to view toolchain service instances from the platform, perform platform actions that are required to configure and operate toolchain service instances, and assign access policies to other users.
In the Roles and actions section, select the Editor role to provide the user with access to create, view, edit, or delete the toolchain service from resource groups. Select the Viewer role to provide the user with access to view toolchains only. Select both the Viewer and PipelineRunner roles to provide the user with access to view toolchains or to run delivery pipelines.
Click Add.
Click Invite.

Depending on their role, the new user can now work with all of the toolchains within the specified resource groups. They can add tool integrations and modify and run pipelines.

Assigning access to existing users

You can assign an existing user access to a toolchain in your resource group.

From the menu bar, click Manage > Access (IAM), and select Users.
From the row for the user that you want to assign access, select the Actions menu.
Click Assign access.
In the How do you want to assign access? section, click Access Policy.
Choose to assign access to the Toolchain service.
Scope the access to Specific resources. Select the Resource group attribute type and enter a resource group.
In the Resource group access section, select Viewer (or higher) access to provide the user with access to view toolchain service instances from the platform, perform platform actions that are required to configure and operate toolchain service instances, and assign access policies to other users.
In the Roles and actions section, select the Editor role to provide the user with access to create, view, edit, or delete the toolchain service from resource groups. Select the Viewer role to provide the user with access to view toolchains only. Select both the Viewer and PipelineRunner roles to provide the user with access to view toolchains or to run delivery pipelines.
Click Add.
Click Assign.

Depending on their role, the user can now work with all of the toolchains within the specified resource group. They can add tool integrations and modify and run pipelines.

Although the most common and flexible methods for granting user access are described here, IAM supports other methods, such as by resource or resource type, or by resource group. For more information about how to assign users access to resources, such as toolchains, see Managing access to resources.