Generate custom abilities documentation

- auto generate custom roles abilities doc using rake task

config/feature_flags/development/manage_project_access_tokens.yml

@@ -6,3 +6,4 @@ milestone: '16.5'
 type: development
 group: group::authorization
 default_enabled: false
+feature_flag: manage_project_access_tokens

doc/api/graphql/reference/index.md

@@ -30857,11 +30857,11 @@ Member role permission.
 | Value | Description |
 | ----- | ----------- |
-| <a id="memberrolepermissionadmin_group_member"></a>`ADMIN_GROUP_MEMBER` | Allows to admin group members. |
-| <a id="memberrolepermissionadmin_merge_request"></a>`ADMIN_MERGE_REQUEST` | Allows to approve merge requests. |
+| <a id="memberrolepermissionadmin_group_member"></a>`ADMIN_GROUP_MEMBER` | Allows admin of group members. |
+| <a id="memberrolepermissionadmin_merge_request"></a>`ADMIN_MERGE_REQUEST` | Allows approval of merge requests. |
 | <a id="memberrolepermissionadmin_terraform_state"></a>`ADMIN_TERRAFORM_STATE` | Allows to admin terraform state. |
 | <a id="memberrolepermissionadmin_vulnerability"></a>`ADMIN_VULNERABILITY` | Allows admin access to the vulnerability reports. |
-| <a id="memberrolepermissionarchive_project"></a>`ARCHIVE_PROJECT` | Allows to archive projects. |
+| <a id="memberrolepermissionarchive_project"></a>`ARCHIVE_PROJECT` | Allows archiving of projects. |
 | <a id="memberrolepermissionmanage_group_access_tokens"></a>`MANAGE_GROUP_ACCESS_TOKENS` | Allows manage access to the group access tokens. |
 | <a id="memberrolepermissionmanage_project_access_tokens"></a>`MANAGE_PROJECT_ACCESS_TOKENS` | Allows manage access to the project access tokens. |
 | <a id="memberrolepermissionread_code"></a>`READ_CODE` | Allows read-only access to the source code. |

doc/development/permissions/custom_roles.md

@@ -169,7 +169,7 @@ For example, you see in `GroupPolicy` that there is an ability called
 than adding a row to the `member_roles` table for each ability, consider
 renaming them to `read_security_dashboard` and adding `read_security_dashboard`
 to the `member_roles` table. This is more expected because it means that
-enabling `read_security_dashboard` on the parent group will enable the custom
+enabling `read_security_dashboard` on the parent group will enable the custom role.
 For example, `GroupPolicy` has an ability called `read_group_security_dashboard` and `ProjectPolicy` has an ability
 called `read_project_security_dashboard`. If you would like to make both customizable, rather than adding a row to the
 `member_roles` table for each ability, consider renaming them to `read_security_dashboard` and adding
