Commit 97aa25ba authored by Achilleas Pipinellis's avatar Achilleas Pipinellis

Merge branch 'docs/document-built-in-templates' into 'master'

Restructure projects template topics

Closes #55834

See merge request gitlab-org/gitlab-ce!24448
parents 2e36b0d7 2b47e4d4
# How to create a project in GitLab # Create a project
> **Notes:** [Projects](../user/project/index.md) combine many features of GitLab together.
> - For a list of words that are not allowed to be used as project names see the
> [reserved names][reserved].
1. In your dashboard, click the green **New project** button or use the plus NOTE: **Note:**
icon in the upper right corner of the navigation bar. For a list of words that cannot be used as project names see
[Reserved project and group names](../user/reserved_names.md).
![Create a project](img/create_new_project_button.png) To create a project in GitLab:
1. This opens the **New project** page. 1. In your dashboard, click the green **New project** button or use the plus
icon in the navigation bar. This opens the **New project** page.
1. On the **New project** page, choose if you want to:
- Create a [blank project](#blank-projects).
- Create a project using with one of the available [project templates](#project-templates).
- [Import a project](../user/project/import/index.md) from a different repository,
if enabled on your GitLab instance. Contact your GitLab admin if this
is unavailable.
![Project information](img/create_new_project_info.png) ## Blank projects
1. Choose if you want start a blank project, or with one of the predefined To create a new blank project on the **New project** page:
[Project Templates](https://gitlab.com/gitlab-org/project-templates):
this will kickstart your repository code and CI automatically.
Otherwise, if you have a project in a different repository, you can [import it] by
clicking on the **Import project** tab, provided this is enabled in
your GitLab instance. Ask your administrator if not.
1. Provide the following information: 1. On the **Blank project** tab, provide the following information:
- Enter the name of your project in the **Project name** field. You can't use - The name of your project in the **Project name** field. You can't use
special characters, but you can use spaces, hyphens, underscores or even special characters, but you can use spaces, hyphens, underscores or even
emoji. emoji.
- The **Project description (optional)** field enables you to enter a - The **Project description (optional)** field enables you to enter a
...@@ -31,11 +32,64 @@ ...@@ -31,11 +32,64 @@
- Changing the **Visibility Level** modifies the project's - Changing the **Visibility Level** modifies the project's
[viewing and access rights](../public_access/public_access.md) for users. [viewing and access rights](../public_access/public_access.md) for users.
- Selecting the **Initialize repository with a README** option creates a - Selecting the **Initialize repository with a README** option creates a
README so that the Git repository is initialized, has a default branch and README file so that the Git repository is initialized, has a default branch, and
can be cloned. can be cloned.
1. Click **Create project**. 1. Click **Create project**.
## Project templates
Project templates can pre-populate your project with necessary files to get you started quickly.
There are two types of project templates:
- [Built-in templates](#builtin-templates), sourced from the [`project-templates`](https://gitlab.com/gitlab-org/project-templates) group.
- [Custom project templates](#custom-project-templates-premium-only), for custom templates configured by GitLab administrators and users.
### Built-in templates
Built-in templates are project templates that are:
- Developed and maintained in the
[`project-templates`](https://gitlab.com/gitlab-org/project-templates) group.
- Released with GitLab.
To use a built-in template on the **New project** page:
1. On the **Create from template** tab.
1. From the list of available built-in templates, click the:
- **Preview** button to look at the template source itself.
- **Use template** button to start creating the project.
1. Finish creating the project by filling out the project's details. The process is the same as for
using a [blank project](#blank-projects).
TIP: **Tip:**
You can improve the existing built-in templates or contribute new ones on the
[`project-templates`](https://gitlab.com/gitlab-org/project-templates) group.
### Custom project templates **[PREMIUM ONLY]**
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6860) in
[GitLab Premium](https://about.gitlab.com/pricing) 11.2.
Creating new projects based on custom project templates is a convenient option to bootstrap a project.
Custom projects are available from the **Instance** or **Group** tabs under the **Create from template** tab,
depending on the type of template.
To use a custom project template on the **New project** page:
1. On the **Create from template** tab, select the **Instance** tab or the **Group** tab.
1. From the list of available custom templates, click the:
- **Preview** button to look at the template source itself.
- **Use template** button to start creating the project.
1. Finish creating the project by filling out the project's details. The process is the same as for
using a [blank project](#blank-projects).
For information on configuring custom project templates, see:
- [Custom instance-level project templates](../user/admin_area/custom_project_templates.md), for instance-level templates.
- [Custom group-level project templates](../user/group/custom_project_templates.md), for group-level templates.
## Push to create a new project ## Push to create a new project
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/26388) in GitLab 10.5. > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/26388) in GitLab 10.5.
...@@ -46,20 +100,20 @@ GitLab to create the new project, all without leaving your terminal. If you have ...@@ -46,20 +100,20 @@ GitLab to create the new project, all without leaving your terminal. If you have
namespace, we will automatically create a new project under that GitLab namespace with its namespace, we will automatically create a new project under that GitLab namespace with its
visibility set to Private by default (you can later change it in the [project's settings](../public_access/public_access.md#how-to-change-project-visibility)). visibility set to Private by default (you can later change it in the [project's settings](../public_access/public_access.md#how-to-change-project-visibility)).
This can be done by using either SSH or HTTP: This can be done by using either SSH or HTTPS:
``` ```sh
## Git push using SSH ## Git push using SSH
git push --set-upstream git@gitlab.example.com:namespace/nonexistent-project.git master git push --set-upstream git@gitlab.example.com:namespace/nonexistent-project.git master
## Git push using HTTP ## Git push using HTTPS
git push --set-upstream https://gitlab.example.com/namespace/nonexistent-project.git master git push --set-upstream https://gitlab.example.com/namespace/nonexistent-project.git master
``` ```
Once the push finishes successfully, a remote message will indicate Once the push finishes successfully, a remote message will indicate
the command to set the remote and the URL to the new project: the command to set the remote and the URL to the new project:
``` ```text
remote: remote:
remote: The private project namespace/nonexistent-project was created. remote: The private project namespace/nonexistent-project was created.
remote: remote:
...@@ -70,6 +124,3 @@ remote: To view the project, visit: ...@@ -70,6 +124,3 @@ remote: To view the project, visit:
remote: https://gitlab.example.com/namespace/nonexistent-project remote: https://gitlab.example.com/namespace/nonexistent-project
remote: remote:
``` ```
[import it]: ../workflow/importing/README.md
[reserved]: ../user/reserved_names.md
...@@ -2,24 +2,25 @@ ...@@ -2,24 +2,25 @@
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6860) in [GitLab Premium](https://about.gitlab.com/pricing) 11.2. > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6860) in [GitLab Premium](https://about.gitlab.com/pricing) 11.2.
When you create a new project, creating it based on custom project templates is When you create a new [project](../project/index.md), creating it based on custom project templates is
a convenient option to bootstrap from an existing project boilerplate. a convenient bootstrap option.
The administration setting to configure a GitLab group that serves as template
source can be found under **Admin > Settings > Custom project templates**. GitLab administrators can configure a GitLab group that serves as template
source for an entire GitLab instance under **Admin area > Settings > Custom project templates**.
NOTE: **Note:**
To set project templates at a group level,
see [Custom group-level project templates](../group/custom_project_templates.md).
Within this section, you can configure the group where all the custom project Within this section, you can configure the group where all the custom project
templates are sourced. Every project directly under the group namespace will be templates are sourced. Every project directly under the group namespace will be
available to the user if they have access to them. For example, every public available to the user if they have access to them. For example, every public
project in the group will be available to every logged user. However, project in the group will be available to every logged in user.
private projects will be available only if the user has view [permissions](../permissions.md)
in the project:
- Project Owner, Maintainer, Developer, Reporter or Guest However, private projects will be available only if the user is a member of the project.
- Is a member of the Group: Owner, Maintainer, Developer, Reporter or Guest
NOTE: **Note:**
Projects below subgroups of the template group are **not** supported. Projects below subgroups of the template group are **not** supported.
Repository and database information that are copied over to each new project are Repository and database information that are copied over to each new project are
identical to the data exported with [GitLab's Project Import/Export](../project/settings/import_export.md). identical to the data exported with [GitLab's Project Import/Export](../project/settings/import_export.md).
If you would like to set project templates at a group level, please see [Custom group-level project templates](../group/custom_project_templates.md).
\ No newline at end of file
...@@ -2,22 +2,25 @@ ...@@ -2,22 +2,25 @@
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6861) in [GitLab Premium](https://about.gitlab.com/pricing) 11.6. > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6861) in [GitLab Premium](https://about.gitlab.com/pricing) 11.6.
When you create a new project, creating it based on custom project templates is When you create a new [project](../project/index.md), creating it based on custom project templates is
a convenient option to bootstrap from an existing project boilerplate. a convenient bootstrap option.
The group-level setting to configure a GitLab group that serves as template
source can be found under **Group > Settings > General > Custom project templates**. Users can configure a GitLab group that serves as template
source under a group's **Settings > General > Custom project templates**.
NOTE: **Note:**
GitLab administrators can
[set project templates for an entire GitLab instance](../admin_area/custom_project_templates.md).
Within this section, you can configure the group where all the custom project Within this section, you can configure the group where all the custom project
templates are sourced. Every project directly under the group namespace will be templates are sourced. Every project directly under the group namespace will be
available to the user if they have access to them. For example, every public available to the user if they have access to them. For example, every public
project in the group will be available to every logged in user. However, project in the group will be available to every logged in user.
private projects will be available only if the user has view [permissions](../permissions.md)
in the project. That is, users with Owner, Maintainer, Developer, Reporter or Guest roles for projects,
or for groups to which the project belongs.
However, private projects will be available only if the user is a member of the project.
NOTE: **Note:**
Projects of nested subgroups of a selected template source cannot be used. Projects of nested subgroups of a selected template source cannot be used.
Repository and database information that are copied over to each new project are Repository and database information that are copied over to each new project are
identical to the data exported with [GitLab's Project Import/Export](../project/settings/import_export.md). identical to the data exported with [GitLab's Project Import/Export](../project/settings/import_export.md).
If you would like to set project templates at an instance level, please see [Custom instance-level project templates](../admin_area/custom_project_templates.md).
\ No newline at end of file
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