Merge branch 'weimeng-master-patch-10785' into 'master'

Documentation: Programatically creating a personal access token

Closes #213255, gitlab-com/support/toolbox/snippets#24, and gitlab-com/support/toolbox/snippets#25

See merge request gitlab-org/gitlab!28520

doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md

@@ -380,39 +380,6 @@ user = User.find_by_username ''
 user.skip_reconfirmation!
 ```
 
-### Get an admin token
-
-```ruby
-# Get the first admin's first access token (no longer works on 11.9+. see: https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22743)
-User.where(admin:true).first.personal_access_tokens.first.token
-
-# Get the first admin's private token (no longer works on 10.2+)
-User.where(admin:true).private_token
-```
-
-### Create personal access token
-
-```ruby
-personal_access_token = User.find(123).personal_access_tokens.create(
-  name: 'apitoken',
-  impersonation: false,
-  scopes: [:api]
-)
-
-puts personal_access_token.token
-```
-
-You might also want to manually set the token string:
-
-```ruby
-User.find(123).personal_access_tokens.create(
-  name: 'apitoken',
-  token_digest: Gitlab::CryptoHelper.sha256('some-token-string-here'),
-  impersonation: false,
-  scopes: [:api]
-)
-```
-
 ### Active users & Historical users
 
 ```ruby

doc/user/profile/personal_access_tokens.md

@@ -56,6 +56,58 @@ the following table.
 | `read_repository`  | [GitLab 10.7](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17894)  | Allows read-only access (pull) to the repository through `git clone`. |
 | `write_repository` | [GitLab 11.11](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26021) | Allows read-write access (pull, push) to the repository through `git clone`. Required for accessing Git repositories over HTTP when 2FA is enabled. |
 
+## Programmatically creating a personal access token
+
+You can programmatically create a predetermined personal access token for use in
+automation or tests. You will need sufficient access to run a
+[Rails console session](../../administration/troubleshooting/debug.md#starting-a-rails-console-session)
+for your GitLab instance.
+
+To create a token belonging to a user with username `automation-bot`, run the
+following in the Rails console (`sudo gitlab-rails console`):
+
+```ruby
+user = User.find_by_username('automation-bot')
+token = user.personal_access_tokens.create(scopes: [:read_user, :read_repository], name: 'Automation token')
+token.set_token('token-string-here123')
+token.save!
+```
+
+This can be shortened into a single-line shell command using the
+[GitLab Rails Runner](../../administration/troubleshooting/debug.md#using-the-rails-runner):
+
+```shell
+sudo gitlab-rails runner "token = User.find_by_username('automation-bot').personal_access_tokens.create(scopes: [:read_user, :read_repository], name: 'Automation token'); token.set_token('token-string-here123'); token.save!"
+```
+
+NOTE: **Note:**
+The token string must be 20 characters in length, or it will not be
+recognized as a personal access token.
+
+The list of valid scopes and what they do can be found
+[in the source code](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/auth.rb).
+
+## Programmatically revoking a personal access token
+
+You can programmatically revoke a personal access token. You will need
+sufficient access to run a [Rails console session](../../administration/troubleshooting/debug.md#starting-a-rails-console-session)
+for your GitLab instance.
+
+To revoke a known token `token-string-here123`, run the following in the Rails
+console (`sudo gitlab-rails console`):
+
+```ruby
+token = PersonalAccessToken.find_by_token('token-string-here123')
+token.revoke!
+```
+
+This can be shorted into a single-line shell command using the
+[GitLab Rails Runner](../../administration/troubleshooting/debug.md#using-the-rails-runner):
+
+```shell
+sudo gitlab-rails runner "PersonalAccessToken.find_by_token('token-string-here123').revoke!"
+```
+
 <!-- ## Troubleshooting
 
 Include any troubleshooting steps that you can foresee. If you know beforehand what issues