Document Rake task to show/edit token expirations

This documents the Rake task added in
https://gitlab.com/gitlab-org/gitlab/-/merge_requests/157855.

Relates to https://gitlab.com/gitlab-org/gitlab/-/issues/467416

config/vite.gdk.json

+{
+  "enabled": true,
+  "host": "127.0.0.1",
+  "port": 3038,
+  "hmr": {
+    "clientPort": 3443,
+    "host": "gdk.test",
+    "protocol": "wss"
+  }
+}

doc/administration/raketasks/tokens/index.md

+---
+stage: Govern
+group: Authentication
+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
+---
+
+# Access token Rake tasks
+
+DETAILS:
+**Tier:** Free, Premium, Ultimate
+**Offering:** Self-managed
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467416) in GitLab 17.2.
+
+## Analyze token expiration dates
+
+GitLab provides a Rake task that analyzes personal, project, and group access tokens and
+displays the top ten most common expiration dates. In GitLab 16.0, a [background migration](https://gitlab.com/gitlab-org/gitlab/-/issues/369123) assigned
+an expiration date of one year after an access token was created. This tool helps
+identify which tokens might have been affected by this migration.
+
+To see the breakdown, run:
+
+   ::Tabs
+
+   :::TabTitle Linux package (Omnibus)
+
+   ```shell
+   gitlab-rake gitlab:tokens:analyze
+   ```
+
+   :::TabTitle Helm chart (Kubernetes)
+
+   ```shell
+   # Find the toolbox pod
+   kubectl --namespace <namespace> get pods -lapp=toolbox
+   kubectl exec -it <toolbox-pod-name> -- sh -c 'cd /srv/gitlab && bin/rake gitlab:tokens:analyze'
+   ```
+
+   :::TabTitle Docker
+
+   ```shell
+   sudo docker exec -it <container_name> /bin/bash
+   gitlab-rake gitlab:tokens:analyze
+   ```
+
+   :::TabTitle Self-compiled (source)
+
+   ```shell
+   sudo RAILS_ENV=production -u git -H bundle exec rake gitlab:tokens:analyze
+   ```
+
+   ::EndTabs
+
+This task analyzes all the access tokens and groups them by expiration date.
+The left column shows the expiration date, and the right shows how many tokens
+have that expiration date. Example output:
+
+```plaintext
+======= Personal/Project/Group Access Token Expiration Migration =======
+Started at: 2023-06-15 10:20:35 +0000
+Finished  : 2023-06-15 10:23:01 +0000
+===== Top 10 Personal/Project/Group Access Token Expiration Dates =====
+| Expiration Date | Count |
+|-----------------|-------|
+| 2024-06-15      | 1565353 |
+| 2017-12-31      | 2508  |
+| 2018-01-01      | 1008  |
+| 2016-12-31      | 833   |
+| 2017-08-31      | 705   |
+| 2017-06-30      | 596   |
+| 2018-12-31      | 548   |
+| 2017-05-31      | 523   |
+| 2017-09-30      | 520   |
+| 2017-07-31      | 494   |
+========================================================================
+```
+
+In this example, you can see that over 1.5 million access tokens have an
+expiration date of 2024-06-15, one year after the migration was run
+on 2023-06-15. This suggests that most of these tokens were assigned by
+the migration. However, there is no way to know for sure whether other
+tokens were created manually with the same date.
+
+## Update expiration dates in bulk
+
+GitLab provides another Rake task that allows an administrator to extend
+or remove expiration dates from token in bulk. This tool requires an
+interactive terminal.
+
+1. Run the tool:
+
+   ::Tabs
+
+   :::TabTitle Linux package (Omnibus)
+
+   ```shell
+   gitlab-rake gitlab:tokens:edit
+   ```
+
+   :::TabTitle Helm chart (Kubernetes)
+
+   ```shell
+   # Find the toolbox pod
+   kubectl --namespace <namespace> get pods -lapp=toolbox
+   kubectl exec -it <toolbox-pod-name> -- sh -c 'cd /srv/gitlab && bin/rake gitlab:tokens:edit'
+   ```
+
+   :::TabTitle Docker
+
+   ```shell
+   sudo docker exec -it <container_name> /bin/bash
+   gitlab-rake gitlab:tokens:edit
+   ```
+
+   :::TabTitle Self-compiled (source)
+
+   ```shell
+   sudo RAILS_ENV=production -u git -H bundle exec rake gitlab:tokens:edit
+   ```
+
+   ::EndTabs
+
+   After the tool starts, it shows the output from the analyze step
+   described above plus an additional prompt about modifying the expiration
+   dates:
+
+   ```plaintext
+   ======= Personal/Project/Group Access Token Expiration Migration =======
+   Started at: 2023-06-15 10:20:35 +0000
+   Finished  : 2023-06-15 10:23:01 +0000
+   ===== Top 10 Personal/Project/Group Access Token Expiration Dates =====
+   | Expiration Date | Count |
+   |-----------------|-------|
+   | 2024-05-14      | 1565353 |
+   | 2017-12-31      | 2508  |
+   | 2018-01-01      | 1008  |
+   | 2016-12-31      | 833   |
+   | 2017-08-31      | 705   |
+   | 2017-06-30      | 596   |
+   | 2018-12-31      | 548   |
+   | 2017-05-31      | 523   |
+   | 2017-09-30      | 520   |
+   | 2017-07-31      | 494   |
+   ========================================================================
+   What do you want to do? (Press ↑/↓ arrow or 1-3 number to move and Enter to select)
+   ‣ 1. Extend expiration date
+     2. Remove expiration date
+     3. Quit
+   ```
+
+### Extend expiration dates
+
+To extend expirations dates on all tokens matching a given expiration date:
+
+1. Select option 1, `Extend expiration date`:
+
+   ```plaintext
+   What do you want to do?
+   ‣ 1. Extend expiration date
+     2. Remove expiration date
+     3. Quit
+   ```
+
+1. Tthe tool asks you to select one of the expiration dates listed. For example:
+
+   ```plaintext
+   Select an expiration date (Press ↑/↓/←/→ arrow to move and Enter to select)
+   ‣ 2024-05-14
+     2017-12-31
+     2018-01-01
+     2016-12-31
+     2017-08-31
+     2017-06-30
+   ```
+
+   Use the arrow keys on your keyboard to select a date. To abort,
+   scroll all the way down and select `--> Abort`. Press <kbd>Enter</kbd> to confirm
+   your selection:
+
+   ```plaintext
+   Select an expiration date
+     2017-06-30
+     2018-12-31
+     2017-05-31
+     2017-09-30
+     2017-07-31
+   ‣ --> Abort
+   ```
+
+   If you select a date, the tool prompts you for a new expiration date:
+
+   ```plaintext
+   What would you like the new expiration date to be? (2025-05-14) 2024-05-14
+   ```
+
+   The default is one year from the selected date. Press <kbd>Enter</kbd>
+   to use the default, or manually type in a date in `YYYY-MM-DD` format.
+
+1. After you have entered a valid date, the tool asks one more time for confirmation:
+
+   ```plaintext
+   Old expiration date: 2024-05-14
+   New expiration date: 2025-05-14
+   WARNING: This will now update 1565353 token(s). Are you sure? (y/N)
+   ```
+
+   If you enter `y`, the tool proceeds to extend the expiration date
+   for all the tokens with the selected expiration date.
+
+   If you enter `N`, the tool aborts the update task and return to the
+   original analyze output.
+
+### Remove expiration dates
+
+To remove expiration dates on all tokens matching
+a given expiration date:
+
+1. Select option 2, `Remove expiration date`:
+
+   ```plaintext
+   What do you want to do?
+     1. Extend expiration date
+   ‣ 2. Remove expiration date
+     3. Quit
+   ```
+
+1. The tool asks you to select the expiration date from the table. For example:
+
+   ```plaintext
+   Select an expiration date (Press ↑/↓/←/→ arrow to move and Enter to select)
+   ‣ 2024-05-14
+     2017-12-31
+     2018-01-01
+     2016-12-31
+     2017-08-31
+     2017-06-30
+   ```
+
+   Use the arrow keys on your keyboard to select a date. To abort,
+   scroll all the way down and select `--> Abort`. Press <kbd>Enter</kbd> to confirm
+   your selection:
+
+   ```plaintext
+   Select an expiration date
+     2017-06-30
+     2018-12-31
+     2017-05-31
+     2017-09-30
+     2017-07-31
+   ‣ --> Abort
+   ```
+
+1. After selecting a date, the tool prompts you to confirm the selection:
+
+   ```plaintext
+   WARNING: This will remove the expiration for tokens that expire on 2024-05-14.
+   This will affect 1565353 tokens. Are you sure? (y/N)
+   ```
+
+   If you enter `y`, the tool removes the expiration date for all the
+   tokens with the selected expiration date.
+
+   If you enter `N`, the tool aborts the update task and returns to the first menu.

doc/raketasks/index.md

@@ -20,6 +20,7 @@ The following Rake tasks are available for use with GitLab:
 | Tasks                                                 | Description |
 |:------------------------------------------------------|:------------|
+| [Access token expiration tasks](../administration/raketasks/tokens/index.md)  | Bulk extend or remove expiration dates for access tokens. |
 | [Back up and restore](../administration/backup_restore/index.md)              | Back up, restore, and migrate GitLab instances between servers. |
 | [Clean up](cleanup.md)                                | Clean up unneeded items from GitLab instances. |
 | [Development](../development/rake_tasks.md)           | Tasks for GitLab contributors. |