debian-mirror-gitlab/doc/api/remote_mirrors.md

206 lines
7 KiB
Markdown
Raw Normal View History

2020-10-24 23:57:45 +05:30
---
stage: Create
group: Source Code
2022-11-25 23:54:43 +05:30
info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments"
2020-10-24 23:57:45 +05:30
type: reference, api
---
2021-03-11 19:13:27 +05:30
# Project remote mirrors API **(FREE)**
2020-04-08 14:13:33 +05:30
2021-11-18 22:05:49 +05:30
[Push mirrors](../user/project/repository/mirror/push.md)
2023-01-13 00:05:48 +05:30
defined on a project's repository settings are called "remote mirrors". You
can query and modify the state of these mirrors with the remote mirror API.
2020-04-08 14:13:33 +05:30
2023-01-13 00:05:48 +05:30
For security reasons, the `url` attribute in the API response is always scrubbed of username
and password information.
2020-04-08 14:13:33 +05:30
2023-04-23 21:23:45 +05:30
NOTE:
[Pull mirrors](../user/project/repository/mirror/pull.md) use
[a different API endpoint](projects.md#configure-pull-mirroring-for-a-project) to
display and update them.
2023-01-13 00:05:48 +05:30
## List a project's remote mirrors
2020-04-08 14:13:33 +05:30
2023-01-13 00:05:48 +05:30
Returns an array of remote mirrors and their statuses:
2020-04-08 14:13:33 +05:30
2020-05-24 23:13:21 +05:30
```plaintext
2020-04-08 14:13:33 +05:30
GET /projects/:id/remote_mirrors
```
Example request:
2020-05-24 23:13:21 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/42/remote_mirrors"
2020-04-08 14:13:33 +05:30
```
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,
2020-05-24 23:13:21 +05:30
"keep_divergent_refs": true,
2020-04-08 14:13:33 +05:30
"update_status": "finished",
"url": "https://*****:*****@gitlab.com/gitlab-org/security/gitlab.git"
}
]
```
2022-06-21 17:19:12 +05:30
## Get a single project's remote mirror
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82770) in GitLab 14.10.
Returns a remote mirror and its statuses:
```plaintext
GET /projects/:id/remote_mirrors/:mirror_id
```
Example request:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/42/remote_mirrors/101486"
```
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,
"keep_divergent_refs": true,
"update_status": "finished",
"url": "https://*****:*****@gitlab.com/gitlab-org/security/gitlab.git"
}
```
2021-11-18 22:05:49 +05:30
## Create a pull mirror
Learn how to [configure a pull mirror](projects.md#configure-pull-mirroring-for-a-project) using the Projects API.
## Create a push mirror
2020-04-08 14:13:33 +05:30
2023-03-17 16:20:25 +05:30
> Field `mirror_branch_regex` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102608) in GitLab 15.8 [with a flag](../administration/feature_flags.md) named `mirror_only_branches_match_regex`. Disabled by default.
FLAG:
On self-managed GitLab, by default the field `mirror_branch_regex` is not available.
To make it available, ask an administrator to [enable the feature flag](../administration/feature_flags.md)
named `mirror_only_branches_match_regex`.
On GitLab.com, this feature is not available.
2023-01-13 00:05:48 +05:30
Push mirroring is disabled by default. To enable it, include the optional parameter
`enabled` when you create the mirror:
2020-04-08 14:13:33 +05:30
2020-05-24 23:13:21 +05:30
```plaintext
2020-04-08 14:13:33 +05:30
POST /projects/:id/remote_mirrors
```
| Attribute | Type | Required | Description |
| :---------- | :----- | :--------- | :------------ |
2021-11-18 22:05:49 +05:30
| `url` | String | yes | The target URL to which the repository is mirrored. |
2020-04-08 14:13:33 +05:30
| `enabled` | Boolean | no | Determines if the mirror is enabled. |
2020-05-24 23:13:21 +05:30
| `keep_divergent_refs` | Boolean | no | Determines if divergent refs are skipped. |
2023-01-13 00:05:48 +05:30
| `only_protected_branches` | Boolean | no | Determines if only protected branches are mirrored. |
2023-03-17 16:20:25 +05:30
| `mirror_branch_regex` **(PREMIUM)** | String | no | Contains a regular expression. Only branches with names matching the regex are mirrored. Requires `only_protected_branches` to be disabled. |
2020-04-08 14:13:33 +05:30
Example request:
2020-05-24 23:13:21 +05:30
```shell
2021-09-04 01:27:46 +05:30
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"
2020-04-08 14:13:33 +05:30
```
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,
2020-05-24 23:13:21 +05:30
"keep_divergent_refs": false,
2020-04-08 14:13:33 +05:30
"update_status": "none",
"url": "https://*****:*****@example.com/gitlab/example.git"
}
```
## Update a remote mirror's attributes
2023-03-17 16:20:25 +05:30
FLAG:
On self-managed GitLab, by default the field `mirror_branch_regex` is not available.
To make it available, ask an administrator to [enable the feature flag](../administration/feature_flags.md)
named `mirror_only_branches_match_regex`.
On GitLab.com, this feature is not available.
2020-04-08 14:13:33 +05:30
Toggle a remote mirror on or off, or change which types of branches are
mirrored:
2020-05-24 23:13:21 +05:30
```plaintext
2020-04-08 14:13:33 +05:30
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. |
2020-05-24 23:13:21 +05:30
| `keep_divergent_refs` | Boolean | no | Determines if divergent refs are skipped. |
2023-01-13 00:05:48 +05:30
| `only_protected_branches` | Boolean | no | Determines if only protected branches are mirrored. |
2023-03-17 16:20:25 +05:30
| `mirror_branch_regex`**(PREMIUM)** | String | no | Determines if only the branch whose name matches the regex is mirrored. It does not work with `only_protected_branches` enabled. |
2020-04-08 14:13:33 +05:30
Example request:
2020-05-24 23:13:21 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request PUT --data "enabled=false" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/42/remote_mirrors/101486"
2020-04-08 14:13:33 +05:30
```
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,
2020-05-24 23:13:21 +05:30
"keep_divergent_refs": true,
2020-04-08 14:13:33 +05:30
"update_status": "finished",
"url": "https://*****:*****@gitlab.com/gitlab-org/security/gitlab.git"
}
```
2022-06-21 17:19:12 +05:30
## Delete a remote mirror
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82778) in GitLab 14.10.
Delete a remote mirror.
```plaintext
DELETE /projects/:id/remote_mirrors/:mirror_id
```
| Attribute | Type | Required | Description |
| :---------- | :----- | :--------- |:------------------|
| `mirror_id` | Integer | yes | Remote mirror ID. |
Example request:
```shell
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/42/remote_mirrors/101486"
```