The following documentation is for the [internal CI API](ci/README.md):
-[Builds](ci/builds.md)
-[Runners](ci/runners.md)
## Road to GraphQL
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.
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
compatability 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)
It will co-exist with the current v4 REST API. If we have a v5 API, this should
be a compatibility layer on top of GraphQL.
## 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
those cases where it is not required, this will be mentioned in the documentation
for each individual endpoint. For example, the [`/projects/:id` endpoint](projects.md).
There are three types of tokens available: private tokens, OAuth 2 tokens, and personal
@@ -125,23 +125,14 @@ applications and U2F devices.
## Personal access tokens
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
access token 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.
authenticate with Git over HTTPS on the command line or when using
[GitLab's API][api], you must use a [personal access token][pat] instead.
## Recovery options
To disable two-factor authentication on your account (for example, if you
have lost your code generation device) you can:
*[Use a saved recovery code](#use-a-saved-recovery-code)
*[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)
...
...
@@ -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
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
use the other recovery codes you saved.
>**Note:**
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
...
...
@@ -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
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
device.
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 device.
### Ask a GitLab administrator to disable two-factor authentication on your account
...
...
@@ -206,19 +201,13 @@ Sign in and re-enable two-factor authentication as soon as possible.
## Note to GitLab administrators
- 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
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.
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). |
