From 1b47b087e6c36f8dc38162d7712f01173c7b85cf Mon Sep 17 00:00:00 2001 From: GitLab Bot Date: Fri, 10 Dec 2021 00:13:05 +0000 Subject: Add latest changes from gitlab-org/gitlab@master --- doc/administration/audit_events.md | 3 +- doc/administration/incoming_email.md | 2 +- doc/administration/index.md | 2 +- .../cicd/cicd_reference_documentation_guide.md | 181 +++++++------- doc/gitlab-basics/index.md | 2 +- doc/update/deprecations.md | 8 + doc/user/project/description_templates.md | 2 +- .../project/issues/img/new_issue_from_email.png | Bin 4259 -> 0 bytes .../issues/img/new_issue_from_issue_board.png | Bin 20063 -> 0 bytes .../issues/img/new_issue_from_open_issue_v13_6.png | Bin 25667 -> 0 bytes .../img/new_issue_from_projects_dashboard.png | Bin 9674 -> 0 bytes .../issues/img/new_issue_from_tracker_list.png | Bin 19632 -> 0 bytes doc/user/project/issues/img/new_issue_v13_1.png | Bin 69721 -> 0 bytes ...oject_from_group_level_issue_tracker_v13_11.png | Bin 8863 -> 0 bytes doc/user/project/issues/index.md | 2 +- doc/user/project/issues/managing_issues.md | 268 +++++++++++++-------- doc/user/project/working_with_projects.md | 229 +++++++++--------- 17 files changed, 393 insertions(+), 306 deletions(-) delete mode 100644 doc/user/project/issues/img/new_issue_from_email.png delete mode 100644 doc/user/project/issues/img/new_issue_from_issue_board.png delete mode 100644 doc/user/project/issues/img/new_issue_from_open_issue_v13_6.png delete mode 100644 doc/user/project/issues/img/new_issue_from_projects_dashboard.png delete mode 100644 doc/user/project/issues/img/new_issue_from_tracker_list.png delete mode 100644 doc/user/project/issues/img/new_issue_v13_1.png delete mode 100644 doc/user/project/issues/img/select_project_from_group_level_issue_tracker_v13_11.png (limited to 'doc') diff --git a/doc/administration/audit_events.md b/doc/administration/audit_events.md index 71eee78c168..06ad16bbcba 100644 --- a/doc/administration/audit_events.md +++ b/doc/administration/audit_events.md @@ -9,8 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w GitLab offers a way to view the changes made within the GitLab server for owners and administrators on a [paid plan](https://about.gitlab.com/pricing/). -GitLab system administrators can also take advantage of the logs located on the -file system. See [the logs system documentation](logs.md#audit_jsonlog) for more details. +GitLab system administrators can also view all audit events by accessing the [`audit_json.log` file](logs.md#audit_jsonlog). You can: diff --git a/doc/administration/incoming_email.md b/doc/administration/incoming_email.md index 6b390cfc77a..62fbf9e7166 100644 --- a/doc/administration/incoming_email.md +++ b/doc/administration/incoming_email.md @@ -10,7 +10,7 @@ GitLab has several features based on receiving incoming email messages: - [Reply by Email](reply_by_email.md): allow GitLab users to comment on issues and merge requests by replying to notification email. -- [New issue by email](../user/project/issues/managing_issues.md#new-issue-via-email): +- [New issue by email](../user/project/issues/managing_issues.md#by-sending-an-email): allow GitLab users to create a new issue by sending an email to a user-specific email address. - [New merge request by email](../user/project/merge_requests/creating_merge_requests.md#by-sending-an-email): diff --git a/doc/administration/index.md b/doc/administration/index.md index ef9c56c1615..d78c9d80b5f 100644 --- a/doc/administration/index.md +++ b/doc/administration/index.md @@ -133,7 +133,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. - Instances. - [Auditor users](auditor_users.md): Users with read-only access to all projects, groups, and other resources on the GitLab instance. - [Incoming email](incoming_email.md): Configure incoming emails to allow - users to [reply by email](reply_by_email.md), create [issues by email](../user/project/issues/managing_issues.md#new-issue-via-email) and + users to [reply by email](reply_by_email.md), create [issues by email](../user/project/issues/managing_issues.md#by-sending-an-email) and [merge requests by email](../user/project/merge_requests/creating_merge_requests.md#by-sending-an-email), and to enable [Service Desk](../user/project/service_desk.md). - [Postfix for incoming email](reply_by_email_postfix_setup.md): Set up a basic Postfix mail server with IMAP authentication on Ubuntu for incoming diff --git a/doc/development/cicd/cicd_reference_documentation_guide.md b/doc/development/cicd/cicd_reference_documentation_guide.md index aa3888cd866..892c9814c7f 100644 --- a/doc/development/cicd/cicd_reference_documentation_guide.md +++ b/doc/development/cicd/cicd_reference_documentation_guide.md @@ -9,14 +9,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w The CI/CD YAML reference uses a standard style to make it easier to use and update. The reference information should be kept as simple as possible, and expanded details -and examples documented in a separate page. +and examples should be documented on other pages. ## YAML reference structure Every YAML keyword must have its own section in the reference. The sections should be nested so that the keywords follow a logical tree structure. For example: -```plaintext +```markdown ### `artifacts` #### `artifacts:name` #### `artifacts:paths` @@ -27,128 +27,127 @@ be nested so that the keywords follow a logical tree structure. For example: ## YAML reference style -Each keyword entry in the reference should use the following style: +Each keyword entry in the reference: -````markdown -### `keyword-name` - -> Version information - -Keyword description and main details. - -**Keyword type**: - -**Possible inputs**: +- Must have a simple introductory section. The introduction should give the fundamental + information needed to use the keyword. Advanced details and tasks should be in + feature pages, not the reference page. -**Example of `keyword-name`**: +- Must use the keyword name as the title, for example: -(optional) In this example... + ```markdown + ### `artifacts` + ``` -(optional) **Additional details**: +- Should include the following sections: + - [Keyword type](#keyword-type) + - [Possible inputs](#possible-inputs) + - [Example of `keyword-name`](#example-of-keyword-name) +- (Optional) Can also include the following sections when needed: + - [Additional details](#additional-details) + - [Related topics](#related-topics) -- List of extra details. +The keyword name must always be in backticks without a final `:`, like `artifacts`, not `artifacts:`. +If it is a subkey of another keyword, write out all the subkeys to the "parent" key the first time it +is used, like `artifacts:reports:dast`. Afterwards, you can use just the subkey alone, like `dast`. -(optional) **Related topics**: +## Keyword type -- List of links to topics related to the keyword. -```` - -- ``### `keyword-name` ``: The keyword name must always be in backticks. - If it is a subkey of another keyword, write out all the keywords, with each separated - by `:`, for example: `artifacts:reports:dast`. - -- ``> Version information``: The [version history details](../documentation/styleguide/index.md#version-text-in-the-version-history). - If the keyword is feature flagged, see the [feature flag documentation guide](../documentation/feature_flags.md) - as well. +The keyword can be either a job or global keyword. If it can be used in a `default` +section, make not of that as well, for example: -- `Keyword description and main details.`: A simple description of the keyword, and - how to use it. Additional use cases and benefits should be added to a page outside - the reference document. Link to that document in this section. +- `**Keyword type**: Global keyword.` +- `**Keyword type**: Job keyword. You can use it only as part of a job.` +- ``**Keyword type**: Job keyword. You can use it only as part of a job or in the [`default:` section](#default).`` -- `**Keyword type**:`: Most keywords are defined at the job level, like `script`, - or at the pipeline level, like `stages`. Add the appropriate line: +### Possible inputs - - `**Keyword type**: Job keyword. You can use it only as part of a job.` - - `**Keyword type**: Pipeline keyword. You cannot use it as part of a job.` +List all the possible inputs, and any extra details about the inputs, such as defaults +or changes due to different GitLab versions, for example: - If a keyword can be used at both the job and pipeline level, like `variables`, - explain it in detail instead of using the pre-written lines above. +```markdown +**Possible inputs**: -- `**Possible inputs**:`: Explain in detail which inputs the keyword can accept. - You can add the details in a sentence, paragraph, or list. +- `true` (default if not defined) or `false`. +``` -- ``**Example of `keyword-name`**:``: An example configuration that uses the keyword. - Do not add extra keywords that are not required to understand the behavior. +```markdown +**Possible inputs**: -- (optional) `In this example...`: If the example needs extra details, - add the clarification text below the example. +- A single exit code. +- An array of exit codes. +``` -- (optional) `**Additional details**:` If there are any caveats or extra details you - want to document along with the keyword, add each one as a list item here. +```markdown +**Possible inputs**: -- (optional) `**Related topics**:` If there are any other keywords or pages that - relate to this keyword, add these links as list items here. +- A string with the long description. +- The path to a file that contains the description. Introduced in [GitLab 13.7](https://gitlab.com/gitlab-org/release-cli/-/merge_requests/67). + - The file location must be relative to the project directory (`$CI_PROJECT_DIR`). + - If the file is a symbolic link, it must be in the `$CI_PROJECT_DIR`. + - The `./path/to/file` and filename can't contain spaces. +``` -### YAML reference style example +### Example of `keyword-name` -See the [`only:changes` / `except:changes`](../../ci/yaml/index.md#onlychanges--exceptchanges) -documentation for an example of the YAML reference style. The following example is a -shortened version of that documentation's Markdown: +An example of the keyword. Use the minimum number of other keywords necessary +to make the example valid. If the example needs explanation, add it after the example, +for example: ````markdown -#### `only:changes` / `except:changes` +**Example of `dast`**: -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/19232) in GitLab 11.4. - -Use the `changes` keyword with `only` to run a job, or with `except` to skip a job, -when a Git push event modifies a file. +```yaml +stages: + - build + - dast -Use `changes` in pipelines with the following refs: +include: + - template: DAST.gitlab-ci.yml -- `branches` -- `external_pull_requests` -- `merge_requests` (see additional details about [using `only:changes` with pipelines for merge requests](../jobs/job_control.md#use-onlychanges-with-pipelines-for-merge-requests)) +dast: + dast_configuration: + site_profile: "Example Co" + scanner_profile: "Quick Passive Test" +``` -**Keyword type**: Job keyword. You can use it only as part of a job. +In this example, the `dast` job extends the `dast` configuration added with the `include:` keyword +to select a specific site profile and scanner profile. +```` -**Possible inputs**: An array including any number of: +### Additional details -- Paths to files. -- Wildcard paths for single directories, for example `path/to/directory/*`, or a directory - and all its subdirectories, for example `path/to/directory/**/*`. +The additional details should be an unordered list of extra information that is +useful to know, but not important enough to put in the introduction. This information +can include changes introduced in different GitLab versions. For example: -**Example of `only:changes`**: +```markdown +**Additional details**: -```yaml -docker build: - script: docker build -t my-image:$CI_COMMIT_REF_SLUG . - only: - refs: - - branches - changes: - - Dockerfile - - docker/scripts/* - - dockerfiles/**/* +- The expiration time period begins when the artifact is uploaded and stored on GitLab. + If the expiry time is not defined, it defaults to the [instance wide setting](../../user/admin_area/settings/continuous_integration.md#default-artifacts-expiration). +- To override the expiration date and protect artifacts from being automatically deleted: + - Select **Keep** on the job page. + - [In GitLab 13.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/22761), set the value of + `expire_in` to `never`. ``` -In this example, `docker build` only runs in branch pipelines, and only if at least one of -these files changed: +### Related topics -- `Dockerfile`. -- Any file in `docker/scripts` -- Any file in `dockerfiles/` or any of its subdirectories. +The related topics should be an unordered list of crosslinks to related pages, including: -**Additional details**: +- Specific tasks that you can accomplish with the keyword. +- Advanced examples of the keyword. +- Other related keywords that can be used together with this keyword. -- If you use refs other than `branches`, `external_pull_requests`, or `merge_requests`, - `changes` can't determine if a given file is new or old and always returns `true`. -- If you use `only: changes` with other refs, jobs ignore the changes and always run. -- If you use `except: changes` with other refs, jobs ignore the changes and never run. +For example: +```markdown **Related topics**: -- [`only: changes` and `except: changes` examples](../jobs/job_control.md#onlychanges--exceptchanges-examples). -- If you use `changes` with [only allow merge requests to be merged if the pipeline succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md#only-allow-merge-requests-to-be-merged-if-the-pipeline-succeeds), - you should [also use `only:merge_requests`](../jobs/job_control.md#use-onlychanges-with-pipelines-for-merge-requests). -- Use `changes` with [scheduled pipelines](../jobs/job_control.md#use-onlychanges-with-scheduled-pipelines). -```` +- You can specify a [fallback cache key](../caching/index.md#use-a-fallback-cache-key) + to use if the specified `cache:key` is not found. +- You can [use multiple cache keys](../caching/index.md#use-multiple-caches) in a single job. +- See the [common `cache` use cases](../caching/index.md#common-use-cases-for-caches) for more + `cache:key` examples. +``` diff --git a/doc/gitlab-basics/index.md b/doc/gitlab-basics/index.md index 5e4ec0e8c51..5ba5366eafa 100644 --- a/doc/gitlab-basics/index.md +++ b/doc/gitlab-basics/index.md @@ -29,7 +29,7 @@ The following are guides to basic GitLab functionality: - [Feature branch workflow](feature_branch_workflow.md). - [Fork a project](../user/project/repository/forking_workflow.md#creating-a-fork), to duplicate projects so they can be worked on in parallel. - [Add a file](add-file.md), to add new files to a project's repository. -- [Create an issue](../user/project/issues/managing_issues.md#create-a-new-issue), +- [Create an issue](../user/project/issues/managing_issues.md#create-an-issue), to start collaborating within a project. - [Create a merge request](../user/project/merge_requests/creating_merge_requests.md), to request changes made in a branch be merged into a project's repository. diff --git a/doc/update/deprecations.md b/doc/update/deprecations.md index 066c91b7dd9..20c6d692cf6 100644 --- a/doc/update/deprecations.md +++ b/doc/update/deprecations.md @@ -116,6 +116,14 @@ Long term service and support (LTSS) for SUSE Linux Enterprise Server (SLES) 12 Announced: 2021-11-22 +### Deprecation of bundler-audit Dependency Scanning tool + +As of 14.6 bundler-audit is being deprecated from Dependency Scanning. It will continue to be in our CI/CD template while deprecated. We are removing bundler-audit from Dependency Scanning on May 22, 2022 in 15.0. After this removal Ruby scanning functionality will not be affected as it is still being covered by Gemnasium. + +If you have explicitly excluded bundler-audit using DS_EXCLUDED_ANALYZERS you will need to clean up (remove the reference) in 15.0. If you have customized your pipeline's Dependency Scanning configuration, for example to edit the `bundler-audit-dependency_scanning` job, you will want to switch to gemnasium-dependency_scanning before removal in 15.0, to prevent your pipeline from failing. If you have not used the DS_EXCLUDED_ANALYZERS to reference bundler-audit, or customized your template specifically for bundler-audit, you will not need to take action. + +Announced: 2021-12-22 + ### GitLab Serverless [GitLab Serverless](https://docs.gitlab.com/ee/user/project/clusters/serverless/) is a feature set to support Knative-based serverless development with automatic deployments and monitoring. diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 5b19a54bd91..66e5931fa4c 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -71,7 +71,7 @@ To create the `.gitlab/issue_templates` directory: 1. Select **New directory**. 1. Name your directory `issue_templates` and commit to your default branch. -To check if this has worked correctly, [create a new issue](issues/managing_issues.md#create-a-new-issue) +To check if this has worked correctly, [create a new issue](issues/managing_issues.md#create-an-issue) and see if you can choose a description template. ## Create a merge request template diff --git a/doc/user/project/issues/img/new_issue_from_email.png b/doc/user/project/issues/img/new_issue_from_email.png deleted file mode 100644 index 6da899ea37c..00000000000 Binary files a/doc/user/project/issues/img/new_issue_from_email.png and /dev/null differ diff --git a/doc/user/project/issues/img/new_issue_from_issue_board.png b/doc/user/project/issues/img/new_issue_from_issue_board.png deleted file mode 100644 index 30a1ffb9011..00000000000 Binary files a/doc/user/project/issues/img/new_issue_from_issue_board.png and /dev/null differ diff --git a/doc/user/project/issues/img/new_issue_from_open_issue_v13_6.png b/doc/user/project/issues/img/new_issue_from_open_issue_v13_6.png deleted file mode 100644 index 902aa40614a..00000000000 Binary files a/doc/user/project/issues/img/new_issue_from_open_issue_v13_6.png and /dev/null differ diff --git a/doc/user/project/issues/img/new_issue_from_projects_dashboard.png b/doc/user/project/issues/img/new_issue_from_projects_dashboard.png deleted file mode 100644 index 474ca2b45c0..00000000000 Binary files a/doc/user/project/issues/img/new_issue_from_projects_dashboard.png and /dev/null differ diff --git a/doc/user/project/issues/img/new_issue_from_tracker_list.png b/doc/user/project/issues/img/new_issue_from_tracker_list.png deleted file mode 100644 index 66793cb44fa..00000000000 Binary files a/doc/user/project/issues/img/new_issue_from_tracker_list.png and /dev/null differ diff --git a/doc/user/project/issues/img/new_issue_v13_1.png b/doc/user/project/issues/img/new_issue_v13_1.png deleted file mode 100644 index a66846c234e..00000000000 Binary files a/doc/user/project/issues/img/new_issue_v13_1.png and /dev/null differ diff --git a/doc/user/project/issues/img/select_project_from_group_level_issue_tracker_v13_11.png b/doc/user/project/issues/img/select_project_from_group_level_issue_tracker_v13_11.png deleted file mode 100644 index 4612ae254d4..00000000000 Binary files a/doc/user/project/issues/img/select_project_from_group_level_issue_tracker_v13_11.png and /dev/null differ diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index c535d16bc0f..85c30fa4ae5 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -29,7 +29,7 @@ To learn how the GitLab Strategic Marketing department uses GitLab issues with [ ## Related topics -- [Create issues](managing_issues.md#create-a-new-issue) +- [Create issues](managing_issues.md#create-an-issue) - [Create an issue from a template](../../project/description_templates.md#use-the-templates) - [Edit issues](managing_issues.md#edit-an-issue) - [Move issues](managing_issues.md#moving-issues) diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index d357f45b1e7..0f02eec0ce9 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -4,148 +4,228 @@ group: Project Management 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 --- -# Managing issues **(FREE)** +# Manage issues **(FREE)** [GitLab Issues](index.md) are the fundamental medium for collaborating on ideas and planning work in GitLab. -Key actions for issues include: +## Create an issue -- [Creating issues](#create-a-new-issue) -- [Moving issues](#moving-issues) -- [Closing issues](#closing-issues) -- [Deleting issues](#deleting-issues) -- [Promoting issues](#promote-an-issue-to-an-epic) **(PREMIUM)** - -## Create a new issue - -When you create a new issue, you are prompted to enter the fields of the issue. +When you create an issue, you are prompted to enter the fields of the issue. If you know the values you want to assign to an issue, you can use [quick actions](../quick_actions.md) to enter them. -While creating an issue, you can associate it to an existing epic from current group by -selecting it using **Epic** dropdown. - -### Accessing the New Issue form - -There are many ways to get to the New Issue form from a project's page: +You can create an issue in many ways in GitLab: -- Navigate to your **Project's Dashboard** > **Issues** > **New Issue**: +- [From a project](#from-a-project) +- [From a group](#from-a-group) +- [From another issue](#from-another-issue) +- [From an issue board](#from-an-issue-board) +- [By sending an email](#by-sending-an-email) +- Using a URL with prefilled fields +- [Using Service Desk](#using-service-desk) - ![New issue from the issue list view](img/new_issue_from_tracker_list.png) +### From a project -- From an **open issue** in your project, click the vertical ellipsis (**{ellipsis_v}**) button - to open a dropdown menu, and then click **New Issue** to create a new issue in the same project: +Prerequisites: - ![New issue from an open issue](img/new_issue_from_open_issue_v13_6.png) +- You must have at least the [Guest role](../../permissions.md) for the project. -- From your **Project's Dashboard**, click the plus sign (**+**) to open a dropdown - menu with a few options. Select **New Issue** to create an issue in that project: +To create an issue: - ![New issue from a project's dashboard](img/new_issue_from_projects_dashboard.png) +1. On the top bar, select **Menu > Projects** and find your project. +1. Either: -- From an **issue board**, create a new issue by clicking on the plus sign (**+**) at the top of a list. - It opens a new issue for that project, pre-labeled with its respective list. + - On the left sidebar, select **Issues**, and then, in the top right corner, select **New issue**. + - On the top bar, select the plus sign (**{plus-square}**) and then, under **This project**, + select **New issue**. - ![From the issue board](img/new_issue_from_issue_board.png) +1. Complete the [fields](#fields-in-the-new-issue-form). +1. Select **Create issue**. -### Elements of the New Issue form +The newly created issue opens. -> Ability to add the new issue to an epic [was introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13847) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.1. +### From a group -![New issue from the issues list](img/new_issue_v13_1.png) +Issues belong to projects, but when you're in a group, you can access and create issues that belong +to the projects in the group. -When you're creating a new issue, these are the fields you can fill in: - -- Title -- Description -- Checkbox to make the issue [confidential](confidential_issues.md) -- Assignee -- Weight -- [Epic](../../group/epics/index.md) -- Due date -- Milestone -- Labels +Prerequisites: -### New issue from the group-level issue tracker +- You must have at least the [Guest role](../../permissions.md) for a project in the group. -To visit the issue tracker for all projects in your group: +To create an issue from a group: -1. Go to the group dashboard. +1. On the top bar, select **Menu > Groups** and find your group. 1. On the left sidebar, select **Issues**. -1. In the top-right, select the **Select project to create issue** button. +1. In the top right corner, select **Select project to create issue**. 1. Select the project you'd like to create an issue for. The button now reflects the selected project. -1. Select the button to create an issue in the selected project. +1. Select **New issue in ``**. +1. Complete the [fields](#fields-in-the-new-issue-form). +1. Select **Create issue**. -![Select project to create issue](img/select_project_from_group_level_issue_tracker_v13_11.png) +The newly created issue opens. The project you selected most recently becomes the default for your next visit. -This should save you a lot of time and clicks, if you mostly create issues for the same project. +This can save you a lot of time and clicks, if you mostly create issues for the same project. -### New issue via Service Desk +### From another issue -Enable [Service Desk](../service_desk.md) for your project and offer email support. -Now, when your customer sends a new email, a new issue can be created in -the appropriate project and followed up from there. +> New issue becoming linked to the issue of origin [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68226) in GitLab 14.3. -### New issue via email +You can create a new issue from an existing one. The two issues can then be marked as related. -A link to **Email a new issue to this project** is displayed at the bottom of a project's -**Issues List** page. The link is shown only if your GitLab instance has [incoming email](../../../administration/incoming_email.md) -configured and there is at least one issue in the issue list. +Prerequisites: -![Bottom of a project issues page](img/new_issue_from_email.png) +- You must have at least the [Guest role](../../permissions.md) for the project. -When you click this link, an email address is generated and displayed, which should be used -by **you only**, to create issues in this project. You can save this address as a -contact in your email client for quick access. +To create an issue from another issue: -WARNING: -This is a private email address, generated just for you. **Keep it to yourself**, -as anyone who knows it can create issues or merge requests as if they -were you. If the address is compromised, or you want to regenerate it, -click **Email a new issue to this project**, followed by **reset it**. +1. In an existing issue, select the vertical ellipsis (**{ellipsis_v}**). +1. Select **New issue**. +1. Complete the [fields](#fields-in-the-new-issue-form). + The new issue's description is prefilled with `Related to #123`, where `123` is the ID of the + issue of origin. If you keep this mention in the description, the two issues become + [linked](related_issues.md). +1. Select **Create issue**. + +The newly created issue opens. + +### From an issue board -Sending an email to this address creates a new issue associated with your account for -this project, where: +You can create a new issue from an [issue board](../issue_board.md). -- The email subject becomes the issue title. -- The email body becomes the issue description. -- [Markdown](../../markdown.md) and [quick actions](../quick_actions.md) are supported. +Prerequisites: -NOTE: -In GitLab 11.7, we updated the format of the generated email address. However the -older format is still supported, allowing existing aliases or contacts to continue working. +- You must have at least the [Guest role](../../permissions.md) for the project. -### New issue via URL with prefilled fields +To create an issue from a project issue board: + +1. On the top bar, select **Menu > Projects** and find your project. +1. Select **Issues > Boards**. +1. At the top of a board list, select **New issue** (**{plus-square}**). +1. Enter the issue's title. +1. Select **Create issue**. + +To create an issue from a group issue board: + +1. On the top bar, select **Menu > Groups** and find your group. +1. Select **Issues > Boards**. +1. At the top of a board list, select **New issue** (**{plus-square}**). +1. Enter the issue's title. +1. Under **Projects**, select the project in the group that the issue should belong to. +1. Select **Create issue**. + +The issue is created and shows up in the board list. It shares the list's characteristic, so, for +example, if the list is scoped to a label `Frontend`, the new issue also has this label. + +### By sending an email + +> Generated email address format changed in GitLab 11.7. +> The older format is still supported, so existing aliases and contacts still work. + +You can send an email to create an issue in a project on the project's +**Issues List** page. + +Prerequisites: + +- Your GitLab instance must have [incoming email](../../../administration/incoming_email.md) + configured. +- There must be at least one issue in the issue list. +- You must have at least the [Guest role](../../permissions.md) for the project. + +To email an issue to a project: + +1. On the top bar, select **Menu > Projects** and find your project. +1. Select **Issues**. +1. At the bottom of the page, select **Email a new issue to this project**. +1. To copy the email address, select **Copy** (**{copy-to-clipboard}**). +1. From your email client, send an email to this address. + The subject is used as the title of the new issue, and the email body becomes the description. + You can use [Markdown](../../markdown.md) and [quick actions](../quick_actions.md). + +A new issue is created, with your user as the author. +You can save this address as a contact in your email client to use it again. + +WARNING: +The email address you see is a private email address, generated just for you. +**Keep it to yourself**, because anyone who knows it can create issues or merge requests as if they +were you. + +To regenerate the email address: + +1. On the issues list, select **Email a new issue to this project**. +1. Select **reset this token**. + +### Using a URL with prefilled values To link directly to the new issue page with prefilled fields, use query string parameters in a URL. You can embed a URL in an external -HTML page to create issues with certain -fields prefilled. - -| Field | URL Parameter Name | Notes | -|----------------------|-----------------------|-------------------------------------------------------| -| title | `issue[title]` | | -| description | `issue[description]` | Cannot be used at the same time as `issuable_template`. | -| description template | `issuable_template` | Cannot be used at the same time as `issue[description]`. | -| issue type | `issue[issue_type]` | Either `incident` or `issue`. | -| confidential | `issue[confidential]` | Parameter value must be `true` to set to confidential. | - -Follow these examples to form your new issue URL with prefilled fields. - -- For a new issue in the GitLab Community Edition project with a pre-filled title - and a pre-filled description, the URL would be `https://gitlab.com/gitlab-org/gitlab-foss/-/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea` -- For a new issue in the GitLab Community Edition project with a pre-filled title - and a pre-filled description template, the URL would be `https://gitlab.com/gitlab-org/gitlab-foss/-/issues/new?issue[title]=Validate%20new%20concept&issuable_template=Research%20proposal` -- For a new issue in the GitLab Community Edition project with a pre-filled title, - a pre-filled description, and the confidential flag set, the URL would be `https://gitlab.com/gitlab-org/gitlab-foss/-/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea&issue[confidential]=true` +HTML page to create issues with certain fields prefilled. + +| Field | URL parameter | Notes | +| -------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------- | +| Title | `issue[title]` | Must be [URL-encoded](../../../api/index.md#namespaced-path-encoding). | +| Issue type | `issue[issue_type]` | Either `incident` or `issue`. | +| Description template | `issuable_template` | Cannot be used at the same time as `issue[description]`. Must be [URL-encoded](../../../api/index.md#namespaced-path-encoding). | +| Description | `issue[description]` | Cannot be used at the same time as `issuable_template`. Must be [URL-encoded](../../../api/index.md#namespaced-path-encoding). | +| Confidential | `issue[confidential]` | If `true`, the issue is marked as confidential. | + +Adapt these examples to form your new issue URL with prefilled fields. +To create an issue in the GitLab project: + +- With a prefilled title and description: + + ```plaintext + https://gitlab.com/gitlab-org/gitlab/-/issues/new?issue[title]=Whoa%2C%20we%27re%20half-way%20there&issue[description]=Whoa%2C%20livin%27%20in%20a%20URL + ``` + +- With a prefilled title and description template: + + ```plaintext + https://gitlab.com/gitlab-org/gitlab/-/issues/new?issue[title]=Validate%20new%20concept&issuable_template=Feature%20Proposal%20-%20basic + ``` + +- With a prefilled title, description, and marked as confidential: + + ```plaintext + https://gitlab.com/gitlab-org/gitlab/-/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea&issue[confidential]=true + ``` + +### Using Service Desk + +To offer email support, enable [Service Desk](../service_desk.md) for your project. + +Now, when your customer sends a new email, a new issue can be created in +the appropriate project and followed up from there. + +### Fields in the new issue form + +> Adding the new issue to an epic [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13847) in GitLab 13.1. + +When you're creating a new issue, you can complete the following fields: + +- Title +- Type: either issue (default) or incident +- [Description template](../description_templates.md): overwrites anything in the Description text box +- Description: you can use [Markdown](../../markdown.md) and [quick actions](../quick_actions.md) +- Checkbox to make the issue [confidential](confidential_issues.md) +- [Assignees](#assignee) +- [Weight](issue_weight.md) +- [Epic](../../group/epics/index.md) +- [Due date](due_dates.md) +- [Milestone](../milestones/index.md) +- [Labels](../labels.md) ## Edit an issue You can edit an issue's title and description. +Prerequisites: + +- You must have at least the [Reporter role](../../permissions.md) for a project. + To edit an issue, select **Edit title and description** (**{pencil}**). ### Bulk edit issues at the project level diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 9469dead0dc..2bcfad97c25 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -4,7 +4,7 @@ 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)** +# Manage 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. @@ -16,7 +16,7 @@ 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. +The **Projects** page shows a list of projects, sorted by last updated date. - To view projects with the most [stars](#star-a-project), select **Most stars**. - To view projects with the largest number of comments in the past month, select **Trending**. @@ -26,14 +26,37 @@ The **Explore projects** tab is visible to unauthenticated users unless the [**Public** visibility level](../admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels) is restricted. Then the tab is visible only to signed-in users. +### Who can view the **Projects** page + +When you select a project, the project landing page shows the project contents. + +For public projects, and members of internal and private projects +with [permissions to view the project's code](../permissions.md#project-members-permissions), +the project landing page shows: + +- A [`README` or index file](repository/index.md#readme-and-index-files). +- A list of directories in the project's repository. + +For users without permission to view the project's code, the landing page shows: + +- The wiki homepage. +- The list of issues in the project. + +### Access a project page with the project ID + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53671) in GitLab 11.8. + +To 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. + ## Explore topics -You can explore popular project topics available on GitLab. To explore project topics: +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. +The **Projects** page shows 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). @@ -260,9 +283,8 @@ To add a star to a project: ## Delete a project -After you delete a project, projects in personal namespaces are deleted immediately. You can -[enable delayed project removal](../group/index.md#enable-delayed-project-deletion) to -delay deletion of projects in a group. +After you delete a project, projects in personal namespaces are deleted immediately. To delay deletion of projects in a group +you can [enable delayed project removal](../group/index.md#enable-delayed-project-deletion). To delete a project: @@ -299,56 +321,27 @@ To leave a project: on the project dashboard when a project is part of a group under a [group namespace](../group/index.md#namespaces). -## 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. -These projects 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. +## Use a project as a Go package -For example: +Prerequisites: + +- Contact your administrator to enable the [GitLab Go Proxy](../packages/go_proxy/index.md). +- 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 +`go get` to fail. You don't need to authenticate Go requests for projects that are not in subgroups. + +To use a project as a Go package, use the `go get` and `godoc.org` discovery requests. You can use the meta tags: + +- [`go-import`](https://golang.org/cmd/go/#hdr-Remote_import_paths) +- [`go-source`](https://github.com/golang/gddo/wiki/Source-Code-Links) + +### Authenticate Go requests to private projects + +Prerequisites: + +- Your GitLab instance must be accessible with HTTPS. +- You must have a [personal access token](../profile/personal_access_tokens.md). + +To authenticate Go requests, create a [`.netrc`](https://everything.curl.dev/usingcurl/netrc) file with the following information: ```plaintext machine gitlab.example.com @@ -356,98 +349,106 @@ login password ``` -NOTE: On Windows, Go reads `~/_netrc` instead of `~/.netrc`. -### Authenticate Git fetches +The `go` command does not transmit credentials over insecure connections. It authenticates +HTTPS requests made by Go, but does not authenticate requests made +through Git. -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: +### Authenticate Git requests -- Embed specific credentials in the request URL. -- Use SSH instead of HTTPS, as Go always uses HTTPS to fetch Git repositories. +If Go cannot fetch a module from a proxy, it uses Git. Git uses a `.netrc` file to authenticate requests, but you can +configure other authentication methods. -```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" +Configure Git to either: -# Use SSH instead of HTTPS: -git config --global url."git@gitlab.example.com".insteadOf "https://gitlab.example.com" -``` +- Embed credentials in the request URL: -### Fetch Go modules from Geo secondary sites + ```shell + git config --global url."https://${user}:${personal_access_token}@gitlab.example.com".insteadOf "https://gitlab.example.com" + ``` -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. +- Use SSH instead of HTTPS: -In the following examples, the primary's site domain name is `gitlab.example.com`, -and the secondary's is `gitlab-secondary.example.com`. + ```shell + git config --global url."git@gitlab.example.com".insteadOf "https://gitlab.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. +### Disable Go module fetching for private projects -#### Use SSH to access the Geo secondary +To [fetch modules or packages](../../development/go_guide/dependencies.md#fetching), Go uses +the [environment variables](../../development/go_guide/dependencies.md#proxies): -To fetch Go modules from the secondary using SSH: +- `GOPRIVATE` +- `GONOPROXY` +- `GONOSUMDB` + +To disable fetching: + +1. Disable `GOPRIVATE`: + - To disable queries for one project, disable `GOPRIVATE=gitlab.example.com/my/private/project`. + - To disable queries for all projects on GitLab.com, disable `GOPRIVATE=gitlab.example.com`. +1. Disable proxy queries in `GONOPROXY`. +1. Disable checksum queries in `GONOSUMDB`. + +- If the module name or its prefix is in `GOPRIVATE` or `GONOPROXY`, Go does not query module +proxies. +- If the module name or its prefix is in `GONOPRIVATE` or `GONOSUMDB`, Go does not query +Checksum databases. + +### Fetch Go modules from Geo secondary sites + +Use [Geo](../../administration/geo/index.md) to access Git repositories that contain Go modules +on secondary Geo servers. + +You can use SSH or HTTP to access the Geo secondary server. + +#### Use SSH to access the Geo secondary server + +To access the Geo secondary server with SSH: 1. Reconfigure Git on the client to send traffic for the primary to the secondary: - ```plaintext + ```shell 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. + - For `gitlab.example.com`, use the primary site domain name. + - For `gitlab-secondary.example.com`, use the secondary site domain name. + +1. Ensure the client is set up for SSH access to GitLab repositories. You can test this on the primary, + and GitLab replicates the public key to the secondary. + +The `go get` request generates HTTP traffic to the primary Geo server. When the module +download starts, the `insteadOf` configuration sends the traffic to the secondary Geo server. #### 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. +You must use persistent access tokens that replicate to the secondary server. You cannot use +CI/CD job tokens to fetch Go modules with HTTP. -To fetch Go modules from the secondary using HTTP: +To access the Geo secondary server with HTTP: -1. Put in place a Git `insteadOf` redirect on the client: +1. Add a Git `insteadOf` redirect on the client: - ```plaintext + ```shell git config --global url."https://gitlab-secondary.example.com".insteadOf "https://gitlab.example.com" ``` + - For `gitlab.example.com`, use the primary site domain name. + - For `gitlab-secondary.example.com`, use the secondary site domain name. + 1. Generate a [personal access token](../profile/personal_access_tokens.md) and - provide those credentials in the client's `~/.netrc` file: + add the credentials in the client's `~/.netrc` file: - ```plaintext + ```shell 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. +The `go get` request generates HTTP traffic to the primary Geo server. When the module +download starts, the `insteadOf` configuration sends the traffic to the secondary Geo server. ## Related topics -- cgit v1.2.1