@@ -185,7 +185,9 @@ To add a new ability to a custom role:
 - Generate YAML file by running `./ee/bin/custom-ability` generator
 - Add a new column to `member_roles` table, either manually or by running `custom_roles:code`  generator, eg. by running `rails generate gitlab:custom_roles:code --ability new_ability_name`. The ability parameter is case sensitive and has to exactly match the permission name from the YAML file.
 - Add the ability to the respective Policy for example in [this change in merge request 114734](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114734/diffs#diff-content-edcbe28bdecbd848d4d9efdc5b5e9bddd2a7299e).
-- Update the specs. Don't forget to add a spec to `ee/spec/requests/custom_roles` - the spec template file was generated if you used the code generator
+- Update the specs. Don't forget to add a spec to `ee/spec/requests/custom_roles` - the spec template file was pre-generated if you used the code generator
+- Compile the documentation by running `bundle exec rake gitlab:custom_roles:compile_docs`
+- Update the GraphQL documentation by running `bundle exec rake gitlab:graphql:compile_docs`
 
 Examples of merge requests adding new abilities to custom roles:
 
@@ -193,9 +195,15 @@ Examples of merge requests adding new abilities to custom roles:
 - [Read vulnerability](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114734)
 - [Admin vulnerability](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121534)
 
-The above merge request don't use YAML files and code generators. Some of the changes are not needed anymore. We will update the documentation once we have a permission implemented using the generators.
+The above merge requests don't use YAML files and code generators. Some of the changes are not needed anymore. We will update the documentation once we have a permission implemented using the generators.
 
-You should make sure a new custom roles ability is under a feature flag.
+If you have any concerns, put the new ability behind a feature flag.
+
+#### Documenting handling the feature flag
+
+- When you introduce a new custom ability under a feature flag, add the `feature_flag` attribute to the appropriate ability YAML file.
+- When you enable the ability by default, add the `feature_flag_enabled_milestone` and `feature_flag_enabled_mr` attributes to the appropriate ability YAML file and regenerate the documentation.
+- You do not have to include these attributes in the YAML file if the feature flag is enabled by default in the same release as the ability is introduced.
 
 ## Custom abilities definition
 

doc/user/custom_roles/abilities.md

 ---
 stage: Govern
 group: Authorization
-info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
+info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments"
 ---
 
+<!---
+  This documentation is auto generated by a Rake task.
+
+  Please do not edit this file directly. To update this file, run:
+  bundle exec rake gitlab:custom_roles:compile_docs
+
+  To make changes to the output of the Rake task,
+  edit `tooling/custom_roles/docs/templates/custom_abilities.md.erb`.
+--->
+
 # Available custom abilities
 
 The following abilities are available. You can add these abilities in any combination
@@ -13,15 +23,43 @@ Some abilities require having other abilities enabled first. For example, admini
 
 These requirements are documented in the `Required ability` column in the following table.
 
-| Ability                      | Version                | Required ability  | Description |
-| ------------------------------- | -----------------------| -------------------- | ----------- |
-| `read_code`                     | [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106256) in GitLab 15.7 [with a flag](../../administration/feature_flags.md) named `customizable_roles`. [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114524) in GitLab 15.10.| Not applicable       | View project code. Does not include the ability to pull code.  |
-| `read_vulnerability`            | [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10160) in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `custom_roles_vulnerability`. [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124049) in GitLab 16.2. | Not applicable       | View [vulnerability reports](../application_security/vulnerability_report/index.md).  |
-| `admin_vulnerability`           | [Introduced in GitLab 16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/412536).  | `read_vulnerability` | Change the [status of vulnerabilities](../application_security/vulnerabilities/index.md#vulnerability-status-values).  |
-| `read_dependency`               | [Introduced in GitLab 16.3](https://gitlab.com/gitlab-org/gitlab/-/issues/415255).  | Not applicable       | View [project dependencies](../application_security/dependency_list/index.md).  |
-| `admin_merge_request`           | [Introduced in GitLab 16.4](https://gitlab.com/gitlab-org/gitlab/-/issues/412708).  | Not applicable       | View and approve [merge requests](../project/merge_requests/index.md), revoke merge request approval, and view the associated merge request code. <br> Does not allow users to view or change merge request approval rules.  |
-| `manage_project_access_tokens`  | [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/421778) in GitLab 16.5 [with a flag](../../administration/feature_flags.md) named `manage_project_access_tokens`  | Not applicable       | Create, delete, and list [project access tokens](../project/settings/project_access_tokens.md).  |
-| `admin_group_member`            | [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17364) in GitLab 16.5  | Not applicable       | Add or remove [group members](../group/manage.md).  |
-| `archive_project`               | [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/425957) in GitLab 16.7  | Not applicable       | [Archive and unarchive projects](../project/settings/migrate_projects.md#archive-a-project).  |
-| `remove_project`                | [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/425959) in GitLab 16.8  | Not applicable       | [Delete projects](../project/working_with_projects.md#delete-a-project).  |
-| `manage_group_access_tokens`    | [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/428353) in GitLab 16.8  | Not applicable       | [Create, delete, and list group access tokens](../group/settings/group_access_tokens.md).  |
+## Code review workflow
+
+| Name | Required permission | Description | Introduced in | Feature flag | Enabled in |
+|:-----|:------------|:------------------|:---------|:--------------|:---------|
+| [`admin_merge_request`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128302) |  | Allows approval of merge requests. | GitLab [16.4](https://gitlab.com/gitlab-org/gitlab/-/issues/412708) |  |  |
+| [`read_code`](https://gitlab.com/gitlab-org/gitlab/-/issues/376180) |  | Allows read-only access to the source code. | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/20277) | `customizable_roles` | GitLab [15.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110810) |
+
+## Group and projects
+
+| Name | Required permission | Description | Introduced in | Feature flag | Enabled in |
+|:-----|:------------|:------------------|:---------|:--------------|:---------|
+| [`admin_group_member`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131914) |  | Allows admin of group members. | GitLab [16.5](https://gitlab.com/gitlab-org/gitlab/-/issues/17364) | `admin_group_member` | GitLab [16.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136247) |
+
+## Groups and projects
+
+| Name | Required permission | Description | Introduced in | Feature flag | Enabled in |
+|:-----|:------------|:------------------|:---------|:--------------|:---------|
+| [`archive_project`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/134998) |  | Allows archiving of projects. | GitLab [16.6](https://gitlab.com/gitlab-org/gitlab/-/issues/425957) | `archive_project` | GitLab [16.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/139260) |
+| [`remove_project`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/139696) |  | Allows deletion of projects. | GitLab [16.8](https://gitlab.com/gitlab-org/gitlab/-/issues/425959) |  |  |
+
+## Infrastructure as code
+
+| Name | Required permission | Description | Introduced in | Feature flag | Enabled in |
+|:-----|:------------|:------------------|:---------|:--------------|:---------|
+| [`admin_terraform_state`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/140759) |  | Allows to admin terraform state | GitLab [16.8](https://gitlab.com/gitlab-org/gitlab/-/issues/421789) |  |  |
+
+## System access
+
+| Name | Required permission | Description | Introduced in | Feature flag | Enabled in |
+|:-----|:------------|:------------------|:---------|:--------------|:---------|
+| [`manage_group_access_tokens`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/140115) |  | Allows manage access to the group access tokens. | GitLab [16.8](https://gitlab.com/gitlab-org/gitlab/-/issues/428353) |  |  |
+| [`manage_project_access_tokens`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132342) |  | Allows manage access to the project access tokens. | GitLab [16.5](https://gitlab.com/gitlab-org/gitlab/-/issues/421778) | `manage_project_access_tokens` | GitLab [16.8](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/141294) |
+
+## Vulnerability management
+
+| Name | Required permission | Description | Introduced in | Feature flag | Enabled in |
+|:-----|:------------|:------------------|:---------|:--------------|:---------|
+| [`admin_vulnerability`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121534) | read_vulnerability | Allows admin access to the vulnerability reports. | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/412536) |  |  |
+| [`read_dependency`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/126247) |  | Allows read-only access to the dependencies. | GitLab [16.3](https://gitlab.com/gitlab-org/gitlab/-/issues/415255) |  |  |
+| [`read_vulnerability`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120704) |  | Allows read-only access to the vulnerability reports. | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/399119) |  |  |

ee/config/custom_abilities/admin_group_member.yml

 ---
 name: admin_group_member
-description: Allows to admin group members.
+description: Allows admin of group members.
 introduced_by_issue: https://gitlab.com/gitlab-org/gitlab/-/issues/17364
 introduced_by_mr: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131914
 feature_category: group_and_projects
 milestone: '16.5'
 group_ability: true
 project_ability: false
+feature_flag: admin_group_member
+feature_flag_enabled_milestone: '16.6'
+feature_flag_enabled_mr: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136247

ee/config/custom_abilities/admin_merge_request.yml

 ---
 name: admin_merge_request
-description: Allows to approve merge requests
+description: Allows approval of merge requests.
 introduced_by_issue: https://gitlab.com/gitlab-org/gitlab/-/issues/412708
 introduced_by_mr: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128302
 feature_category: code_review_workflow

ee/config/custom_abilities/archive_project.yml

 ---
 name: archive_project
-description: Allows to archive projects.
+description: Allows archiving of projects.
 introduced_by_issue: https://gitlab.com/gitlab-org/gitlab/-/issues/425957
 introduced_by_mr: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/134998
 feature_category: groups_and_projects
 milestone: '16.6'
 group_ability: false
 project_ability: true
+feature_flag: archive_project
+feature_flag_enabled_milestone: '16.7'
+feature_flag_enabled_mr: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/139260

ee/config/custom_abilities/manage_project_access_tokens.yml

@@ -7,3 +7,6 @@ feature_category: system_access
 milestone: '16.5'
 group_ability: false
 project_ability: true
+feature_flag: manage_project_access_tokens
+feature_flag_enabled_milestone: '16.8'
+feature_flag_enabled_mr: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/141294

ee/config/custom_abilities/read_code.yml

@@ -8,3 +8,6 @@ milestone: '15.7'
 group_ability: false
 project_ability: true
 skip_seat_consumption: true
+feature_flag: customizable_roles
+feature_flag_enabled_milestone: '15.9'
+feature_flag_enabled_mr: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110810

ee/lib/tasks/gitlab/custom_roles/compile_docs_task.rb

+# frozen_string_literal: true
+
+module Tasks
+  module Gitlab
+    module CustomRoles
+      class CompileDocsTask
+        def initialize(docs_dir, docs_path, template_erb_path)
+          @custom_roles_dir = docs_dir
+          @custom_roles_doc_file = docs_path
+          @custom_roles_template = ERB.new(File.read(template_erb_path), trim_mode: '<>')
+        end
+
+        def run
+          FileUtils.mkdir_p(@custom_roles_dir)
+          File.write(@custom_roles_doc_file, @custom_roles_template.result)
+
+          puts "Documentation compiled."
+        end
+      end
+    end
+  end
+end

ee/lib/tasks/gitlab/custom_roles/custom_roles.rake

+# frozen_string_literal: true
+
+return if Rails.env.production?
+
+namespace :gitlab do
+  namespace :custom_roles do
+    custom_roles_dir = Rails.root.join("doc/user/custom_roles")
+    custom_roles_doc_file = Rails.root.join(custom_roles_dir, 'abilities.md')
+    template_directory = 'tooling/custom_roles/docs/templates/'
+    template_erb_file_path = Rails.root.join(template_directory, 'custom_abilities.md.erb')
+
+    desc 'GitLab | Custom Roles | Compile custom abilities documentation'
+    task compile_docs: :environment do
+      require_relative './compile_docs_task'
+
+      Tasks::Gitlab::CustomRoles::CompileDocsTask
+        .new(custom_roles_dir, custom_roles_doc_file, template_erb_file_path).run
+    end
+  end
+end

ee/spec/tasks/gitlab/custom_roles/compile_docs_task_spec.rb

+# frozen_string_literal: true
+
+require 'spec_helper'
+require_relative '../../../../lib/tasks/gitlab/custom_roles/compile_docs_task'
+
+RSpec.describe Tasks::Gitlab::CustomRoles::CompileDocsTask, feature_category: :permissions do
+  let(:docs_dir) { Rails.root.join("tmp/tests/doc/administration/custom_roles") }
+  let(:docs_path) { Rails.root.join(docs_dir, 'abilities.md') }
+  let(:template_erb_path) { Rails.root.join("tooling/custom_roles/docs/templates/custom_abilities.md.erb") }
+
+  subject(:compile_docs_task) { described_class.new(docs_dir, docs_path, template_erb_path) }
+
+  describe '#run' do
+    it 'outputs message after compiling the documentation' do
+      expect { compile_docs_task.run }.to output("Documentation compiled.\n").to_stdout
+    end
+
+    it 'creates abilities.md', :aggregate_failures do
+      FileUtils.rm_f(docs_path)
+
+      expect { File.read(docs_path) }.to raise_error(Errno::ENOENT)
+
+      compile_docs_task.run
+
+      expect(File.read(docs_path).size).not_to eq(0)
+      expect(File.read(docs_path)).to match(/This documentation is auto generated by a Rake task/)
+    end
+  end
+end

ee/spec/tasks/gitlab/custom_roles/custom_roles_rake_spec.rb

+# frozen_string_literal: true
+
+require 'spec_helper'
+require_relative '../../../../lib/tasks/gitlab/custom_roles/compile_docs_task'
+
+RSpec.describe 'gitlab:custom_roles rake tasks', :silence_stdout, feature_category: :permissions do
+  before do
+    Rake.application.rake_require('tasks/gitlab/custom_roles/custom_roles')
+    stub_env('VERBOSE' => 'true')
+  end
+
+  describe 'compile_docs' do
+    it 'invokes Gitlab::CustomRoles::CompileDocsTask with correct arguments' do
+      compile_docs_task = instance_double(Tasks::Gitlab::CustomRoles::CompileDocsTask)
+
+      expect(Tasks::Gitlab::CustomRoles::CompileDocsTask).to receive(:new).with(
+        Rails.root.join("doc/user/custom_roles"),
+        Rails.root.join("doc/user/custom_roles/abilities.md"),
+        Rails.root.join("tooling/custom_roles/docs/templates/custom_abilities.md.erb")).and_return(compile_docs_task)
+
+      expect(compile_docs_task).to receive(:run)
+
+      run_rake_task('gitlab:custom_roles:compile_docs')
+    end
+  end
+end

tooling/custom_roles/docs/templates/custom_abilities.md.erb

+<% custom_abilities_by_feature_category = MemberRole.all_customizable_permissions.group_by { |_k, definition| definition[:feature_category] } %>
+<% def humanize(feature_category) %>
+<%   case feature_category %>
+<%   when 'mlops' %>
+<%     "MLOps" %>
+<%   when 'not_owned' %>
+<%     "Not categorized" %>
+<%   else %>
+<%     "#{feature_category.humanize}" %>
+<%   end %>
+<% end %>
+<% def enabled_link(ability) %>
+<%   return unless ability[:feature_flag_enabled_milestone] || ability[:feature_flag_enabled_mr] %>
+<%   return "GitLab #{ability[:feature_flag_enabled_milestone]}" unless ability[:feature_flag_enabled_mr] %>
+<%   "GitLab [#{ability[:feature_flag_enabled_milestone]}](#{ability[:feature_flag_enabled_mr]})" %>
+<% end %>
+<% def feature_flag(ability) %>
+<%   return unless ability[:feature_flag] %>
+<%   "`#{ability[:feature_flag]}`" %>
+<% end %>
+---
+stage: Govern
+group: Authorization
+info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments"
+---
+
+<!---
+  This documentation is auto generated by a Rake task.
+
+  Please do not edit this file directly. To update this file, run:
+  bundle exec rake gitlab:custom_roles:compile_docs
+
+  To make changes to the output of the Rake task,
+  edit `tooling/custom_roles/docs/templates/custom_abilities.md.erb`.
+--->
+
+# Available custom abilities
+
+The following abilities are available. You can add these abilities in any combination
+to a base role to create a custom role.
+
+Some abilities require having other abilities enabled first. For example, administration of vulnerabilities (`admin_vulnerability`) can only be enabled if reading vulnerabilities (`read_vulnerability`) is also enabled.
+
+These requirements are documented in the `Required ability` column in the following table.
+<% custom_abilities_by_feature_category.sort.each do |category, abilities| %>
+
+## <%= "#{humanize(category)}" %>
+
+| Name | Required permission | Description | Introduced in | Feature flag | Enabled in |
+|:-----|:------------|:------------------|:---------|:--------------|:---------|
+<% abilities.each do |name, ability| %>
+| <%= "[`#{name}`](#{ability[:introduced_by_mr]})" %> | <%= ability[:requirement] %> | <%= ability[:description] %> | GitLab <%= "[#{ability[:milestone]}](#{ability[:introduced_by_issue]})" %> | <%= feature_flag(ability) %> | <%= enabled_link(ability) %> |
+<% end %>
+<% end %>