debian-mirror-gitlab/doc/development/internal_api.md

327 lines
9.1 KiB
Markdown
Raw Normal View History

2019-12-21 20:55:43 +05:30
# Internal API
The internal API is used by different GitLab components, it can not be
used by other consumers. This documentation is intended for people
working on the GitLab codebase.
2020-01-01 13:55:28 +05:30
This documentation does not yet include the internal API used by
GitLab Pages.
2019-12-21 20:55:43 +05:30
## Authentication
These methods are all authenticated using a shared secret. This secret
is stored in a file at the path configured in `config/gitlab.yml` by
default this is in the root of the rails app named
`.gitlab_shell_secret`
To authenticate using that token, clients read the contents of that
2020-04-22 19:07:51 +05:30
file, and include the token Base64 encoded in a `secret_token` parameter
2019-12-21 20:55:43 +05:30
or in the `Gitlab-Shared-Secret` header.
NOTE: **Note:**
2020-01-01 13:55:28 +05:30
The internal API used by GitLab Pages uses a different kind of
2019-12-21 20:55:43 +05:30
authentication.
## Git Authentication
This is called by Gitaly and GitLab-shell to check access to a
repository.
When called from GitLab-shell no changes are passed and the internal
API replies with the information needed to pass the request on to
Gitaly.
When called from Gitaly in a `pre-receive` hook the changes are passed
and those are validated to determine if the push is allowed.
2020-04-22 19:07:51 +05:30
```plaintext
2019-12-21 20:55:43 +05:30
POST /internal/allowed
```
| Attribute | Type | Required | Description |
|:----------|:-------|:---------|:------------|
| `key_id` | string | no | Id of the SSH-key used to connect to GitLab-shell |
| `username` | string | no | Username from the certificate used to connect to GitLab-Shell |
| `project` | string | no (if `gl_repository` is passed) | Path to the project |
| `gl_repository` | string | no (if `project` is passed) | Path to the project |
| `protocol` | string | yes | SSH when called from GitLab-shell, HTTP or SSH when called from Gitaly |
| `action` | string | yes | Git command being run (`git-upload-pack`, `git-receive-pack`, `git-upload-archive`) |
| `changes` | string | yes | `<oldrev> <newrev> <refname>` when called from Gitaly, The magic string `_any` when called from GitLab Shell |
2020-03-13 15:44:24 +05:30
| `check_ip` | string | no | Ip address from which call to GitLab Shell was made |
2019-12-21 20:55:43 +05:30
Example request:
2020-03-13 15:44:24 +05:30
```shell
2019-12-21 20:55:43 +05:30
curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded token>" --data "key_id=11&project=gnuwget/wget2&action=git-upload-pack&protocol=ssh" http://localhost:3001/api/v4/internal/allowed
```
Example response:
2020-04-22 19:07:51 +05:30
```json
2019-12-21 20:55:43 +05:30
{
"status": true,
"gl_repository": "project-3",
"gl_project_path": "gnuwget/wget2",
"gl_id": "user-1",
"gl_username": "root",
"git_config_options": [],
"gitaly": {
"repository": {
"storage_name": "default",
"relative_path": "@hashed/4e/07/4e07408562bedb8b60ce05c1decfe3ad16b72230967de01f640b7e4729b49fce.git",
"git_object_directory": "",
"git_alternate_object_directories": [],
"gl_repository": "project-3",
"gl_project_path": "gnuwget/wget2"
},
"address": "unix:/Users/bvl/repos/gitlab/gitaly.socket",
"token": null
},
"gl_console_messages": []
}
```
### Known consumers
- Gitaly
- GitLab-shell
## LFS Authentication
This is the endpoint that gets called from GitLab-shell to provide
information for LFS clients when the repository is accessed over SSH.
| Attribute | Type | Required | Description |
|:----------|:-------|:---------|:------------|
| `key_id` | string | no | Id of the SSH-key used to connect to GitLab-shell |
| `username`| string | no | Username from the certificate used to connect to GitLab-Shell |
| `project` | string | no | Path to the project |
Example request:
2020-03-13 15:44:24 +05:30
```shell
2019-12-21 20:55:43 +05:30
curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded token>" --data "key_id=11&project=gnuwget/wget2" http://localhost:3001/api/v4/internal/lfs_authenticate
```
2020-04-22 19:07:51 +05:30
```json
2019-12-21 20:55:43 +05:30
{
"username": "root",
"lfs_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7ImFjdG9yIjoicm9vdCJ9LCJqdGkiOiIyYWJhZDcxZC0xNDFlLTQ2NGUtOTZlMi1mODllYWRiMGVmZTYiLCJpYXQiOjE1NzAxMTc2NzYsIm5iZiI6MTU3MDExNzY3MSwiZXhwIjoxNTcwMTE5NDc2fQ.g7atlBw1QMY7QEBVPE0LZ8ZlKtaRzaMRmNn41r2YITM",
"repository_http_path": "http://localhost:3001/gnuwget/wget2.git",
"expires_in": 1800
}
```
### Known consumers
- GitLab-shell
## Authorized Keys Check
This endpoint is called by the GitLab-shell authorized keys
2020-01-01 13:55:28 +05:30
check. Which is called by OpenSSH for [fast SSH key
2019-12-21 20:55:43 +05:30
lookup](../administration/operations/fast_ssh_key_lookup.md).
| Attribute | Type | Required | Description |
|:----------|:-------|:---------|:------------|
| `key` | string | yes | SSH key as passed by OpenSSH to GitLab-shell |
2020-04-22 19:07:51 +05:30
```plaintext
2019-12-21 20:55:43 +05:30
GET /internal/authorized_keys
```
Example request:
2020-03-13 15:44:24 +05:30
```shell
2019-12-21 20:55:43 +05:30
curl --request GET --header "Gitlab-Shared-Secret: <Base64 encoded secret>""http://localhost:3001/api/v4/internal/authorized_keys?key=<key as passed by OpenSSH>"
```
Example response:
2020-04-22 19:07:51 +05:30
```json
2019-12-21 20:55:43 +05:30
{
"id": 11,
"title": "admin@example.com",
"key": "ssh-rsa ...",
"created_at": "2019-06-27T15:29:02.219Z"
}
```
### Known consumers
- GitLab-shell
## Get user for user id or key
This endpoint is used when a user performs `ssh git@gitlab.com`. It
discovers the user associated with an SSH key.
| Attribute | Type | Required | Description |
|:----------|:-------|:---------|:------------|
| `key_id` | integer | no | The id of the SSH key used as found in the authorized-keys file or through the `/authorized_keys` check |
| `username` | string | no | Username of the user being looked up, used by GitLab-shell when authenticating using a certificate |
2020-04-22 19:07:51 +05:30
```plaintext
2019-12-21 20:55:43 +05:30
GET /internal/discover
```
Example request:
2020-03-13 15:44:24 +05:30
```shell
2019-12-21 20:55:43 +05:30
curl --request GET --header "Gitlab-Shared-Secret: <Base64 encoded secret>" "http://localhost:3001/api/v4/internal/discover?key_id=7"
```
Example response:
2020-04-22 19:07:51 +05:30
```json
2019-12-21 20:55:43 +05:30
{
"id": 7,
"name": "Dede Eichmann",
"username": "rubi"
}
```
### Known consumers
- GitLab-shell
## Instance information
2020-04-22 19:07:51 +05:30
This gets some generic information about the instance. This is used
by Geo nodes to get information about each other
2019-12-21 20:55:43 +05:30
2020-04-22 19:07:51 +05:30
```plaintext
2019-12-21 20:55:43 +05:30
GET /internal/check
```
Example request:
2020-03-13 15:44:24 +05:30
```shell
2019-12-21 20:55:43 +05:30
curl --request GET --header "Gitlab-Shared-Secret: <Base64 encoded secret>" "http://localhost:3001/api/v4/internal/check"
```
Example response:
2020-04-22 19:07:51 +05:30
```json
2019-12-21 20:55:43 +05:30
{
"api_version": "v4",
"gitlab_version": "12.3.0-pre",
"gitlab_rev": "d69c988e6a6",
"redis": true
}
```
### Known consumers
- GitLab Geo
- GitLab-shell's `bin/check`
## Get new 2FA recovery codes using an SSH key
This is called from GitLab-shell and allows users to get new 2FA
recovery codes based on their SSH key
| Attribute | Type | Required | Description |
|:----------|:-------|:---------|:------------|
| `key_id` | integer | no | The id of the SSH key used as found in the authorized-keys file or through the `/authorized_keys` check |
| `user_id` | integer | no | **Deprecated** User_id for which to generate new recovery codes |
2020-04-22 19:07:51 +05:30
```plaintext
2019-12-21 20:55:43 +05:30
GET /internal/two_factor_recovery_codes
```
Example request:
2020-03-13 15:44:24 +05:30
```shell
2019-12-21 20:55:43 +05:30
curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" --data "key_id=7" http://localhost:3001/api/v4/internal/two_factor_recovery_codes
```
Example response:
2020-04-22 19:07:51 +05:30
```json
2019-12-21 20:55:43 +05:30
{
"success": true,
"recovery_codes": [
"d93ee7037944afd5",
"19d7b84862de93dd",
"1e8c52169195bf71",
"be50444dddb7ca84",
"26048c77d161d5b7",
"482d5c03d1628c47",
"d2c695e309ce7679",
"dfb4748afc4f12a7",
"0e5f53d1399d7979",
"af04d5622153b020"
]
}
```
### Known consumers
- GitLab-shell
## Incrementing counter on pre-receive
This is called from the Gitaly hooks increasing the reference counter
for a push that might be accepted.
| Attribute | Type | Required | Description |
|:----------|:-------|:---------|:------------|
| `gl_repository` | string | yes | repository identifier for the repository receiving the push |
2020-04-22 19:07:51 +05:30
```plaintext
2019-12-21 20:55:43 +05:30
POST /internal/pre_receive
```
Example request:
2020-03-13 15:44:24 +05:30
```shell
2019-12-21 20:55:43 +05:30
curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" --data "gl_repository=project-7" http://localhost:3001/api/v4/internal/pre_receive
```
Example response:
2020-04-22 19:07:51 +05:30
```json
2019-12-21 20:55:43 +05:30
{
"reference_counter_increased": true
}
```
## PostReceive
Called from Gitaly after a receiving a push. This triggers the
2020-01-01 13:55:28 +05:30
`PostReceive`-worker in Sidekiq, processes the passed push options and
2019-12-21 20:55:43 +05:30
builds the response including messages that need to be displayed to
the user.
| Attribute | Type | Required | Description |
|:----------|:-------|:---------|:------------|
| `identifier` | string | yes | `user-[id]` or `key-[id]` Identifying the user performing the push |
| `gl_repository` | string | yes | identifier of the repository being pushed to |
2020-01-01 13:55:28 +05:30
| `push_options` | string array | no | array of push options |
2019-12-21 20:55:43 +05:30
| `changes` | string | no | refs to be updated in the push in the format `oldrev newrev refname\n`. |
2020-04-22 19:07:51 +05:30
```plaintext
2019-12-21 20:55:43 +05:30
POST /internal/post_receive
```
Example Request:
2020-03-13 15:44:24 +05:30
```shell
2019-12-21 20:55:43 +05:30
curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" --data "gl_repository=project-7" --data "identifier=user-1" --data "changes=0000000000000000000000000000000000000000 fd9e76b9136bdd9fe217061b497745792fe5a5ee gh-pages\n" http://localhost:3001/api/v4/internal/post_receive
```
Example response:
2020-04-22 19:07:51 +05:30
```json
2019-12-21 20:55:43 +05:30
{
"messages": [
{
"message": "Hello from post-receive",
"type": "alert"
}
],
"reference_counter_decreased": true
}
```