Add docs for personal access tokens
This commit is contained in:
parent
578f460674
commit
8fb33b8f01
|
@ -3,7 +3,7 @@
|
||||||
>**Note:**
|
>**Note:**
|
||||||
>
|
>
|
||||||
> - [Introduced][ce-10308] in GitLab 9.1.
|
> - [Introduced][ce-10308] in GitLab 9.1.
|
||||||
> - You need a personal access token in order to retrieve and import GitHub
|
> - You need a personal access token in order to retrieve and import GitHub
|
||||||
> projects. You can get it from: https://github.com/settings/tokens
|
> projects. You can get it from: https://github.com/settings/tokens
|
||||||
> - You also need to pass an username as the second argument to the rake task
|
> - You also need to pass an username as the second argument to the rake task
|
||||||
> which will become the owner of the project.
|
> which will become the owner of the project.
|
||||||
|
@ -19,7 +19,7 @@ bundle exec rake import:github[access_token,root,foo/bar] RAILS_ENV=production
|
||||||
```
|
```
|
||||||
|
|
||||||
In this case, `access_token` is your GitHub personal access token, `root`
|
In this case, `access_token` is your GitHub personal access token, `root`
|
||||||
is your GitLab username, and `foo/bar` is the new GitLab namespace/project that
|
is your GitLab username, and `foo/bar` is the new GitLab namespace/project that
|
||||||
will get created from your GitHub project. Subgroups are also possible: `foo/foo/bar`.
|
will get created from your GitHub project. Subgroups are also possible: `foo/foo/bar`.
|
||||||
|
|
||||||
|
|
||||||
|
|
|
@ -55,6 +55,11 @@ following locations:
|
||||||
- [V3 to V4](v3_to_v4.md)
|
- [V3 to V4](v3_to_v4.md)
|
||||||
- [Version](version.md)
|
- [Version](version.md)
|
||||||
|
|
||||||
|
The following documentation is for the [internal CI API](ci/README.md):
|
||||||
|
|
||||||
|
- [Builds](ci/builds.md)
|
||||||
|
- [Runners](ci/runners.md)
|
||||||
|
|
||||||
## Road to GraphQL
|
## Road to GraphQL
|
||||||
|
|
||||||
Going forward, we will start on moving to
|
Going forward, we will start on moving to
|
||||||
|
@ -65,22 +70,20 @@ controller-specific endpoints. GraphQL has a number of benefits:
|
||||||
2. Callers of the API can request only what they need.
|
2. Callers of the API can request only what they need.
|
||||||
3. It is versioned by default.
|
3. It is versioned by default.
|
||||||
|
|
||||||
It will co-exist with the current V4 REST API. If we have a V5 API, this should be
|
It will co-exist with the current v4 REST API. If we have a v5 API, this should
|
||||||
compatability layer on top of GraphQL.
|
be a compatibility layer on top of GraphQL.
|
||||||
|
|
||||||
### Internal CI API
|
|
||||||
|
|
||||||
The following documentation is for the [internal CI API](ci/README.md):
|
|
||||||
|
|
||||||
- [Builds](ci/builds.md)
|
|
||||||
- [Runners](ci/runners.md)
|
|
||||||
|
|
||||||
## Authentication
|
## Authentication
|
||||||
|
|
||||||
Most API requests require authentication via a session cookie or token. For those cases where it is not required, this will be mentioned in the documentation
|
Most API requests require authentication via a session cookie or token. For
|
||||||
for each individual endpoint. For example, the [`/projects/:id` endpoint](projects.md).
|
those cases where it is not required, this will be mentioned in the documentation
|
||||||
There are three types of tokens available: private tokens, OAuth 2 tokens, and personal
|
for each individual endpoint. For example, the [`/projects/:id` endpoint](projects.md).
|
||||||
access tokens.
|
|
||||||
|
There are three types of access tokens available:
|
||||||
|
|
||||||
|
1. [OAuth2 tokens](#oauth2-tokens)
|
||||||
|
1. [Private tokens](#private-tokens)
|
||||||
|
1. [Personal access tokens](#personal-access-tokens)
|
||||||
|
|
||||||
If authentication information is invalid or omitted, an error message will be
|
If authentication information is invalid or omitted, an error message will be
|
||||||
returned with status code `401`:
|
returned with status code `401`:
|
||||||
|
@ -91,20 +94,13 @@ returned with status code `401`:
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### Session Cookie
|
### Session cookie
|
||||||
|
|
||||||
When signing in to GitLab as an ordinary user, a `_gitlab_session` cookie is
|
When signing in to GitLab as an ordinary user, a `_gitlab_session` cookie is
|
||||||
set. The API will use this cookie for authentication if it is present, but using
|
set. The API will use this cookie for authentication if it is present, but using
|
||||||
the API to generate a new session cookie is currently not supported.
|
the API to generate a new session cookie is currently not supported.
|
||||||
|
|
||||||
### Private Tokens
|
### OAuth2 tokens
|
||||||
|
|
||||||
You need to pass a `private_token` parameter via query string or header. If passed as a
|
|
||||||
header, the header name must be `PRIVATE-TOKEN` (uppercase and with a dash instead of
|
|
||||||
an underscore). You can find or reset your private token in your account page
|
|
||||||
(`/profile/account`).
|
|
||||||
|
|
||||||
### OAuth 2 Tokens
|
|
||||||
|
|
||||||
You can use an OAuth 2 token to authenticate with the API by passing it either in the
|
You can use an OAuth 2 token to authenticate with the API by passing it either in the
|
||||||
`access_token` parameter or in the `Authorization` header.
|
`access_token` parameter or in the `Authorization` header.
|
||||||
|
@ -117,30 +113,31 @@ curl --header "Authorization: Bearer OAUTH-TOKEN" https://gitlab.example.com/api
|
||||||
|
|
||||||
Read more about [GitLab as an OAuth2 client](oauth2.md).
|
Read more about [GitLab as an OAuth2 client](oauth2.md).
|
||||||
|
|
||||||
### Personal Access Tokens
|
### Private tokens
|
||||||
|
|
||||||
> [Introduced][ce-3749] in GitLab 8.8.
|
Private tokens provide full access to the GitLab API. Anyone with access to
|
||||||
|
them can interact with GitLab as if they were you. You can find or reset your
|
||||||
|
private token in your account page (`/profile/account`).
|
||||||
|
|
||||||
You can create as many personal access tokens as you like from your GitLab
|
For examples of usage, [read the basic usage section](#basic-usage).
|
||||||
profile (`/profile/personal_access_tokens`); perhaps one for each application
|
|
||||||
that needs access to the GitLab API.
|
### Personal access tokens
|
||||||
|
|
||||||
|
Instead of using your private token which grants full access to your account,
|
||||||
|
personal access tokens could be a better fit because of their granular
|
||||||
|
permissions.
|
||||||
|
|
||||||
Once you have your token, pass it to the API using either the `private_token`
|
Once you have your token, pass it to the API using either the `private_token`
|
||||||
parameter or the `PRIVATE-TOKEN` header.
|
parameter or the `PRIVATE-TOKEN` header. For examples of usage,
|
||||||
|
[read the basic usage section](#basic-usage).
|
||||||
|
|
||||||
> [Introduced][ce-5951] in GitLab 8.15.
|
[Read more about personal access tokens.][pat]
|
||||||
|
|
||||||
Personal Access Tokens can be created with one or more scopes that allow various actions
|
|
||||||
that a given token can perform. Although there are only two scopes available at the
|
|
||||||
moment – `read_user` and `api` – the groundwork has been laid to add more scopes easily.
|
|
||||||
|
|
||||||
At any time you can revoke any personal access token by just clicking **Revoke**.
|
|
||||||
|
|
||||||
### Impersonation tokens
|
### Impersonation tokens
|
||||||
|
|
||||||
> [Introduced][ce-9099] in GitLab 9.0. Needs admin permissions.
|
> [Introduced][ce-9099] in GitLab 9.0. Needs admin permissions.
|
||||||
|
|
||||||
Impersonation tokens are a type of [Personal Access Token](#personal-access-tokens)
|
Impersonation tokens are a type of [personal access token][pat]
|
||||||
that can only be created by an admin for a specific user.
|
that can only be created by an admin for a specific user.
|
||||||
|
|
||||||
They are a better alternative to using the user's password/private token
|
They are a better alternative to using the user's password/private token
|
||||||
|
@ -149,9 +146,11 @@ or private token, since the password/token can change over time. Impersonation
|
||||||
tokens are a great fit if you want to build applications or tools which
|
tokens are a great fit if you want to build applications or tools which
|
||||||
authenticate with the API as a specific user.
|
authenticate with the API as a specific user.
|
||||||
|
|
||||||
For more information about the usage please refer to the
|
For more information, refer to the
|
||||||
[users API](users.md#retrieve-user-impersonation-tokens) docs.
|
[users API](users.md#retrieve-user-impersonation-tokens) docs.
|
||||||
|
|
||||||
|
For examples of usage, [read the basic usage section](#basic-usage).
|
||||||
|
|
||||||
### Sudo
|
### Sudo
|
||||||
|
|
||||||
> Needs admin permissions.
|
> Needs admin permissions.
|
||||||
|
@ -204,11 +203,16 @@ GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=23
|
||||||
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "SUDO: 23" "https://gitlab.example.com/api/v4/projects"
|
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "SUDO: 23" "https://gitlab.example.com/api/v4/projects"
|
||||||
```
|
```
|
||||||
|
|
||||||
## Basic Usage
|
## Basic usage
|
||||||
|
|
||||||
API requests should be prefixed with `api` and the API version. The API version
|
API requests should be prefixed with `api` and the API version. The API version
|
||||||
is defined in [`lib/api.rb`][lib-api-url].
|
is defined in [`lib/api.rb`][lib-api-url].
|
||||||
|
|
||||||
|
For endpoints that require [authentication](#authentication), you need to pass
|
||||||
|
a `private_token` parameter via query string or header. If passed as a header,
|
||||||
|
the header name must be `PRIVATE-TOKEN` (uppercase and with a dash instead of
|
||||||
|
an underscore).
|
||||||
|
|
||||||
Example of a valid API request:
|
Example of a valid API request:
|
||||||
|
|
||||||
```
|
```
|
||||||
|
@ -221,6 +225,12 @@ Example of a valid API request using cURL and authentication via header:
|
||||||
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects"
|
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects"
|
||||||
```
|
```
|
||||||
|
|
||||||
|
Example of a valid API request using cURL and authentication via a query string:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
curl "https://gitlab.example.com/api/v4/projects?private_token=9koXpg98eAheJpvBs5tK"
|
||||||
|
```
|
||||||
|
|
||||||
The API uses JSON to serialize data. You don't need to specify `.json` at the
|
The API uses JSON to serialize data. You don't need to specify `.json` at the
|
||||||
end of an API URL.
|
end of an API URL.
|
||||||
|
|
||||||
|
@ -436,3 +446,4 @@ programming languages. Visit the [GitLab website] for a complete list.
|
||||||
[ce-3749]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3749
|
[ce-3749]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3749
|
||||||
[ce-5951]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5951
|
[ce-5951]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5951
|
||||||
[ce-9099]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9099
|
[ce-9099]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9099
|
||||||
|
[pat]: ../user/profile/personal_access_tokens.md
|
||||||
|
|
|
@ -134,4 +134,4 @@ access_token = client.password.get_token('user@example.com', 'secret')
|
||||||
puts access_token.token
|
puts access_token.token
|
||||||
```
|
```
|
||||||
|
|
||||||
[personal access tokens]: ./README.md#personal-access-tokens
|
[personal access tokens]: ../user/profile/personal_access_tokens.md
|
||||||
|
|
|
@ -1,11 +1,9 @@
|
||||||
# Session API
|
# Session API
|
||||||
|
|
||||||
## Deprecation Notice
|
>**Deprecation notice:**
|
||||||
|
Starting in GitLab 8.11, this feature has been **disabled** for users with
|
||||||
1. Starting in GitLab 8.11, this feature has been *disabled* for users with two-factor authentication turned on.
|
[two-factor authentication][2fa] turned on. These users can access the API
|
||||||
2. These users can access the API using [personal access tokens] instead.
|
using [personal access tokens] instead.
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
You can login with both GitLab and LDAP credentials in order to obtain the
|
You can login with both GitLab and LDAP credentials in order to obtain the
|
||||||
private token.
|
private token.
|
||||||
|
@ -52,4 +50,5 @@ Example response:
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
[personal access tokens]: ./README.md#personal-access-tokens
|
[2fa]: ../user/profile/account/two_factor_authentication.md
|
||||||
|
[personal access tokens]: ../user/profile/personal_access_tokens.md
|
||||||
|
|
|
@ -804,7 +804,7 @@ Example response:
|
||||||
|
|
||||||
It creates a new impersonation token. Note that only administrators can do this.
|
It creates a new impersonation token. Note that only administrators can do this.
|
||||||
You are only able to create impersonation tokens to impersonate the user and perform
|
You are only able to create impersonation tokens to impersonate the user and perform
|
||||||
both API calls and Git reads and writes. The user will not see these tokens in his profile
|
both API calls and Git reads and writes. The user will not see these tokens in their profile
|
||||||
settings page.
|
settings page.
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
|
@ -282,9 +282,9 @@ which can be avoided if a different driver is used, for example `overlay`.
|
||||||
|
|
||||||
> **Notes:**
|
> **Notes:**
|
||||||
- This feature requires GitLab 8.8 and GitLab Runner 1.2.
|
- This feature requires GitLab 8.8 and GitLab Runner 1.2.
|
||||||
- Starting from GitLab 8.12, if you have 2FA enabled in your account, you need
|
- Starting from GitLab 8.12, if you have [2FA] enabled in your account, you need
|
||||||
to pass a personal access token instead of your password in order to login to
|
to pass a [personal access token][pat] instead of your password in order to
|
||||||
GitLab's Container Registry.
|
login to GitLab's Container Registry.
|
||||||
|
|
||||||
Once you've built a Docker image, you can push it up to the built-in
|
Once you've built a Docker image, you can push it up to the built-in
|
||||||
[GitLab Container Registry](../../user/project/container_registry.md). For example,
|
[GitLab Container Registry](../../user/project/container_registry.md). For example,
|
||||||
|
@ -409,3 +409,5 @@ Some things you should be aware of when using the Container Registry:
|
||||||
|
|
||||||
[docker-in-docker]: https://blog.docker.com/2013/09/docker-can-now-run-within-docker/
|
[docker-in-docker]: https://blog.docker.com/2013/09/docker-can-now-run-within-docker/
|
||||||
[docker-cap]: https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities
|
[docker-cap]: https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities
|
||||||
|
[2fa]: ../../user/profile/account/two_factor_authentication.md
|
||||||
|
[pat]: ../../user/profile/personal_access_tokens.md
|
||||||
|
|
|
@ -125,23 +125,14 @@ applications and U2F devices.
|
||||||
## Personal access tokens
|
## Personal access tokens
|
||||||
|
|
||||||
When 2FA is enabled, you can no longer use your normal account password to
|
When 2FA is enabled, you can no longer use your normal account password to
|
||||||
authenticate with Git over HTTPS on the command line, you must use a personal
|
authenticate with Git over HTTPS on the command line or when using
|
||||||
access token instead.
|
[GitLab's API][api], you must use a [personal access token][pat] instead.
|
||||||
|
|
||||||
1. Log in to your GitLab account.
|
|
||||||
1. Go to your **Profile Settings**.
|
|
||||||
1. Go to **Access Tokens**.
|
|
||||||
1. Choose a name and expiry date for the token.
|
|
||||||
1. Click on **Create Personal Access Token**.
|
|
||||||
1. Save the personal access token somewhere safe.
|
|
||||||
|
|
||||||
When using Git over HTTPS on the command line, enter the personal access token
|
|
||||||
into the password field.
|
|
||||||
|
|
||||||
## Recovery options
|
## Recovery options
|
||||||
|
|
||||||
To disable two-factor authentication on your account (for example, if you
|
To disable two-factor authentication on your account (for example, if you
|
||||||
have lost your code generation device) you can:
|
have lost your code generation device) you can:
|
||||||
|
|
||||||
* [Use a saved recovery code](#use-a-saved-recovery-code)
|
* [Use a saved recovery code](#use-a-saved-recovery-code)
|
||||||
* [Generate new recovery codes using SSH](#generate-new-recovery-codes-using-ssh)
|
* [Generate new recovery codes using SSH](#generate-new-recovery-codes-using-ssh)
|
||||||
* [Ask a GitLab administrator to disable two-factor authentication on your account](#ask-a-gitlab-administrator-to-disable-two-factor-authentication-on-your-account)
|
* [Ask a GitLab administrator to disable two-factor authentication on your account](#ask-a-gitlab-administrator-to-disable-two-factor-authentication-on-your-account)
|
||||||
|
@ -154,8 +145,9 @@ codes. If you saved these codes, you can use one of them to sign in.
|
||||||
To use a recovery code, enter your username/email and password on the GitLab
|
To use a recovery code, enter your username/email and password on the GitLab
|
||||||
sign-in page. When prompted for a two-factor code, enter the recovery code.
|
sign-in page. When prompted for a two-factor code, enter the recovery code.
|
||||||
|
|
||||||
> **Note:** Once you use a recovery code, you cannot re-use it. You can still
|
>**Note:**
|
||||||
use the other recovery codes you saved.
|
Once you use a recovery code, you cannot re-use it. You can still use the other
|
||||||
|
recovery codes you saved.
|
||||||
|
|
||||||
### Generate new recovery codes using SSH
|
### Generate new recovery codes using SSH
|
||||||
|
|
||||||
|
@ -190,11 +182,14 @@ a new set of recovery codes with SSH.
|
||||||
two-factor code. Then, visit your Profile Settings and add a new device
|
two-factor code. Then, visit your Profile Settings and add a new device
|
||||||
so you do not lose access to your account again.
|
so you do not lose access to your account again.
|
||||||
```
|
```
|
||||||
3. Go to the GitLab sign-in page and enter your username/email and password. When prompted for a two-factor code, enter one of the recovery codes obtained
|
|
||||||
from the command-line output.
|
|
||||||
|
|
||||||
> **Note:** After signing in, visit your **Profile Settings -> Account** immediately to set up two-factor authentication with a new
|
3. Go to the GitLab sign-in page and enter your username/email and password.
|
||||||
device.
|
When prompted for a two-factor code, enter one of the recovery codes obtained
|
||||||
|
from the command-line output.
|
||||||
|
|
||||||
|
>**Note:**
|
||||||
|
After signing in, visit your **Profile settings > Account** immediately to set
|
||||||
|
up two-factor authentication with a new device.
|
||||||
|
|
||||||
### Ask a GitLab administrator to disable two-factor authentication on your account
|
### Ask a GitLab administrator to disable two-factor authentication on your account
|
||||||
|
|
||||||
|
@ -206,23 +201,23 @@ Sign in and re-enable two-factor authentication as soon as possible.
|
||||||
## Note to GitLab administrators
|
## Note to GitLab administrators
|
||||||
|
|
||||||
- You need to take special care to that 2FA keeps working after
|
- You need to take special care to that 2FA keeps working after
|
||||||
[restoring a GitLab backup](../../../raketasks/backup_restore.md).
|
[restoring a GitLab backup](../../../raketasks/backup_restore.md).
|
||||||
|
|
||||||
- To ensure 2FA authorizes correctly with TOTP server, you may want to ensure
|
- To ensure 2FA authorizes correctly with TOTP server, you may want to ensure
|
||||||
your GitLab server's time is synchronized via a service like NTP. Otherwise,
|
your GitLab server's time is synchronized via a service like NTP. Otherwise,
|
||||||
you may have cases where authorization always fails because of time differences.
|
you may have cases where authorization always fails because of time differences.
|
||||||
|
|
||||||
[Google Authenticator]: https://support.google.com/accounts/answer/1066447?hl=en
|
|
||||||
[FreeOTP]: https://freeotp.github.io/
|
|
||||||
[YubiKey]: https://www.yubico.com/products/yubikey-hardware/
|
|
||||||
|
|
||||||
- The GitLab U2F implementation does _not_ work when the GitLab instance is accessed from
|
- The GitLab U2F implementation does _not_ work when the GitLab instance is accessed from
|
||||||
multiple hostnames, or FQDNs. Each U2F registration is linked to the _current hostname_ at
|
multiple hostnames, or FQDNs. Each U2F registration is linked to the _current hostname_ at
|
||||||
the time of registration, and cannot be used for other hostnames/FQDNs.
|
the time of registration, and cannot be used for other hostnames/FQDNs.
|
||||||
|
|
||||||
For example, if a user is trying to access a GitLab instance from `first.host.xyz` and `second.host.xyz`:
|
For example, if a user is trying to access a GitLab instance from `first.host.xyz` and `second.host.xyz`:
|
||||||
|
|
||||||
- The user logs in via `first.host.xyz` and registers their U2F key.
|
- The user logs in via `first.host.xyz` and registers their U2F key.
|
||||||
- The user logs out and attempts to log in via `first.host.xyz` - U2F authentication suceeds.
|
- The user logs out and attempts to log in via `first.host.xyz` - U2F authentication suceeds.
|
||||||
- The user logs out and attempts to log in via `second.host.xyz` - U2F authentication fails, because
|
- The user logs out and attempts to log in via `second.host.xyz` - U2F authentication fails, because
|
||||||
the U2F key has only been registered on `first.host.xyz`.
|
the U2F key has only been registered on `first.host.xyz`.
|
||||||
|
|
||||||
|
[Google Authenticator]: https://support.google.com/accounts/answer/1066447?hl=en
|
||||||
|
[FreeOTP]: https://freeotp.github.io/
|
||||||
|
[YubiKey]: https://www.yubico.com/products/yubikey-hardware/
|
||||||
|
[api]: ../../../api/README.md
|
||||||
|
[pat]: ../personal_access_tokens.md
|
||||||
|
|
Binary file not shown.
After Width: | Height: | Size: 18 KiB |
|
@ -0,0 +1,57 @@
|
||||||
|
# Personal access tokens
|
||||||
|
|
||||||
|
> [Introduced][ce-3749] in GitLab 8.8.
|
||||||
|
|
||||||
|
Personal access tokens are useful if you need access to the [GitLab API][api].
|
||||||
|
Instead of using your private token which grants full access to your account,
|
||||||
|
personal access tokens could be a better fit because of their
|
||||||
|
[granular permissions](#limiting-scopes-of-a-personal-access-token).
|
||||||
|
|
||||||
|
You can also use them to authenticate against Git over HTTP. They are the only
|
||||||
|
accepted method of authentication when you have
|
||||||
|
[Two-Factor Authentication (2FA)][2fa] enabled.
|
||||||
|
|
||||||
|
Once you have your token, [pass it to the API][usage] using either the
|
||||||
|
`private_token` parameter or the `PRIVATE-TOKEN` header.
|
||||||
|
|
||||||
|
## Creating a personal access token
|
||||||
|
|
||||||
|
You can create as many personal access tokens as you like from your GitLab
|
||||||
|
profile.
|
||||||
|
|
||||||
|
1. Log in to your GitLab account.
|
||||||
|
1. Go to your **Profile settings**.
|
||||||
|
1. Go to **Access tokens**.
|
||||||
|
1. Choose a name and optionally an expiry date for the token.
|
||||||
|
1. Choose the [desired scopes](#limiting-scopes-of-a-personal-access-token).
|
||||||
|
1. Click on **Create personal access token**.
|
||||||
|
1. Save the personal access token somewhere safe. Once you leave or refresh
|
||||||
|
the page, you won't be able to access it again.
|
||||||
|
|
||||||
|
![Personal access tokens page](img/personal_access_tokens.png)
|
||||||
|
|
||||||
|
## Revoking a personal access token
|
||||||
|
|
||||||
|
At any time, you can revoke any personal access token by just clicking the
|
||||||
|
respective **Revoke** button under the 'Active personal access tokens' area.
|
||||||
|
|
||||||
|
## Limiting scopes of a personal access token
|
||||||
|
|
||||||
|
Personal access tokens can be created with one or more scopes that allow various
|
||||||
|
actions that a given token can perform. The available scopes are depicted in
|
||||||
|
the following table.
|
||||||
|
|
||||||
|
| Scope | Description |
|
||||||
|
| ----- | ----------- |
|
||||||
|
|`read_user` | Allows access to the read-only endpoints under `/users`. Essentially, any of the `GET` requests in the [Users API][users] are allowed ([introduced][ce-5951] in GitLab 8.15). |
|
||||||
|
| `api` | Grants complete access to the API (read/write) ([introduced][ce-5951] in GitLab 8.15). Required for accessing Git repositories over HTTP when 2FA is enabled. |
|
||||||
|
| `read_registry` | Allows to read [container registry] images if a project is private and authorization is required ([introduced][ce-11845] in GitLab 9.3). |
|
||||||
|
|
||||||
|
[2fa]: ../account/two_factor_authentication.md
|
||||||
|
[api]: ../../api/README.md
|
||||||
|
[ce-3749]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3749
|
||||||
|
[ce-5951]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5951
|
||||||
|
[ce-11845]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11845
|
||||||
|
[container registry]: ../project/container_registry.md
|
||||||
|
[users]: ../../api/users.md
|
||||||
|
[usage]: ../../api/README.md#basic-usage
|
|
@ -8,8 +8,8 @@
|
||||||
Registry across your GitLab instance, visit the
|
Registry across your GitLab instance, visit the
|
||||||
[administrator documentation](../../administration/container_registry.md).
|
[administrator documentation](../../administration/container_registry.md).
|
||||||
- Starting from GitLab 8.12, if you have 2FA enabled in your account, you need
|
- Starting from GitLab 8.12, if you have 2FA enabled in your account, you need
|
||||||
to pass a personal access token instead of your password in order to login to
|
to pass a [personal access token][pat] instead of your password in order to
|
||||||
GitLab's Container Registry.
|
login to GitLab's Container Registry.
|
||||||
- Multiple level image names support was added in GitLab 9.1
|
- Multiple level image names support was added in GitLab 9.1
|
||||||
|
|
||||||
With the Docker Container Registry integrated into GitLab, every project can
|
With the Docker Container Registry integrated into GitLab, every project can
|
||||||
|
@ -114,12 +114,11 @@ and [Using the GitLab Container Registry documentation](../../ci/docker/using_do
|
||||||
|
|
||||||
## Using with private projects
|
## Using with private projects
|
||||||
|
|
||||||
If a project is private, credentials will need to be provided for authorization.
|
> [Introduced][ce-11845] in GitLab 9.3.
|
||||||
The preferred way to do this, is by using personal access tokens, which can be
|
|
||||||
created under `/profile/personal_access_tokens`. The minimal scope needed is:
|
|
||||||
`read_registry`.
|
|
||||||
|
|
||||||
This feature was introduced in GitLab 9.3.
|
If a project is private, credentials will need to be provided for authorization.
|
||||||
|
The preferred way to do this, is by using [personal access tokens][pat].
|
||||||
|
The minimal scope needed is `read_registry`.
|
||||||
|
|
||||||
## Troubleshooting the GitLab Container Registry
|
## Troubleshooting the GitLab Container Registry
|
||||||
|
|
||||||
|
@ -264,4 +263,6 @@ The solution: check the [IAM permissions again](https://docs.docker.com/registry
|
||||||
Once the right permissions were set, the error will go away.
|
Once the right permissions were set, the error will go away.
|
||||||
|
|
||||||
[ce-4040]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4040
|
[ce-4040]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4040
|
||||||
|
[ce-11845]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11845
|
||||||
[docker-docs]: https://docs.docker.com/engine/userguide/intro/
|
[docker-docs]: https://docs.docker.com/engine/userguide/intro/
|
||||||
|
[pat]: ../profile/personal_access_tokens.md
|
||||||
|
|
|
@ -212,9 +212,9 @@ Container Registries for private projects.
|
||||||
access token created explicitly for this purpose). This issue is resolved with
|
access token created explicitly for this purpose). This issue is resolved with
|
||||||
latest changes in GitLab Runner 1.8 which receives GitLab credentials with
|
latest changes in GitLab Runner 1.8 which receives GitLab credentials with
|
||||||
build data.
|
build data.
|
||||||
- Starting with GitLab 8.12, if you have 2FA enabled in your account, you need
|
- Starting from GitLab 8.12, if you have [2FA] enabled in your account, you need
|
||||||
to pass a personal access token instead of your password in order to login to
|
to pass a [personal access token][pat] instead of your password in order to
|
||||||
GitLab's Container Registry.
|
login to GitLab's Container Registry.
|
||||||
|
|
||||||
Your jobs can access all container images that you would normally have access
|
Your jobs can access all container images that you would normally have access
|
||||||
to. The only implication is that you can push to the Container Registry of the
|
to. The only implication is that you can push to the Container Registry of the
|
||||||
|
@ -239,3 +239,5 @@ test:
|
||||||
[update-docs]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update
|
[update-docs]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update
|
||||||
[workhorse]: https://gitlab.com/gitlab-org/gitlab-workhorse
|
[workhorse]: https://gitlab.com/gitlab-org/gitlab-workhorse
|
||||||
[jobenv]: ../../ci/variables/README.md#predefined-variables-environment-variables
|
[jobenv]: ../../ci/variables/README.md#predefined-variables-environment-variables
|
||||||
|
[2fa]: ../profile/account/two_factor_authentication.md
|
||||||
|
[pat]: ../profile/personal_access_tokens.md
|
||||||
|
|
Loading…
Reference in New Issue