1--- 2stage: Manage 3group: Workspace 4info: "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" 5--- 6 7# Manage projects **(FREE)** 8 9Most work in GitLab is done in a [project](../../user/project/index.md). Files and 10code are saved in projects, and most features are in the scope of projects. 11 12## View projects 13 14To explore projects: 15 161. On the top bar, select **Menu > Projects**. 171. Select **Explore projects**. 18 19The **Projects** page shows a list of projects, sorted by last updated date. 20 21- To view projects with the most [stars](#star-a-project), select **Most stars**. 22- To view projects with the largest number of comments in the past month, select **Trending**. 23 24NOTE: 25The **Explore projects** tab is visible to unauthenticated users unless the 26[**Public** visibility level](../admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels) 27is restricted. Then the tab is visible only to signed-in users. 28 29### Who can view the **Projects** page 30 31When you select a project, the project landing page shows the project contents. 32 33For public projects, and members of internal and private projects 34with [permissions to view the project's code](../permissions.md#project-members-permissions), 35the project landing page shows: 36 37- A [`README` or index file](repository/index.md#readme-and-index-files). 38- A list of directories in the project's repository. 39 40For users without permission to view the project's code, the landing page shows: 41 42- The wiki homepage. 43- The list of issues in the project. 44 45### Access a project page with the project ID 46 47> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53671) in GitLab 11.8. 48 49To access a project from the GitLab UI using the project ID, 50visit the `/projects/:id` URL in your browser or other tool accessing the project. 51 52## Explore topics 53 54To explore project topics: 55 561. On the top bar, select **Menu > Projects**. 571. Select **Explore topics**. 58 59The **Projects** page shows list of topics sorted by the number of associated projects. 60To view projects associated with a topic, select a topic from the list. 61 62You can assign topics to a project on the [Project Settings page](settings/index.md#topics). 63 64If you're an instance administrator, you can administer all project topics from the 65[Admin Area's Topics page](../admin_area/index.md#administering-topics). 66 67## Create a project 68 69To create a project in GitLab: 70 711. On the top bar, select **Menu > Project**. 721. Select **Create new project**. 731. On the **New project** page, choose if you want to: 74 - Create a [blank project](#create-a-blank-project). 75 - Create a project from a: 76 - [built-in template](#create-a-project-from-a-built-in-template). 77 - [custom template](#create-a-project-from-a-custom-template). 78 - [HIPAA audit protocol template](#create-a-project-from-the-hipaa-audit-protocol-template). 79 - [Import a project](../../user/project/import/index.md) 80 from a different repository. Contact your GitLab administrator if this option is not available. 81 - [Connect an external repository to GitLab CI/CD](../../ci/ci_cd_for_external_repos/index.md). 82 83NOTE: 84For a list of words that can't be used as project names see 85[reserved project and group names](../../user/reserved_names.md). 86 87## Create a blank project 88 89To create a blank project: 90 911. On the top bar, select **Menu > Project**. 921. Select **Create new project**. 931. Select **Create blank project**. 941. Enter the project details: 95 - In the **Project name** field, enter the name of your project. You can use spaces, hyphens, 96 underscores, and emoji. You cannot use special characters. After you enter the name, 97 the **Project slug** populates. 98 - In the **Project slug** field, enter the path to your project. The GitLab instance uses the 99 slug as the URL path to the project. To change the slug, first enter the project name, 100 then change the slug. 101 - In the **Project description (optional)** field, enter the description of your project's dashboard. 102 - To modify the project's [viewing and access rights](../../public_access/public_access.md) for 103 users, change the **Visibility Level**. 104 - To create README file so that the Git repository is initialized, has a default branch, and 105 can be cloned, select **Initialize repository with a README**. 106 - To analyze the source code in the project for known security vulnerabilities, 107 select **Enable Static Application Security Testing (SAST)**. 1081. Select **Create project**. 109 110## Create a project from a built-in template 111 112A built-in project template populates a new project with files to get you started. 113Built-in templates are sourced from the following groups: 114 115- [`project-templates`](https://gitlab.com/gitlab-org/project-templates) 116- [`pages`](https://gitlab.com/pages) 117 118Anyone can contribute a built-in template by following [these steps](https://about.gitlab.com/community/contribute/project-templates/). 119 120To create a project from a built-in template: 121 1221. On the top bar, select **Menu > Project**. 1231. Select **Create new project**. 1241. Select **Create from template**. 1251. Select the **Built-in** tab. 1261. From the list of templates: 127 - To view a preview of the template, select **Preview**. 128 - To use a template for the project, select **Use template**. 1291. Enter the project details: 130 - In the **Project name** field, enter the name of your project. You can use spaces, hyphens, 131 underscores, and emoji. You cannot use special characters. After you enter the name, 132 the **Project slug** populates. 133 - In the **Project slug** field, enter the path to your project. The GitLab instance uses the 134 slug as the URL path to the project. To change the slug, first enter the project name, 135 then change the slug. 136 - In the **Project description (optional)** field, enter the description of your project's dashboard. 137 - To modify the project's [viewing and access rights](../../public_access/public_access.md) for users, 138 change the **Visibility Level**. 1391. Select **Create project**. 140 141## Create a project from a custom template **(PREMIUM)** 142 143> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6860) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2. 144 145Custom project templates are available at: 146 147- The [instance-level](../../user/admin_area/custom_project_templates.md) 148- The [group-level](../../user/group/custom_project_templates.md) 149 1501. On the top bar, select **Menu > Project**. 1511. Select **Create new project**. 1521. Select **Create from template**. 1531. Select the **Instance** or **Group** tab. 1541. From the list of templates: 155 - To view a preview of the template, select **Preview**. 156 - To use a template for the project, select **Use template**. 1571. Enter the project details: 158 - In the **Project name** field, enter the name of your project. You can use spaces, hyphens, 159 underscores, and emoji. You cannot use special characters. After you enter the name, 160 the **Project slug** populates. 161 - In the **Project slug** field, enter the path to your project. The GitLab instance uses the 162 slug as the URL path to the project. To change the slug, first enter the project name, 163 then change the slug. 164 - The description of your project's dashboard in the **Project description (optional)** field. 165 - To modify the project's [viewing and access rights](../../public_access/public_access.md) for users, 166 change the **Visibility Level**. 1671. Select **Create project**. 168 169## Create a project from the HIPAA Audit Protocol template **(ULTIMATE)** 170 171> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13756) in GitLab 12.10 172 173The HIPAA Audit Protocol template contains issues for audit inquiries in the 174HIPAA Audit Protocol published by the U.S Department of Health and Human Services. 175 176To create a project from the HIPAA Audit Protocol template: 177 1781. On the top bar, select **Menu > Project**. 1791. Select **Create new project**. 1801. Select **Create from template**. 1811. Select the **Built-in** tab. 1821. Locate the **HIPAA Audit Protocol** template: 183 - To view a preview of the template, select **Preview**. 184 - To use the template for the project, select **Use template**. 1851. Enter the project details: 186 - In the **Project name** field, enter the name of your project. You can use spaces, hyphens, 187 underscores, and emoji. You cannot use special characters. After you enter the name, 188 the **Project slug** populates. 189 - In the **Project slug** field, enter the path to your project. The GitLab instance uses the 190 slug as the URL path to the project. To change the slug, first enter the project name, 191 then change the slug. 192 - In the **Project description (optional)** field, enter the description of your project's dashboard. 193 - To modify the project's [viewing and access rights](../../public_access/public_access.md) for users, 194 change the **Visibility Level**. 1951. Select **Create project**. 196 197## Push to create a new project 198 199> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/26388) in GitLab 10.5. 200 201Use `git push` to push a local project repository to GitLab. After you push a repository, 202GitLab creates your project in your chosen namespace. 203 204You cannot use `git push` to create projects with project paths that: 205 206- Have previously been used. 207- Have been [renamed](settings/index.md#renaming-a-repository). 208 209Previously used project paths have a redirect. The redirect causes push attempts to redirect requests 210to the renamed project location, instead of creating a new project. To create a new project for a previously 211used or renamed project, use the [UI](#create-a-project) or the [Projects API](../../api/projects.md#create-project). 212 213Prerequisites: 214 215- To push with SSH, you must have [an SSH key](../../ssh/index.md) that is 216[added to your GitLab account](../../ssh/index.md#add-an-ssh-key-to-your-gitlab-account). 217- You must have permission to add new projects to a namespace. To check if you have permission: 218 219 1. On the top bar, select **Menu > Project**. 220 1. Select **Groups**. 221 1. Select a group. 222 1. Confirm that **New project** is visible in the upper right 223 corner. Contact your GitLab 224 administrator if you require permission. 225 226To push your repository and create a project: 227 2281. Push with SSH or HTTPS: 229 - To push with SSH: 230 231 ```shell 232 git push --set-upstream git@gitlab.example.com:namespace/myproject.git master 233 ``` 234 235 - To push with HTTPS: 236 237 ```shell 238 git push --set-upstream https://gitlab.example.com/namespace/myproject.git master 239 ``` 240 241 - For `gitlab.example.com`, use the domain name of the machine that hosts your Git repository. 242 - For `namespace`, use the name of your [namespace](../group/index.md#namespaces). 243 - For `myproject`, use the name of your project. 244 - Optional. To export existing repository tags, append the `--tags` flag to your `git push` command. 2451. Optional. To configure the remote: 246 247 ```shell 248 git remote add origin https://gitlab.example.com/namespace/myproject.git 249 ``` 250 251When the push completes, GitLab displays the message: 252 253```shell 254remote: The private project namespace/myproject was created. 255``` 256 257To view your new project, go to `https://gitlab.example.com/namespace/myproject`. 258Your project's visibility is set to **Private** by default. To change project visibility, adjust your 259[project's settings](../../public_access/public_access.md#change-project-visibility). 260 261## Star a project 262 263You can add a star to projects you use frequently to make them easier to find. 264 265To add a star to a project: 266 2671. On the top bar, select **Menu > Project**. 2681. Select **Your projects** or **Explore projects**. 2691. Select a project. 2701. In the upper right corner of the page, select **Star**. 271 272## View starred projects 273 2741. On the top bar, select **Menu > Project**. 2751. Select **Starred projects**. 2761. GitLab displays information about your starred projects, including: 277 278 - Project description, including name, description, and icon. 279 - Number of times this project has been starred. 280 - Number of times this project has been forked. 281 - Number of open merge requests. 282 - Number of open issues. 283 284## Delete a project 285 286After you delete a project, projects in personal namespaces are deleted immediately. To delay deletion of projects in a group 287you can [enable delayed project removal](../group/index.md#enable-delayed-project-deletion). 288 289To delete a project: 290 2911. On the top bar, select **Menu > Project**. 2921. Select **Your projects** or **Explore projects**. 2931. Select a project. 2941. Select **Settings > General**. 2951. Expand the **Advanced** section. 2961. Scroll down to the **Delete project** section. 2971. Select **Delete project** 2981. Confirm this action by completing the field. 299 300## View project activity 301 302To view the activity of a project: 303 3041. On the top bar, select **Menu > Project**. 3051. Select **Your projects** or **Explore projects**. 3061. Select a project. 3071. On the left sidebar, select **Project information > Activity**. 3081. Select a tab to view the type of project activity. 309 310## Leave a project 311 312If you leave a project you are no longer a project 313member and cannot contribute. 314 315To leave a project: 316 3171. On the top bar, select **Menu > Project**. 3181. Select **Your projects** or **Explore projects**. 3191. Select a project. 3201. Select **Leave project**. The **Leave project** option only displays 321on the project dashboard when a project is part of a group under a 322[group namespace](../group/index.md#namespaces). 323 324## Use a project as a Go package 325 326Prerequisites: 327 328- Contact your administrator to enable the [GitLab Go Proxy](../packages/go_proxy/index.md). 329- To use a private project in a subgroup as a Go package, you must [authenticate Go requests](#authenticate-go-requests-to-private-projects). Go requests that are not authenticated cause 330`go get` to fail. You don't need to authenticate Go requests for projects that are not in subgroups. 331 332To use a project as a Go package, use the `go get` and `godoc.org` discovery requests. You can use the meta tags: 333 334- [`go-import`](https://pkg.go.dev/cmd/go#hdr-Remote_import_paths) 335- [`go-source`](https://github.com/golang/gddo/wiki/Source-Code-Links) 336 337### Authenticate Go requests to private projects 338 339Prerequisites: 340 341- Your GitLab instance must be accessible with HTTPS. 342- You must have a [personal access token](../profile/personal_access_tokens.md). 343 344To authenticate Go requests, create a [`.netrc`](https://everything.curl.dev/usingcurl/netrc) file with the following information: 345 346```plaintext 347machine gitlab.example.com 348login <gitlab_user_name> 349password <personal_access_token> 350``` 351 352On Windows, Go reads `~/_netrc` instead of `~/.netrc`. 353 354The `go` command does not transmit credentials over insecure connections. It authenticates 355HTTPS requests made by Go, but does not authenticate requests made 356through Git. 357 358### Authenticate Git requests 359 360If Go cannot fetch a module from a proxy, it uses Git. Git uses a `.netrc` file to authenticate requests, but you can 361configure other authentication methods. 362 363Configure Git to either: 364 365- Embed credentials in the request URL: 366 367 ```shell 368 git config --global url."https://${user}:${personal_access_token}@gitlab.example.com".insteadOf "https://gitlab.example.com" 369 ``` 370 371- Use SSH instead of HTTPS: 372 373 ```shell 374 git config --global url."git@gitlab.example.com".insteadOf "https://gitlab.example.com" 375 ``` 376 377### Disable Go module fetching for private projects 378 379To [fetch modules or packages](../../development/go_guide/dependencies.md#fetching), Go uses 380the [environment variables](../../development/go_guide/dependencies.md#proxies): 381 382- `GOPRIVATE` 383- `GONOPROXY` 384- `GONOSUMDB` 385 386To disable fetching: 387 3881. Disable `GOPRIVATE`: 389 - To disable queries for one project, disable `GOPRIVATE=gitlab.example.com/my/private/project`. 390 - To disable queries for all projects on GitLab.com, disable `GOPRIVATE=gitlab.example.com`. 3911. Disable proxy queries in `GONOPROXY`. 3921. Disable checksum queries in `GONOSUMDB`. 393 394- If the module name or its prefix is in `GOPRIVATE` or `GONOPROXY`, Go does not query module 395proxies. 396- If the module name or its prefix is in `GONOPRIVATE` or `GONOSUMDB`, Go does not query 397Checksum databases. 398 399### Fetch Go modules from Geo secondary sites 400 401Use [Geo](../../administration/geo/index.md) to access Git repositories that contain Go modules 402on secondary Geo servers. 403 404You can use SSH or HTTP to access the Geo secondary server. 405 406#### Use SSH to access the Geo secondary server 407 408To access the Geo secondary server with SSH: 409 4101. Reconfigure Git on the client to send traffic for the primary to the secondary: 411 412 ```shell 413 git config --global url."git@gitlab-secondary.example.com".insteadOf "https://gitlab.example.com" 414 git config --global url."git@gitlab-secondary.example.com".insteadOf "http://gitlab.example.com" 415 ``` 416 417 - For `gitlab.example.com`, use the primary site domain name. 418 - For `gitlab-secondary.example.com`, use the secondary site domain name. 419 4201. Ensure the client is set up for SSH access to GitLab repositories. You can test this on the primary, 421 and GitLab replicates the public key to the secondary. 422 423The `go get` request generates HTTP traffic to the primary Geo server. When the module 424download starts, the `insteadOf` configuration sends the traffic to the secondary Geo server. 425 426#### Use HTTP to access the Geo secondary 427 428You must use persistent access tokens that replicate to the secondary server. You cannot use 429CI/CD job tokens to fetch Go modules with HTTP. 430 431To access the Geo secondary server with HTTP: 432 4331. Add a Git `insteadOf` redirect on the client: 434 435 ```shell 436 git config --global url."https://gitlab-secondary.example.com".insteadOf "https://gitlab.example.com" 437 ``` 438 439 - For `gitlab.example.com`, use the primary site domain name. 440 - For `gitlab-secondary.example.com`, use the secondary site domain name. 441 4421. Generate a [personal access token](../profile/personal_access_tokens.md) and 443 add the credentials in the client's `~/.netrc` file: 444 445 ```shell 446 machine gitlab.example.com login USERNAME password TOKEN 447 machine gitlab-secondary.example.com login USERNAME password TOKEN 448 ``` 449 450The `go get` request generates HTTP traffic to the primary Geo server. When the module 451download starts, the `insteadOf` configuration sends the traffic to the secondary Geo server. 452 453## Related topics 454 455- [Import a project](../../user/project/import/index.md). 456- [Connect an external repository to GitLab CI/CD](../../ci/ci_cd_for_external_repos/index.md). 457- [Fork a project](repository/forking_workflow.md#creating-a-fork). 458- [Adjust project visibility and access levels](settings/index.md#sharing-and-permissions). 459