From adf9e42a0d0bf6a979a4fc8393c4d0a41eede96b Mon Sep 17 00:00:00 2001 From: Michele Cereda Date: Wed, 4 Feb 2026 01:04:51 +0100 Subject: [PATCH] docs(gitlab): tldr tokens --- knowledge base/gitlab/README.md | 41 +++++++++++++++++++++++++++------ 1 file changed, 34 insertions(+), 7 deletions(-) diff --git a/knowledge base/gitlab/README.md b/knowledge base/gitlab/README.md index 1de8181..d25f262 100644 --- a/knowledge base/gitlab/README.md +++ b/knowledge base/gitlab/README.md @@ -7,7 +7,7 @@ 1. [Helm chart](#helm-chart) 1. [Operator](#operator) 1. [Create resources in GitLab using Pulumi](#create-resources-in-gitlab-using-pulumi) -1. [Forking](#forking) +1. [Forking projects](#forking-projects) 1. [Repository management](#repository-management) 1. [Different owners for parts of the code base](#different-owners-for-parts-of-the-code-base) 1. [Get the version of the helper image to use for a runner](#get-the-version-of-the-helper-image-to-use-for-a-runner) @@ -31,9 +31,33 @@ ## TL;DR -Using `-H 'PRIVATE-TOKEN: glpat-m-…'` in API calls is the same as using `-H 'Authorization: bearer glpat-m-…'`. +_Projects_ contain a code repository, collaborative tools, project management features, and CI/CD capabilities.
+They can be set to be available _publicly_, _internally_, or _privately_.
+GitLab does **not** limit the number of private projects one can create. -Use _deploy tokens_ instead of personal access tokens to access repositories in pipelines as they do not expire. +_Personal Access Tokens_ (PATs) are **an user**'s alternative to OAuth2 to authenticate: + +- With GitLab's API. +- With Git, using HTTP Basic Authentication. + +One authenticates with a PAT in place of one's password.
+Usernames are _required_, but **not** evaluated when authenticating with PATs.
+Refer [Personal access tokens]. + +_Project access tokens_ are similar to PATs, but they limit access to **their project's** resources, are granted a +limited role, and require an expiration date.
+Refer [Project access tokens]. + +_Group access tokens_ are similar to PATs and project access tokens, but they relate to **a group** instead.
+They **cannot** be used to create other group, project, or personal access tokens.
+Refer [Group access tokens]. + +_Deploy tokens_ allow accessing resources **without** tying permissions to individual user accounts, and do **not** +expire.
+Consider using those in place of PATs for git-related operations, container registries, package registries, and +repositories from pipelines. + +Using `-H 'PRIVATE-TOKEN: glpat-m-…'` in API calls is the same as using `-H 'Authorization: bearer glpat-m-…'`. ```sh # List the current application settings of the GitLab instance. @@ -41,7 +65,6 @@ curl -H 'PRIVATE-TOKEN: glpat-m-…' 'https://gitlab.fqdn/api/v4/application/set # Enable maintenance mode. curl -X 'PUT' -H 'PRIVATE-TOKEN: glpat-m-…' 'https://gitlab.fqdn/api/v4/application/settings?maintenance_mode=true' - # Disable maintenance mode. curl -X 'PUT' -H 'PRIVATE-TOKEN: glpat-m-…' 'https://gitlab.fqdn/api/v4/application/settings?maintenance_mode=false' @@ -50,8 +73,8 @@ curl -fsSL -H 'PRIVATE-TOKEN: glpat-something' 'https://gitlab.fqdn/api/v4/users | jq '.[]|{"name":.name,"username":.username,"state":.state,"locked":.locked}' - ``` -GitLab uses [GitLab Flavored Markdown (GLFM)] to render Markdown files in its UI.
-Since v17.10, one can use Alerts to highlight or call attention to something in GitHub-like fashion. +GitLab uses [GitLab Flavored Markdown (GLFM)] to render Markdown files in its web UI.
+Since v17.10, one can use [Alerts][glfm alerts] to highlight or call attention to something in GitHub-like fashion. ## Setup @@ -586,7 +609,7 @@ Refer Pulumi's [GitLab provider installation & configuration] and [GitLab provid export GITLAB_TOKEN='glpat-m-Va…zy' ``` -## Forking +## Forking projects Refer [Forks]. @@ -1097,7 +1120,9 @@ Refer [Invalid login or password]. [GitLab Flavored Markdown (GLFM)]: https://docs.gitlab.com/user/markdown/ [gitlab ha scaling runner vending machine for aws ec2 asg]: https://gitlab.com/guided-explorations/aws/gitlab-runner-autoscaling-aws-asg#gitlab-runners-on-aws-spot-best-practices [gitlab maintenance mode]: https://docs.gitlab.com/ee/administration/maintenance_mode/ +[GLFM alerts]: https://docs.gitlab.com/user/markdown/#alerts [global settings]: https://docs.gitlab.com/charts/charts/globals.html +[Group access tokens]: https://docs.gitlab.com/user/group/settings/group_access_tokens/ [how to restart gitlab]: https://docs.gitlab.com/ee/administration/restart_gitlab.html [icons]: https://gitlab-org.gitlab.io/gitlab-svgs/ [install gitlab with the linux package]: https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/master/doc/installation/index.md @@ -1110,6 +1135,8 @@ Refer [Invalid login or password]. [operator guide]: https://docs.gitlab.com/operator/ [package configuration file template]: https://gitlab.com/gitlab-org/omnibus-gitlab/-/raw/master/files/gitlab-config-template/gitlab.rb.template [Password authentication enabled]: https://gitlab.com/help/administration/settings/sign_in_restrictions.md#password-authentication-enabled +[Personal access tokens]: https://docs.gitlab.com/user/profile/personal_access_tokens/ +[Project access tokens]: https://docs.gitlab.com/user/project/settings/project_access_tokens/ [Python SDK]: https://github.com/python-gitlab/python-gitlab [reset a user's password]: https://docs.gitlab.com/security/reset_user_password/ [restore gitlab]: https://docs.gitlab.com/ee/administration/backup_restore/restore_gitlab.html