debian-mirror-gitlab/doc/user/project/working_with_projects.md

---
stage: Manage
group: Workspace
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. On the top bar, select **Menu > Projects**.
1. Select **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**.

NOTE:
By default, `/explore` is visible to unauthenticated users. However, if the
[**Public** visibility level](../admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels)
is restricted, `/explore` is visible only to signed-in users.

## Explore topics

You can explore popular project topics available on GitLab. To explore project topics:

1. On the top bar, select **Menu > Projects**.
1. Select **Explore topics**.

GitLab displays a list of topics sorted by the number of associated projects.
To view projects associated with a topic, select a topic from the list.

You can assign topics to a project on the [Project Settings page](settings/index.md#topics).

If you're an instance administrator, you can administer all project topics from the
[Admin Area's Topics page](../admin_area/index.md#administering-topics).

## Create a project

To create a project in GitLab:

1. In your dashboard, select **New project** or use the **New...** **{plus-square}** icon
on the top bar. The **New project** page opens.
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. Click **Create blank project**
1. 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.
- Anyone can contribute a built-in template by following [these steps](https://about.gitlab.com/community/contribute/project-templates/).

To use a built-in template on the **New project** page:

1. Click **Create from template**
1. 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. Click **Create from template**
1. 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, on the **Create from template** page.

To use a custom project template on the **New project** page:

1. Click **Create from template**
1. 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, you don't have to sign in to the GitLab
interface to create a project and
[clone its repository](../../gitlab-basics/start-using-git.md#clone-a-repository).
You can directly push your new repository to GitLab, which creates your new project
without leaving your terminal.

To push a new project:

1. Identify the [namespace](../group/index.md#namespaces) you want to add the new
   project to, as you need this information in a future step. To determine if you have
   permission to create new projects in a namespace, view the group's page in a
   web browser and confirm the page displays a **New project** button.

   NOTE:
   As project creation permissions can have many factors, contact your
   GitLab administrator if you're unsure.

1. If you want to push using SSH, ensure you have [created a SSH key](../../ssh/index.md) and
   [added it to your GitLab account](../../ssh/index.md#add-an-ssh-key-to-your-gitlab-account).
1. Push with one of the following methods. Replace `gitlab.example.com` with the
   domain name of the machine that hosts your Git repository, `namespace` with the name of
   your namespace, and `myproject` with the name of your new project:
   - To push with SSH: `git push --set-upstream git@gitlab.example.com:namespace/myproject.git master`
   - To push with HTTPS: `git push --set-upstream https://gitlab.example.com/namespace/myproject.git master`
   Optional: to export existing repository tags, append the `--tags` flag to your `git push` command.
1. When the push completes, GitLab displays a message:

   ```plaintext
   remote: The private project namespace/myproject was created.
   ```

1. (Optional) To configure the remote, alter the command
   `git remote add origin https://gitlab.example.com/namespace/myproject.git`
   to match your namespace and project names.

You can view your new project at `https://gitlab.example.com/namespace/myproject`.
Your project's visibility is set to **Private** by default, but you can change it
in your [project's settings](../../public_access/public_access.md#change-project-visibility)).

This feature does not work for project paths that have previously been in use and
[renamed](settings/index.md#renaming-a-repository). A redirect exists over the previous project path
that causes push attempts to redirect requests to the renamed project location, instead of creating
a new project. To create a new project, use the [Web UI](#create-a-project) or the
[Projects API](../../api/projects.md#create-project).

## 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. On the top bar, select **Menu > Projects**.
1. Select **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 [Enable delayed project removal](../group/index.md#enable-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:

1. On the left sidebar, select **Project information > Activity**.
1. Select a tab to view **All** the activity, or to filter it by any of these criteria:
   - **Push events**
   - **Merge events**
   - **Issue events**
   - **Comments**
   - **Team**
   - **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://everything.curl.dev/usingcurl/netrc) 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"
```

### Fetch Go modules from Geo secondary sites

As Go modules are stored in Git repositories, you can use the [Geo](../../administration/geo/index.md)
feature that allows Git repositories to be accessed on the secondary Geo servers.

In the following examples, the primary's site domain name is `gitlab.example.com`,
and the secondary's is `gitlab-secondary.example.com`.

`go get` will initially generate some HTTP traffic to the primary, but when the module
download commences, the `insteadOf` configuration sends the traffic to the secondary.

#### Use SSH to access the Geo secondary

To fetch Go modules from the secondary using SSH:

1. Reconfigure Git on the client to send traffic for the primary to the secondary:

   ```plaintext
   git config --global url."git@gitlab-secondary.example.com".insteadOf "https://gitlab.example.com"
   git config --global url."git@gitlab-secondary.example.com".insteadOf "http://gitlab.example.com"
   ```

1. Ensure the client is set up for SSH access to GitLab repositories. This can be tested on the primary,
   and GitLab will replicate the public key to the secondary.

#### Use HTTP to access the Geo secondary

Using HTTP to fetch Go modules does not work with CI/CD job tokens, only with
persistent access tokens that are replicated to the secondary.

To fetch Go modules from the secondary using HTTP:

1. Put in place a Git `insteadOf` redirect on the client:

   ```plaintext
   git config --global url."https://gitlab-secondary.example.com".insteadOf "https://gitlab.example.com"
   ```

1. Generate a [personal access token](../profile/personal_access_tokens.md) and
   provide those credentials in the client's `~/.netrc` file:

   ```plaintext
   machine gitlab.example.com login USERNAME password TOKEN
   machine gitlab-secondary.example.com login USERNAME password TOKEN
   ```

## 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/index.md#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.