Valid since:
XL Release 8.6.0
XL Deploy 8.6.0
XL JetPack 8.6.0

You can specify and maintain team permissions for XL Release folders in YAML, enabling you to manage this aspect of your XL 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 XL 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 XL 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 XL 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

New roles

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 XL Release. Leave the folder empty of any templates, as this example is intended to demonstrate the permissions-related information that is generated.

MyFolder

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 XL 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

My Team Permissions

Export folder permissions to YAML

You can generate the YAML for your folder permissions and then compare the configuration between the XL 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 XL Release:

  • Folder owner
  • Release admin
  • Template owner
- name: Template Owner
  users:
  - admin
  permissions:
  - template#edit
  - template#lock_task
  - template#view
  - folder#view
  - template#edit_triggers
  - 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 XL Release, as this action will result in errors.

Modify the YAML and apply to XL Release

To complete this scenario, you can modify the generated YAML and use the xl apply command to apply it back to XL 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 XL Release

Use the xl apply command to apply the revised export.yaml file to XL 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 XL Release UI

Navigate to Folders > MyFolder > Teams and Permissions.

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

My Team Permissions