Commit 7f052e3e authored by Robert Speicher's avatar Robert Speicher

Merge branch 'rs-remote-mirrors-docs' into 'master'

Add remote mirrors API documentation

See merge request gitlab-org/gitlab!22486
parents 0a1a71fb 33c0b616
---
title: Add documentation for create remote mirrors API
merge_request: 26012
author: Rajendra Kadam
type: added
---
title: Add remote mirrors API
merge_request:
author:
type: added
...@@ -61,6 +61,7 @@ The following API resources are available in the project context: ...@@ -61,6 +61,7 @@ The following API resources are available in the project context:
| [Protected tags](protected_tags.md) | `/projects/:id/protected_tags` | | [Protected tags](protected_tags.md) | `/projects/:id/protected_tags` |
| [Releases](releases/index.md) | `/projects/:id/releases` | | [Releases](releases/index.md) | `/projects/:id/releases` |
| [Release links](releases/links.md) | `/projects/:id/releases/.../assets/links` | | [Release links](releases/links.md) | `/projects/:id/releases/.../assets/links` |
| [Remote mirrors](remote_mirrors.md) | `/projects/:id/remote_mirrors` |
| [Repositories](repositories.md) | `/projects/:id/repository` | | [Repositories](repositories.md) | `/projects/:id/repository` |
| [Repository files](repository_files.md) | `/projects/:id/repository/files` | | [Repository files](repository_files.md) | `/projects/:id/repository/files` |
| [Repository submodules](repository_submodules.md) | `/projects/:id/repository/submodules` | | [Repository submodules](repository_submodules.md) | `/projects/:id/repository/submodules` |
......
# Project remote mirrors API
[Push mirrors](../user/project/repository/repository_mirroring.md#pushing-to-a-remote-repository-core)
defined on a project's repository settings are called "remote mirrors", and the
state of these mirrors can be queried and modified via the remote mirror API
outlined below.
## List a project's remote mirrors
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/38121) in GitLab 12.9.
Returns an Array of remote mirrors and their statuses:
```text
GET /projects/:id/remote_mirrors
```
Example request:
```sh
curl --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/42/remote_mirrors'
```
Example response:
```json
[
{
"enabled": true,
"id": 101486,
"last_error": null,
"last_successful_update_at": "2020-01-06T17:32:02.823Z",
"last_update_at": "2020-01-06T17:32:02.823Z",
"last_update_started_at": "2020-01-06T17:31:55.864Z",
"only_protected_branches": true,
"update_status": "finished",
"url": "https://*****:*****@gitlab.com/gitlab-org/security/gitlab.git"
}
]
```
NOTE: **Note:**
For security reasons, the `url` attribute will always be scrubbed of username
and password information.
## Create a remote mirror
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/24189) in GitLab 12.9.
Create a remote mirror for a project. The mirror will be disabled by default. You can enable it by including the optional parameter `enabled` when creating it:
```text
POST /projects/:id/remote_mirrors
```
| Attribute | Type | Required | Description |
| :---------- | :----- | :--------- | :------------ |
| `url` | String | yes | The URL of the remote repository to be mirrored. |
| `enabled` | Boolean | no | Determines if the mirror is enabled. |
| `only_protected_branches` | Boolean | no | Determines if only protected branches are mirrored. |
Example request:
```sh
curl --request POST --data "url=https://username:token@example.com/gitlab/example.git" --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/42/remote_mirrors'
```
Example response:
```json
{
"enabled": false,
"id": 101486,
"last_error": null,
"last_successful_update_at": null,
"last_update_at": null,
"last_update_started_at": null,
"only_protected_branches": false,
"update_status": "none",
"url": "https://*****:*****@example.com/gitlab/example.git"
}
```
## Update a remote mirror's attributes
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/38121) in GitLab 12.9.
Toggle a remote mirror on or off, or change which types of branches are
mirrored:
```text
PUT /projects/:id/remote_mirrors/:mirror_id
```
| Attribute | Type | Required | Description |
| :---------- | :----- | :--------- | :------------ |
| `mirror_id` | Integer | yes | The remote mirror ID. |
| `enabled` | Boolean | no | Determines if the mirror is enabled. |
| `only_protected_branches` | Boolean | no | Determines if only protected branches are mirrored. |
Example request:
```sh
curl --request PUT --data "enabled=false" --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/42/remote_mirrors/101486'
```
Example response:
```json
{
"enabled": false,
"id": 101486,
"last_error": null,
"last_successful_update_at": "2020-01-06T17:32:02.823Z",
"last_update_at": "2020-01-06T17:32:02.823Z",
"last_update_started_at": "2020-01-06T17:31:55.864Z",
"only_protected_branches": true,
"update_status": "finished",
"url": "https://*****:*****@gitlab.com/gitlab-org/security/gitlab.git"
}
```
...@@ -69,6 +69,11 @@ Changes pushed to files in the repository are automatically pushed to the remote ...@@ -69,6 +69,11 @@ Changes pushed to files in the repository are automatically pushed to the remote
In the case of a diverged branch, you will see an error indicated at the **Mirroring repositories** In the case of a diverged branch, you will see an error indicated at the **Mirroring repositories**
section. section.
### Configuring push mirrors through the API
You can also create and modify project push mirrors through the
[remote mirrors API](../../../api/remote_mirrors.md).
### Push only protected branches **(CORE)** ### Push only protected branches **(CORE)**
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3350) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3350) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3.
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment