From 6f923944d2e1d042b7865e14def672decd6b2998 Mon Sep 17 00:00:00 2001 From: Ben Prescott Date: Mon, 25 Apr 2022 09:15:52 +0100 Subject: [PATCH 1/3] Project creation example and error --- doc/api/projects.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/doc/api/projects.md b/doc/api/projects.md index 0d39fdd3aa779b..f232c6491c768d 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -1227,6 +1227,21 @@ where `password` is a public access key with the `api` scope enabled. POST /projects ``` +For example: + +```shell +curl --request POST --header "PRIVATE-TOKEN: " \ + --header "Content-Type: application/json" --data '{ + "name": "new_project", "description": "New Project", "path": "new_project", + "namespace_id": "42", "initialize_with_readme": "true"}' \ + --url 'https://gitlab.example.com/api/v4/projects/' +``` + +- `initialize_with_readme` will create a Git repository with just a `README.md` file. + [You might get the error](https://gitlab.com/gitlab-org/gitlab/-/issues/360266) + `not a git repository` if you specify this along with `import_url` or other attributes + of this endpoint which specify alternative contents for the repository. + | Attribute | Type | Required | Description | |-------------------------------------------------------------|---------|------------------------|-------------| | `name` | string | **{check-circle}** Yes (if path isn't provided) | The name of the new project. Equals path if not provided. | @@ -1253,7 +1268,7 @@ POST /projects | `external_authorization_classification_label` **(PREMIUM)** | string | **{dotted-circle}** No | The classification label for the project. | | `forking_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `group_with_project_templates_id` **(PREMIUM)** | integer | **{dotted-circle}** No | For group-level custom templates, specifies ID of group from which all the custom project templates are sourced. Leave empty for instance-level templates. Requires `use_custom_template` to be true. | -| `import_url` | string | **{dotted-circle}** No | URL to import repository from. | +| `import_url` | string | **{dotted-circle}** No | URL to import repository from. `initialize_with_readme` [should not also be set to true](https://gitlab.com/gitlab-org/gitlab/-/issues/360266). | | `initialize_with_readme` | boolean | **{dotted-circle}** No | `false` by default. | | `issues_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `issues_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable issues for this project. Use `issues_access_level` instead. | -- GitLab From 09af522799fb0b35f3b90ae088c77c8547049245 Mon Sep 17 00:00:00 2001 From: Marcin Sedlak-Jakubowski Date: Mon, 25 Apr 2022 12:34:36 +0000 Subject: [PATCH 2/3] Tweak wording for style --- doc/api/projects.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/projects.md b/doc/api/projects.md index f232c6491c768d..cac37c1c5cf40c 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -1227,7 +1227,7 @@ where `password` is a public access key with the `api` scope enabled. POST /projects ``` -For example: +Example request: ```shell curl --request POST --header "PRIVATE-TOKEN: " \ -- GitLab From 11f12fac5603b62716b53e64ae55c1854c3d38c0 Mon Sep 17 00:00:00 2001 From: Marcin Sedlak-Jakubowski Date: Mon, 25 Apr 2022 20:41:41 +0000 Subject: [PATCH 3/3] Clearer limitations of attributes --- doc/api/projects.md | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/doc/api/projects.md b/doc/api/projects.md index cac37c1c5cf40c..895199757bc9d9 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -1237,11 +1237,6 @@ curl --request POST --header "PRIVATE-TOKEN: " \ --url 'https://gitlab.example.com/api/v4/projects/' ``` -- `initialize_with_readme` will create a Git repository with just a `README.md` file. - [You might get the error](https://gitlab.com/gitlab-org/gitlab/-/issues/360266) - `not a git repository` if you specify this along with `import_url` or other attributes - of this endpoint which specify alternative contents for the repository. - | Attribute | Type | Required | Description | |-------------------------------------------------------------|---------|------------------------|-------------| | `name` | string | **{check-circle}** Yes (if path isn't provided) | The name of the new project. Equals path if not provided. | @@ -1268,8 +1263,8 @@ curl --request POST --header "PRIVATE-TOKEN: " \ | `external_authorization_classification_label` **(PREMIUM)** | string | **{dotted-circle}** No | The classification label for the project. | | `forking_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `group_with_project_templates_id` **(PREMIUM)** | integer | **{dotted-circle}** No | For group-level custom templates, specifies ID of group from which all the custom project templates are sourced. Leave empty for instance-level templates. Requires `use_custom_template` to be true. | -| `import_url` | string | **{dotted-circle}** No | URL to import repository from. `initialize_with_readme` [should not also be set to true](https://gitlab.com/gitlab-org/gitlab/-/issues/360266). | -| `initialize_with_readme` | boolean | **{dotted-circle}** No | `false` by default. | +| `import_url` | string | **{dotted-circle}** No | URL to import repository from. When this isn't empty, you must not set `initialize_with_readme` to `true`. Doing so might result in the [following error](https://gitlab.com/gitlab-org/gitlab/-/issues/360266): `not a git repository`. | +| `initialize_with_readme` | boolean | **{dotted-circle}** No | Whether to create a Git repository with just a `README.md` file. Default is `false`. When this is true, you must not pass `import_url` or other attributes of this endpoint which specify alternative contents for the repository. Doing so might result in the [following error](https://gitlab.com/gitlab-org/gitlab/-/issues/360266): `not a git repository`. | | `issues_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `issues_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable issues for this project. Use `issues_access_level` instead. | | `jobs_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable jobs for this project. Use `builds_access_level` instead. | -- GitLab