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:
- Export the permissions for a Template folder to YAML
- Review the resulting YAML
- Modify the YAML and reapply it to Release
- Review the resulting configuration in the UI
Familiarize yourself with how permissions work at both the global and release team and folder levels in Release:
This scenario requires that you configure some new roles, a new template folder, and a new release team.
Create the following roles with at least one user in each role:
For details, see Configure roles. You will apply these roles to a release team later in the scenario.
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 called My Team. This team will have specific permissions to My Folder.
- Click MyFolder and select the Teams & Permissions tab.
- Add the following roles you created earlier to the team:
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 My Team these specific permissions:
- Abort release
- Create release
You can generate the YAML for your folder permissions and then compare the configuration between the Release UI and the resulting 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
xl generate -s xl-release -p MyFolder -v -f export.yaml
You can now compare the folder permissions in the UI and the resulting
--- apiVersion: xl-release/v1 kind: Permissions spec: - directory: MyFolder teams: - name: My Team roles: - Developers - Managers - Sysadmin permissions: - template#create_release - release#abort
- The MyFolder folder is specified with permissions for My Team which consists of the roles, Developers, Managers, and Sysadmin.
release#abortpermissions reflect the specific permissions given to My Team for the Abort release and Create release actions.
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.
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 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 My Second Team permissions to perform two additional actions:
- Edit dashboard (
- Edit folder (
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
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
Navigate to Folders > MyFolder > Teams and Permissions.
Note that My Second Team is created and has permissions to perform additional actions.