From df9ac2a0a22629952f7d208933d7f9176fdc12a5 Mon Sep 17 00:00:00 2001 From: Robert Speicher Date: Mon, 6 Jan 2020 11:49:57 -0600 Subject: [PATCH 1/2] Add remote mirrors API documentation --- .../unreleased/rs-remote-mirrors-docs.yml | 5 ++ doc/api/api_resources.md | 1 + doc/api/remote_mirrors.md | 83 +++++++++++++++++++ .../repository/repository_mirroring.md | 5 ++ 4 files changed, 94 insertions(+) create mode 100644 changelogs/unreleased/rs-remote-mirrors-docs.yml create mode 100644 doc/api/remote_mirrors.md diff --git a/changelogs/unreleased/rs-remote-mirrors-docs.yml b/changelogs/unreleased/rs-remote-mirrors-docs.yml new file mode 100644 index 00000000000000..3711aac63eff9d --- /dev/null +++ b/changelogs/unreleased/rs-remote-mirrors-docs.yml @@ -0,0 +1,5 @@ +--- +title: Add remote mirrors API +merge_request: +author: +type: added diff --git a/doc/api/api_resources.md b/doc/api/api_resources.md index 6a8394752c53d0..7685a564076054 100644 --- a/doc/api/api_resources.md +++ b/doc/api/api_resources.md @@ -61,6 +61,7 @@ The following API resources are available in the project context: | [Protected tags](protected_tags.md) | `/projects/:id/protected_tags` | | [Releases](releases/index.md) | `/projects/:id/releases` | | [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` | | [Repository files](repository_files.md) | `/projects/:id/repository/files` | | [Repository submodules](repository_submodules.md) | `/projects/:id/repository/submodules` | diff --git a/doc/api/remote_mirrors.md b/doc/api/remote_mirrors.md new file mode 100644 index 00000000000000..fc83d3da47425f --- /dev/null +++ b/doc/api/remote_mirrors.md @@ -0,0 +1,83 @@ +# 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: " '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. + +## 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: " '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" +} +``` diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md index fe57df38d37b9d..33fa09255e11ff 100644 --- a/doc/user/project/repository/repository_mirroring.md +++ b/doc/user/project/repository/repository_mirroring.md @@ -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** 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)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3350) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. -- GitLab From 83e138ffa4137be1e0ca66224d6c38b6deb4bb29 Mon Sep 17 00:00:00 2001 From: Rajendra Kadam Date: Wed, 4 Mar 2020 20:25:38 +0000 Subject: [PATCH 2/2] Add docs for create remote mirror API --- .../unreleased/create-remote-mirrors-docs.yml | 5 +++ doc/api/remote_mirrors.md | 38 +++++++++++++++++++ 2 files changed, 43 insertions(+) create mode 100644 changelogs/unreleased/create-remote-mirrors-docs.yml diff --git a/changelogs/unreleased/create-remote-mirrors-docs.yml b/changelogs/unreleased/create-remote-mirrors-docs.yml new file mode 100644 index 00000000000000..16b438d53bb5ef --- /dev/null +++ b/changelogs/unreleased/create-remote-mirrors-docs.yml @@ -0,0 +1,5 @@ +--- +title: Add documentation for create remote mirrors API +merge_request: 26012 +author: Rajendra Kadam +type: added diff --git a/doc/api/remote_mirrors.md b/doc/api/remote_mirrors.md index fc83d3da47425f..0ffff1949760c7 100644 --- a/doc/api/remote_mirrors.md +++ b/doc/api/remote_mirrors.md @@ -43,6 +43,44 @@ 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: " '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. -- GitLab