Skip to main content
Version: Release 23.3

Manage Release Folder Permissions in YAML

You can specify and maintain team permissions for Release folders in YAML, enabling you to manage this aspect of your Release configuration "as code".

To get started, you can use the XL CLI to generate YAML that reflects the permissions configured for a specific Templates folder in Release.

To help you make the visual correlation for how folder permissions are expressed in the UI and how they are expressed in YAML, this topic provides a working example in which you will use the xl generate command to:

  1. Export the permissions for a Template folder to YAML
  2. Review the resulting YAML
  3. Modify the YAML and reapply it to Release
  4. Review the resulting configuration in the UI

Before you begin​

Familiarize yourself with how permissions work at both the global and release team and folder levels in Release:

Prepare the scenario​

This scenario requires that you configure some new roles, a new template folder, and a new release team.

Create roles​

Create the following roles with at least one user in each role:

  • Developers
  • Managers
  • Sysadmin

For details, see Configure roles. You will apply these roles to a release team later in the scenario.

Create an empty folder​

Create a folder called MyFolder in Release. Leave the folder empty of any templates, as this example is intended to demonstrate the permissions-related information that is generated.

Create a custom team​

Create a custom team called My Team. This team will have specific permissions to My Folder.

  1. Click MyFolder and select the Teams & Permissions tab.
  2. Add the following roles you created earlier to the team:
  • Developers
  • Managers
  • Sysadmin
note

In a running Release instance, you should have roles and users that comprise them already defined. You can then add these roles to teams to coordinate permissions at the folder level.

Give folder permissions to the team​

Give My Team these specific permissions:

  • Abort release
  • Create release

Export folder permissions to YAML​

You can generate the YAML for your folder permissions and then compare the configuration between the Release UI and the resulting YAML.

Generate YAML​

In the YAML results, you should expect to see the folder, the team and specific permissions that you applied to the folder:

  • A custom team called My Team
  • Specific permissions given to My Team for the Abort release and Create release actions.

Generate a YAML file called export.yaml:

xl generate -s xl-release -p MyFolder -v -f export.yaml

Review the resulting YAML file​

You can now compare the folder permissions in the UI and the resulting export.yaml file.

Open the YAML file​

Open export.yaml:

---
apiVersion: xl-release/v1
kind: Permissions
spec:
- directory: MyFolder
  teams:
  - name: My Team
    roles:
    - Developers
    - Managers
    - Sysadmin
    permissions:
    - template#create_release
    - release#abort

Note that:

  • The MyFolder folder is specified with permissions for My Team which consists of the roles, Developers, Managers, and Sysadmin.
  • The template#create_release and release#abort permissions reflect the specific permissions given to My Team for the Abort release and Create release actions.

About the default release teams​

It is important to note that remainder of the YAML that is generated is related to the built-in folder permissions given to built-in teams that exist in Release:

  • Folder owner
  • Release admin
  • Template owner
- name: Template Owner
  users:
  - admin
  permissions:
  - template#edit
  - trigger#view_trigger
  - template#lock_task
  - template#view
  - folder#view
  - template#edit_precondition
  - template#edit_security
  - template#create_release
  - template#edit_failure_handler
- name: Release Admin
  users:
  - admin
  permissions:
  - release#edit_precondition
  - release#edit
  - release#reassign_task
  - release#edit_security
  - release#view
  - release#lock_task
  - release#start
  - release#edit_blackout
  - release#edit_failure_handler
  - folder#view
  - release#abort
  - release#edit_task
- name: Folder Owner
  users:
  - admin
  permissions:
  - group#edit
  - folder#edit_configuration
  - folder#view
  - dashboard#edit
  - folder#edit_security
  - folder#edit
  - dashboard#view
  - group#view
important

As these teams are built-in, do not change these default team names in YAML and use the xl apply command to apply them back to Release, as this action will result in errors.

Modify the YAML and apply to Release​

To complete this scenario, you can modify the generated YAML and use the xl apply command to apply it back to Release. This will modify My Folder and you can review the changes in the UI.

Add a new team​

Add a second team called My Second Team to the YAML specification, adding only the Developers role to this team:

---
apiVersion: xl-release/v1
kind: Permissions
spec:
- directory: MyFolder
  teams:
  - name: My Team
    roles:
    - Developers
    - Managers
    - Sysadmin
  - name: My Second Team
    roles:
    - Developers
    users:
    - admin
    permissions:
    - template#create_release
    - release#abort

Give the new team permissions on additional actions​

Give My Second Team permissions to perform two additional actions:

  • Edit dashboard (dashboard#edit)
  • Edit folder (folder#edit)
tip

Refer to the permissions listed for the default teams (Folder owner, Release admin, and Template owner) for the YAML syntax for specific permissions.

---
apiVersion: xl-release/v1
kind: Permissions
spec:
- directory: MyFolder
  teams:
  - name: My Team
    roles:
    - Developers
    - Managers
    - Sysadmin
    users:
    - admin
    permissions:
    - template#create_release
    - release#abort
  - name: My Second Team
    roles:
    - Developers
    users:
    - admin
    permissions:
    - template#create_release
    - release#abort
    - dashboard#edit
    - folder#edit

Save the export.yaml file.

Apply the revised YAML file to Release​

Use the xl apply command to apply the revised export.yaml file to Release. The expected results are:

  • A new team called My Second Team is created
  • My Second Team includes only the Developers role
  • My Second Team has two additional permissions that My Team did not have (Edit dashboard and Edit folder)
  • Permissions for My Team and the built-in teams are unchanged

Apply the revised file:

xl apply -f export.yaml -v

Review the results in the Release UI​

Navigate to Folders > MyFolder > Teams and Permissions.

Note that My Second Team is created and has permissions to perform additional actions.