diff options
Diffstat (limited to 'doc/user/project/working_with_projects.md')
| -rw-r--r-- | doc/user/project/working_with_projects.md | 341 |
1 files changed, 341 insertions, 0 deletions
diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md new file mode 100644 index 00000000000..3fe6193c414 --- /dev/null +++ b/doc/user/project/working_with_projects.md @@ -0,0 +1,341 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +--- + +# Working with projects **(FREE)** + +Most work in GitLab is done in a [project](../../user/project/index.md). Files and +code are saved in projects, and most features are in the scope of projects. + +## Explore projects + +You can explore other popular projects available on GitLab. To explore projects: + +1. Click **Projects** in the navigation bar. +1. Click **Explore Projects**. + +GitLab displays a list of projects, sorted by last updated date. To view +projects with the most [stars](#star-a-project), click **Most stars**. To view +projects with the largest number of comments in the past month, click **Trending**. + +## Create a project + +To create a project in GitLab: + +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 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 administrator if this is unavailable. + - Run [CI/CD pipelines for external repositories](../../ci/ci_cd_for_external_repos/index.md). **(PREMIUM)** + +NOTE: +For a list of words that can't be used as project names see +[Reserved project and group names](../../user/reserved_names.md). + +### Blank projects + +To create a new blank project on the **New project** page: + +1. On the **Blank project** tab, provide the following information: + - 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 + emoji. When adding the name, the **Project slug** auto populates. + The slug is what the GitLab instance uses as the URL path to the project. + If you want a different slug, input the project name first, + then change the slug after. + - The path to your project in the **Project slug** field. This is the URL + path for your project that the GitLab instance uses. If the + **Project name** is blank, it auto populates when you fill in + the **Project slug**. + - The **Project description (optional)** field enables you to enter a + description for your project's dashboard, which helps others + understand what your project is about. Though it's not required, it's a good + idea to fill this in. + - Changing the **Visibility Level** modifies the project's + [viewing and access rights](../../public_access/public_access.md) for users. + - Selecting the **Initialize repository with a README** option creates a + README file so that the Git repository is initialized, has a default branch, and + can be cloned. +1. Click **Create project**. + +### Project templates + +Project templates can pre-populate a new project with the necessary files to get you +started quickly. + +There are two main types of project templates: + +- [Built-in templates](#built-in-templates), sourced from the following groups: + - [`project-templates`](https://gitlab.com/gitlab-org/project-templates) + - [`pages`](https://gitlab.com/pages) +- [Custom project templates](#custom-project-templates), 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) + and [`pages`](https://gitlab.com/pages) groups. +- Released with GitLab. + +To use a built-in template on the **New project** page: + +1. On the **Create from template** tab, select the **Built-in** 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 creating a [blank project](#blank-projects). + +##### Enterprise templates **(ULTIMATE)** + +GitLab is developing Enterprise templates to help you streamline audit management with selected regulatory standards. These templates automatically import issues that correspond to each regulatory requirement. + +To create a new project with an Enterprise template, on the **New project** page: + +1. On the **Create from template** tab, select the **Built-in** tab. +1. From the list of available built-in Enterprise 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 creating a [blank project](#blank-projects). + +Available Enterprise templates include: + +- HIPAA Audit Protocol template ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13756) in GitLab 12.10) + +NOTE: +You can improve the existing built-in templates or contribute new ones in the +[`project-templates`](https://gitlab.com/gitlab-org/project-templates) and +[`pages`](https://gitlab.com/pages) groups by following [these steps](https://gitlab.com/gitlab-org/project-templates/contributing). + +##### Custom project templates **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6860) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2. + +Creating new projects based on custom project templates is a convenient option for +quickly starting projects. + +Custom projects are available at the [instance-level](../../user/admin_area/custom_project_templates.md) +from the **Instance** tab, or at the [group-level](../../user/group/custom_project_templates.md) +from the **Group** tab, under the **Create from template** tab. + +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 creating a [blank project](#blank-projects). + +## Push to create a new project + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/26388) in GitLab 10.5. + +When you create a new repository locally, instead of manually creating a new project in GitLab +and then [cloning the repository](../../gitlab-basics/start-using-git.md#clone-a-repository) +locally, you can directly push it to GitLab to create the new project, all without leaving +your terminal. If you have access rights to the associated namespace, GitLab +automatically creates 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)). + +This can be done by using either SSH or HTTPS: + +```shell +## Git push using SSH +git push --set-upstream git@gitlab.example.com:namespace/nonexistent-project.git master + +## Git push using HTTPS +git push --set-upstream https://gitlab.example.com/namespace/nonexistent-project.git master +``` + +You can pass the flag `--tags` to the `git push` command to export existing repository tags. + +Once the push finishes successfully, a remote message indicates +the command to set the remote and the URL to the new project: + +```plaintext +remote: +remote: The private project namespace/nonexistent-project was created. +remote: +remote: To configure the remote, run: +remote: git remote add origin https://gitlab.example.com/namespace/nonexistent-project.git +remote: +remote: To view the project, visit: +remote: https://gitlab.example.com/namespace/nonexistent-project +remote: +``` + +## Fork a project + +A fork is a copy of an original repository that you put in another namespace +where you can experiment and apply changes that you can later decide whether or +not to share, without affecting the original project. + +It takes just a few steps to [fork a project in GitLab](repository/forking_workflow.md#creating-a-fork). + +## Star a project + +You can star a project to make it easier to find projects you frequently use. +The number of stars a project has can indicate its popularity. + +To star a project: + +1. Go to the home page of the project you want to star. +1. In the upper right corner of the page, click **Star**. + +To view your starred projects: + +1. Click **Projects** in the navigation bar. +1. Click **Starred Projects**. +1. GitLab displays information about your starred projects, including: + + - Project description, including name, description, and icon + - Number of times this project has been starred + - Number of times this project has been forked + - Number of open merge requests + - Number of open issues + +## Delete a project + +To delete a project, first navigate to the home page for that project. + +1. Navigate to **Settings > General**. +1. Expand the **Advanced** section. +1. Scroll down to the **Delete project** section. +1. Click **Delete project** +1. Confirm this action by typing in the expected text. + +Projects in personal namespaces are deleted immediately on request. For information on delayed deletion of projects in a group, please see [Enabling delayed project removal](../group/index.md#enabling-delayed-project-removal). + +## Project settings + +Set the project's visibility level and the access levels to its various pages +and perform actions like archiving, renaming or transferring a project. + +Read through the documentation on [project settings](settings/index.md). + +## Project activity + +To view the activity of a project, navigate to **Project overview > Activity**. +From there, you can click on the tabs to see **All** the activity, or see it +filtered by **Push events**, **Merge events**, **Issue events**, **Comments**, +**Team**, and **Wiki**. + +### Leave a project + +**Leave project** only displays on the project's dashboard +when a project is part of a group (under a +[group namespace](../group/index.md#namespaces)). +If you choose to leave a project you are no longer a project +member, and cannot contribute. + +## Use your project as a Go package + +Any project can be used as a Go package. GitLab responds correctly to `go get` +and `godoc.org` discovery requests, including the +[`go-import`](https://golang.org/cmd/go/#hdr-Remote_import_paths) and +[`go-source`](https://github.com/golang/gddo/wiki/Source-Code-Links) meta tags. + +Private projects, including projects in subgroups, can be used as a Go package, +but may require configuration to work correctly. GitLab responds correctly +to `go get` discovery requests for projects that *are not* in subgroups, +regardless of authentication or authorization. +[Authentication](#authenticate-go-requests) is required to use a private project +in a subgroup as a Go package. Otherwise, GitLab truncates the path for +private projects in subgroups to the first two segments, causing `go get` to +fail. + +GitLab implements its own Go proxy. This feature must be enabled by an +administrator and requires additional configuration. See [GitLab Go +Proxy](../packages/go_proxy/index.md). + +### Disable Go module features for private projects + +In Go 1.12 and later, Go queries module proxies and checksum databases in the +process of [fetching a +module](../../development/go_guide/dependencies.md#fetching). This can be +selectively disabled with `GOPRIVATE` (disable both), +[`GONOPROXY`](../../development/go_guide/dependencies.md#proxies) (disable proxy +queries), and [`GONOSUMDB`](../../development/go_guide/dependencies.md#fetching) +(disable checksum queries). + +`GOPRIVATE`, `GONOPROXY`, and `GONOSUMDB` are comma-separated lists of Go +modules and Go module prefixes. For example, +`GOPRIVATE=gitlab.example.com/my/private/project` disables queries for that +one project, but `GOPRIVATE=gitlab.example.com` disables queries for *all* +projects on GitLab.com. Go does not query module proxies if the module name or a +prefix of it appears in `GOPRIVATE` or `GONOPROXY`. Go does not query checksum +databases if the module name or a prefix of it appears in `GONOPRIVATE` or +`GONOSUMDB`. + +### Authenticate Go requests + +To authenticate requests to private projects made by Go, use a [`.netrc` +file](https://ec.haxx.se/usingcurl-netrc.html) and a [personal access +token](../profile/personal_access_tokens.md) in the password field. **This only +works if your GitLab instance can be accessed with HTTPS.** The `go` command +does not transmit credentials over insecure connections. This authenticates +all HTTPS requests made directly by Go, but does not authenticate requests made +through Git. + +For example: + +```plaintext +machine gitlab.example.com +login <gitlab_user_name> +password <personal_access_token> +``` + +NOTE: +On Windows, Go reads `~/_netrc` instead of `~/.netrc`. + +### Authenticate Git fetches + +If a module cannot be fetched from a proxy, Go falls back to using Git (for +GitLab projects). Git uses `.netrc` to authenticate requests. You can also +configure Git to either: + +- Embed specific credentials in the request URL. +- Use SSH instead of HTTPS, as Go always uses HTTPS to fetch Git repositories. + +```shell +# Embed credentials in any request to GitLab.com: +git config --global url."https://${user}:${personal_access_token}@gitlab.example.com".insteadOf "https://gitlab.example.com" + +# Use SSH instead of HTTPS: +git config --global url."git@gitlab.example.com".insteadOf "https://gitlab.example.com" +``` + +## Access project page with project ID + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53671) in GitLab 11.8. + +To quickly access a project from the GitLab UI using the project ID, +visit the `/projects/:id` URL in your browser or other tool accessing the project. + +## Project's landing page + +The project's landing page shows different information depending on +the project's visibility settings and user permissions. + +For public projects, and to members of internal and private projects +with [permissions to view the project's code](../permissions.md#project-members-permissions): + +- The content of a + [`README` or an index file](repository/#repository-readme-and-index-files) + is displayed (if any), followed by the list of directories in the + project's repository. +- If the project doesn't contain either of these files, the + visitor sees the list of files and directories of the repository. + +For users without permissions to view the project's code, GitLab displays: + +- The wiki homepage, if any. +- The list of issues in the project. |