From 20fb9f4de9b79c36f592a9ebf98a7f80ba1cab2d Mon Sep 17 00:00:00 2001
From: Joe Randazzo <jrandazzo@gitlab.com>
Date: Fri, 28 Feb 2025 19:52:48 +0000
Subject: [PATCH] Add experiment instructions
---
doc/ci/jobs/ci_job_token.md | 4 ++
doc/ci/jobs/fine_grained_permissions.md | 37 ++++++++++++++++++-
.../templates/fine_grained_permissions.md.erb | 37 ++++++++++++++++++-
3 files changed, 74 insertions(+), 4 deletions(-)
diff --git a/doc/ci/jobs/ci_job_token.md b/doc/ci/jobs/ci_job_token.md
index b540ebb4d167e..f7388bdb32097 100644
--- a/doc/ci/jobs/ci_job_token.md
+++ b/doc/ci/jobs/ci_job_token.md
@@ -380,6 +380,10 @@ cannot push to the repository in your project.
You can also control this setting with the [`ci_push_repository_for_job_token_allowed`](../../api/projects.md#edit-a-project)
parameter in the `projects` REST API endpoint.
+## Fine-grained permissions for job tokens
+
+Fine-grained permissions for job tokens are an [experiment](../../policy/development_stages_support.md#experiment). For information on this feature and the available resources, see [Fine-grained permissions for CI/CD job tokens](fine_grained_permissions.md). Feedback is welcome on this [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/519575).
+
## Use a job token
### To `git clone` a private project's repository
diff --git a/doc/ci/jobs/fine_grained_permissions.md b/doc/ci/jobs/fine_grained_permissions.md
index 3c05388797865..92d858e2c6e9f 100644
--- a/doc/ci/jobs/fine_grained_permissions.md
+++ b/doc/ci/jobs/fine_grained_permissions.md
@@ -1,6 +1,6 @@
---
stage: Software Supply Chain Security
-group: Pipeline Security
+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
title: Fine-grained permissions for CI/CD job tokens
---
@@ -23,10 +23,43 @@ Status: Experiment
{{< /details >}}
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/15234) in GitLab 17.10. This feature is an [experiment](../../policy/development_stages_support.md#experiment).
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
+
+The availability of this feature is controlled by a feature flag.
+For more information, see the history.
+This feature is available for testing, but not ready for production use.
+
+{{< /alert >}}
+
+You can use fine-grained permissions to explicitly allow access to a limited set of API endpoints.
+These permissions are applied to the CI/CD job tokens in a specified project.
+This feature is an [experiment](../../policy/development_stages_support.md#experiment).
+
+## Enable fine-grained permissions
+
+### On GitLab Self-Managed
+
+1. Start the GitLab Rails console. For information, see [Enable and disable GitLab features deployed behind feature flags](../../administration/feature_flags.md#enable-or-disable-the-feature)
+1. Turn on the [feature flag](../../administration/feature_flags.md):
+
+```ruby
+# You must include a specific project ID with this command.
+Feature.enable(:add_policies_to_ci_job_token, <project_id>)
+```
+
+### On GitLab.com
+
+Add a comment on this [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/519575) with your project ID.
+
## Available API endpoints
The following endpoints are available for CI/CD job tokens.
-You can use fine-grained permissions to explicitly allow access to a limited set of the following API endpoints.
`None` means fine-grained permissions cannot control access to this endpoint.
diff --git a/tooling/ci/job_tokens/docs/templates/fine_grained_permissions.md.erb b/tooling/ci/job_tokens/docs/templates/fine_grained_permissions.md.erb
index d1bf8cd3c0bdf..bea36f2d88322 100644
--- a/tooling/ci/job_tokens/docs/templates/fine_grained_permissions.md.erb
+++ b/tooling/ci/job_tokens/docs/templates/fine_grained_permissions.md.erb
@@ -1,6 +1,6 @@
---
stage: Software Supply Chain Security
-group: Pipeline Security
+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
title: Fine-grained permissions for CI/CD job tokens
---
@@ -23,10 +23,43 @@ Status: Experiment
{{< /details >}}
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/15234) in GitLab 17.10. This feature is an [experiment](../../policy/development_stages_support.md#experiment).
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
+
+The availability of this feature is controlled by a feature flag.
+For more information, see the history.
+This feature is available for testing, but not ready for production use.
+
+{{< /alert >}}
+
+You can use fine-grained permissions to explicitly allow access to a limited set of API endpoints.
+These permissions are applied to the CI/CD job tokens in a specified project.
+This feature is an [experiment](../../policy/development_stages_support.md#experiment).
+
+## Enable fine-grained permissions
+
+### On GitLab Self-Managed
+
+1. Start the GitLab Rails console. For information, see [Enable and disable GitLab features deployed behind feature flags](../../administration/feature_flags.md#enable-or-disable-the-feature)
+1. Turn on the [feature flag](../../administration/feature_flags.md):
+
+```ruby
+# You must include a specific project ID with this command.
+Feature.enable(:add_policies_to_ci_job_token, <project_id>)
+```
+
+### On GitLab.com
+
+Add a comment on this [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/519575) with your project ID.
+
## Available API endpoints
The following endpoints are available for CI/CD job tokens.
-You can use fine-grained permissions to explicitly allow access to a limited set of the following API endpoints.
`None` means fine-grained permissions cannot control access to this endpoint.
--
GitLab