diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-04-14 18:09:04 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-04-14 18:09:04 +0300 |
commit | a3dfd311f4660fc81e929058abd6e136ac884ed3 (patch) | |
tree | 4d7087cac6e2ca89df3adea98f92b9eddffa7790 /doc | |
parent | 7f408a3831590a1f98a1e1a04b63acba8937e36b (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc')
30 files changed, 622 insertions, 494 deletions
diff --git a/doc/administration/geo/replication/docker_registry.md b/doc/administration/geo/replication/docker_registry.md index 1669abbc52a..745ed28056f 100644 --- a/doc/administration/geo/replication/docker_registry.md +++ b/doc/administration/geo/replication/docker_registry.md @@ -5,16 +5,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Docker Registry for a secondary node **(PREMIUM SELF)** +# Docker Registry for a secondary site **(PREMIUM SELF)** You can set up a [Docker Registry](https://docs.docker.com/registry/) on your -**secondary** Geo node that mirrors the one on the **primary** Geo node. +**secondary** Geo site that mirrors the one on the **primary** Geo site. ## Storage support Docker Registry currently supports a few types of storage. If you choose a distributed storage (`azure`, `gcs`, `s3`, `swift`, or `oss`) for your Docker -Registry on the **primary** node, you can use the same storage for a **secondary** +Registry on the **primary** site, you can use the same storage for a **secondary** Docker Registry as well. For more information, read the [Load balancing considerations](https://docs.docker.com/registry/deploying/#load-balancing-considerations) when deploying the Registry, and how to set up the storage driver for the GitLab @@ -24,22 +24,22 @@ integrated [Container Registry](../../packages/container_registry.md#use-object- You can enable a storage-agnostic replication so it can be used for cloud or local storage. Whenever a new image is pushed to the -**primary** node, each **secondary** node will pull it to its own container +**primary** site, each **secondary** site will pull it to its own container repository. To configure Docker Registry replication: -1. Configure the [**primary** node](#configure-primary-node). -1. Configure the [**secondary** node](#configure-secondary-node). +1. Configure the [**primary** site](#configure-primary-site). +1. Configure the [**secondary** site](#configure-secondary-site). 1. Verify Docker Registry [replication](#verify-replication). -### Configure **primary** node +### Configure **primary** site Make sure that you have Container Registry set up and working on -the **primary** node before following the next steps. +the **primary** site before following the next steps. We need to make Docker Registry send notification events to the -**primary** node. +**primary** site. 1. SSH into your GitLab **primary** server and login as root: @@ -85,27 +85,29 @@ We need to make Docker Registry send notification events to the gitlab-ctl reconfigure ``` -### Configure **secondary** node +### Configure **secondary** site Make sure you have Container Registry set up and working on -the **secondary** node before following the next steps. +the **secondary** site before following the next steps. -The following steps should be done on each **secondary** node you're +The following steps should be done on each **secondary** site you're expecting to see the Docker images replicated. -Because we need to allow the **secondary** node to communicate securely with -the **primary** node Container Registry, we need to have a single key -pair for all the nodes. The **secondary** node will use this key to +Because we need to allow the **secondary** site to communicate securely with +the **primary** site Container Registry, we need to have a single key +pair for all the sites. The **secondary** site will use this key to generate a short-lived JWT that is pull-only-capable to access the -**primary** node Container Registry. +**primary** site Container Registry. -1. SSH into the **secondary** node and login as the `root` user: +For each application node on the **secondary** site: + +1. SSH into the node and login as the `root` user: ```shell sudo -i ``` -1. Copy `/var/opt/gitlab/gitlab-rails/etc/gitlab-registry.key` from the **primary** to the **secondary** node. +1. Copy `/var/opt/gitlab/gitlab-rails/etc/gitlab-registry.key` from the **primary** to the node. 1. Edit `/etc/gitlab/gitlab.rb`: @@ -114,7 +116,7 @@ generate a short-lived JWT that is pull-only-capable to access the gitlab_rails['geo_registry_replication_primary_api_url'] = 'https://primary.example.com:5050/' # Primary registry address, it will be used by the secondary node to directly communicate to primary registry ``` -1. Reconfigure the **secondary** node for the change to take effect: +1. Reconfigure the node for the change to take effect: ```shell gitlab-ctl reconfigure @@ -123,6 +125,6 @@ generate a short-lived JWT that is pull-only-capable to access the ### Verify replication To verify Container Registry replication is working, go to **Admin Area > Geo** -(`/admin/geo/nodes`) on the **secondary** node. +(`/admin/geo/nodes`) on the **secondary** site. The initial replication, or "backfill", will probably still be in progress. -You can monitor the synchronization process on each Geo node from the **primary** node's **Geo Nodes** dashboard in your browser. +You can monitor the synchronization process on each Geo site from the **primary** site's **Geo Nodes** dashboard in your browser. diff --git a/doc/administration/monitoring/prometheus/gitlab_metrics.md b/doc/administration/monitoring/prometheus/gitlab_metrics.md index 4ba1a85babc..9f87192aab0 100644 --- a/doc/administration/monitoring/prometheus/gitlab_metrics.md +++ b/doc/administration/monitoring/prometheus/gitlab_metrics.md @@ -250,10 +250,11 @@ configuration option in `gitlab.yml`. These metrics are served from the The following metrics are available: -| Metric | Type | Since | Description | -|:--------------------------------- |:--------- |:------------------------------------------------------------- |:-------------------------------------- | -| `db_load_balancing_hosts` | Gauge | [12.3](https://gitlab.com/gitlab-org/gitlab/-/issues/13630) | Current number of load balancing hosts | - +| Metric | Type | Since | Description | Labels | +|:--------------------------------- |:--------- |:------------------------------------------------------------- |:-------------------------------------- |:--------------------------------------------------------- | +| `db_load_balancing_hosts` | Gauge | [12.3](https://gitlab.com/gitlab-org/gitlab/-/issues/13630) | Current number of load balancing hosts | | +| `sidekiq_load_balancing_count` | Counter | 13.11 | Sidekiq jobs using load balancing with data consistency set to :sticky or :delayed | `queue`, `boundary`, `external_dependencies`, `feature_category`, `job_status`, `urgency`, `data_consistency`, `database_chosen` | + ## Database partitioning metrics **(PREMIUM SELF)** The following metrics are available: diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md index 8abeacd0d0e..03cc87e8f9b 100644 --- a/doc/api/graphql/reference/index.md +++ b/doc/api/graphql/reference/index.md @@ -63,6 +63,12 @@ Returns [`ContainerRepositoryDetails`](#containerrepositorydetails). | ---- | ---- | ----------- | | `id` | [`ContainerRepositoryID!`](#containerrepositoryid) | The global ID of the container repository. | +### `currentLicense` + +Fields related to the current license. + +Returns [`CurrentLicense`](#currentlicense). + ### `currentUser` Get information about current user. @@ -181,6 +187,21 @@ Returns [`Iteration`](#iteration). | ---- | ---- | ----------- | | `id` | [`IterationID!`](#iterationid) | Find an iteration by its ID. | +### `licenseHistoryEntries` + +Fields related to entries in the license history. + +Returns [`LicenseHistoryEntryConnection`](#licensehistoryentryconnection). + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `after` | [`String`](#string) | Returns the elements in the list that come after the specified cursor. | +| `before` | [`String`](#string) | Returns the elements in the list that come before the specified cursor. | +| `first` | [`Int`](#int) | Returns the first _n_ elements from the list. | +| `last` | [`Int`](#int) | Returns the last _n_ elements from the list. | + ### `metadata` Metadata about GitLab. @@ -1872,6 +1893,27 @@ Autogenerated return type of CreateTestCase. | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | `testCase` | [`Issue`](#issue) | The test case created. | +### `CurrentLicense` + +Represents the current license. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `activatedAt` | [`Date`](#date) | Date when the license was activated. | +| `billableUsersCount` | [`Int`](#int) | Number of billable users on the system. | +| `company` | [`String`](#string) | Company of the licensee. | +| `email` | [`String`](#string) | Email of the licensee. | +| `expiresAt` | [`Date`](#date) | Date when the license expires. | +| `id` | [`ID!`](#id) | ID of the license. | +| `lastSync` | [`Time`](#time) | Date when the license was last synced. | +| `maximumUserCount` | [`Int`](#int) | Highest number of billable users on the system during the term of the current license. | +| `name` | [`String`](#string) | Name of the licensee. | +| `plan` | [`String!`](#string) | Name of the subscription plan. | +| `startsAt` | [`Date`](#date) | Date when the license started. | +| `type` | [`String!`](#string) | Type of the license. | +| `usersInLicenseCount` | [`Int`](#int) | Number of paid users in the license. | +| `usersOverLicenseCount` | [`Int`](#int) | Number of users over the paid users in the license. | + ### `CustomEmoji` A custom emoji uploaded by user. @@ -3106,6 +3148,7 @@ Autogenerated return type of GitlabSubscriptionActivate. | ----- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| `license` | [`CurrentLicense`](#currentlicense) | The current license. | ### `GrafanaIntegration` @@ -3874,6 +3917,42 @@ An edge in a connection. | `cursor` | [`String!`](#string) | A cursor for use in pagination. | | `node` | [`Label`](#label) | The item at the end of the edge. | +### `LicenseHistoryEntry` + +Represents an entry from the Cloud License history. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `activatedAt` | [`Date`](#date) | Date when the license was activated. | +| `company` | [`String`](#string) | Company of the licensee. | +| `email` | [`String`](#string) | Email of the licensee. | +| `expiresAt` | [`Date`](#date) | Date when the license expires. | +| `id` | [`ID!`](#id) | ID of the license. | +| `name` | [`String`](#string) | Name of the licensee. | +| `plan` | [`String!`](#string) | Name of the subscription plan. | +| `startsAt` | [`Date`](#date) | Date when the license started. | +| `type` | [`String!`](#string) | Type of the license. | +| `usersInLicenseCount` | [`Int`](#int) | Number of paid users in the license. | + +### `LicenseHistoryEntryConnection` + +The connection type for LicenseHistoryEntry. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `edges` | [`[LicenseHistoryEntryEdge]`](#licensehistoryentryedge) | A list of edges. | +| `nodes` | [`[LicenseHistoryEntry]`](#licensehistoryentry) | A list of nodes. | +| `pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +### `LicenseHistoryEntryEdge` + +An edge in a connection. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `cursor` | [`String!`](#string) | A cursor for use in pagination. | +| `node` | [`LicenseHistoryEntry`](#licensehistoryentry) | The item at the end of the edge. | + ### `MarkAsSpamSnippetPayload` Autogenerated return type of MarkAsSpamSnippet. @@ -8416,7 +8495,7 @@ Name of the feature that the callout is for. | `NEW_USER_SIGNUPS_CAP_REACHED` | Callout feature name for new_user_signups_cap_reached. | | `PERSONAL_ACCESS_TOKEN_EXPIRY` | Callout feature name for personal_access_token_expiry. | | `REGISTRATION_ENABLED_CALLOUT` | Callout feature name for registration_enabled_callout. | -| `SERVICE_TEMPLATES_DEPRECATED` | Callout feature name for service_templates_deprecated. | +| `SERVICE_TEMPLATES_DEPRECATED_CALLOUT` | Callout feature name for service_templates_deprecated_callout. | | `SUGGEST_PIPELINE` | Callout feature name for suggest_pipeline. | | `SUGGEST_POPOVER_DISMISSED` | Callout feature name for suggest_popover_dismissed. | | `TABS_POSITION_HIGHLIGHT` | Callout feature name for tabs_position_highlight. | diff --git a/doc/api/services.md b/doc/api/services.md index 2311a5cacb7..0b840d907f8 100644 --- a/doc/api/services.md +++ b/doc/api/services.md @@ -767,8 +767,8 @@ Parameters: | `username` | string | yes | The username of the user created to be used with GitLab/Jira. | | `password` | string | yes | The password of the user created to be used with GitLab/Jira. | | `active` | boolean | no | Activates or deactivates the service. Defaults to false (deactivated). | -| `jira_issue_transition_automatic` | boolean | no | Enable [automatic issue transitions](../user/project/integrations/jira.md#automatic-issue-transitions). Takes precedence over `jira_issue_transition_id` if enabled. Defaults to `false` | -| `jira_issue_transition_id` | string | no | The ID of one or more transitions for [custom issue transitions](../user/project/integrations/jira.md#custom-issue-transitions). Ignored if `jira_issue_transition_automatic` is enabled. Defaults to a blank string, which disables custom transitions. | +| `jira_issue_transition_automatic` | boolean | no | Enable [automatic issue transitions](../integration/jira/issues.md#automatic-issue-transitions). Takes precedence over `jira_issue_transition_id` if enabled. Defaults to `false` | +| `jira_issue_transition_id` | string | no | The ID of one or more transitions for [custom issue transitions](../integration/jira/issues.md#custom-issue-transitions). Ignored if `jira_issue_transition_automatic` is enabled. Defaults to a blank string, which disables custom transitions. | | `commit_events` | boolean | false | Enable notifications for commit events | | `merge_requests_events` | boolean | false | Enable notifications for merge request events | | `comment_on_event_enabled` | boolean | false | Enable comments inside Jira issues on each GitLab event (commit / merge request) | diff --git a/doc/integration/jira/connect-app.md b/doc/integration/jira/connect-app.md index 6ccc93df1f9..fa0df27585e 100644 --- a/doc/integration/jira/connect-app.md +++ b/doc/integration/jira/connect-app.md @@ -11,10 +11,13 @@ You can integrate GitLab.com and Jira Cloud using the app in the Atlassian Marketplace. The user configuring GitLab for Jira must have [Maintainer](../../user/permissions.md) permissions in the GitLab namespace. -This method is recommended when using GitLab.com and Jira Cloud because data is synchronized in real-time. The DVCS connector updates data only once per hour. If you are not using both of these environments, use the [Jira DVCS Connector](dvcs.md) method. +This method is recommended when using GitLab.com and Jira Cloud because data is +synchronized in real-time. The DVCS connector updates data only once per hour. +If you are not using both of these environments, use the [Jira DVCS Connector](dvcs.md) method. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For a walkthrough of the integration with GitLab for Jira, watch [Configure GitLab Jira Integration using Marketplace App](https://youtu.be/SwR-g1s1zTo) on YouTube. +For a walkthrough of the integration with GitLab for Jira, watch +[Configure GitLab Jira Integration using Marketplace App](https://youtu.be/SwR-g1s1zTo) on YouTube. 1. Go to **Jira Settings > Apps > Find new apps**, then search for GitLab. 1. Click **GitLab for Jira**, then click **Get it now**, or go to the @@ -47,8 +50,6 @@ After a namespace is added: Support for syncing past branch and commit data [is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/263240). -For more information, see [Usage](index.md#usage). - ## Install the GitLab Jira Cloud application for self-managed instances **(FREE SELF)** If your GitLab instance is self-managed, you must follow some diff --git a/doc/integration/jira/development_panel.md b/doc/integration/jira/development_panel.md new file mode 100644 index 00000000000..1617e950104 --- /dev/null +++ b/doc/integration/jira/development_panel.md @@ -0,0 +1,155 @@ +--- +stage: Create +group: Ecosystem +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 +--- + +# GitLab Jira Development panel integration **(FREE)** + +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/233149) to GitLab Free in 13.4. + +The Jira Development panel integration allows you to reference Jira issues in GitLab, displaying +activity in the [Development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/) +in the issue. + +It complements the [GitLab Jira integration](../../user/project/integrations/jira.md). You may choose +to configure both integrations to take advantage of both sets of features. See a +[feature comparison](index.md#direct-feature-comparison). + +## Features + +| Your mention of Jira issue ID in GitLab context | Automated effect in Jira issue | +|---------------------------------------------------|--------------------------------------------------------------------------------------------------------| +| In a merge request | Link to the MR is displayed in Development panel. | +| In a branch name | Link to the branch is displayed in Development panel. | +| In a commit message | Link to the commit is displayed in Development panel. | +| In a commit message with Jira Smart Commit format | Displays your custom comment or logged time spent and/or performs specified issue transition on merge. | + +With this integration, you can access related GitLab merge requests, branches, and commits directly from a Jira issue, reflecting your work in GitLab. From the Development panel, you can open a detailed view and take actions including creating a new merge request from a branch. For more information, see [Usage](#usage). + +This integration connects all GitLab projects to projects in the Jira instance in either: + +- A top-level group. A top-level GitLab group is one that does not have any parent group itself. All + the projects of that top-level group, as well as projects of the top-level group's subgroups nesting + down, are connected. +- A personal namespace, which then connects the projects in that personal namespace to Jira. + +This differs from the [Jira integration](../../user/project/integrations/jira.md), where the mapping is between one GitLab project and the entire Jira instance. + +Additional features provided by the Jira Development Panel integration include: + +- In a Jira issue, display relevant GitLab information in the [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/), including related branches, commits, and merge requests. +- Use Jira [Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html) in GitLab to add Jira comments, log time spent on the issue, or apply any issue transition. +- Showing pipeline, deployment, and feature flags in Jira issues. + +## Configuration + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview of how to configure Jira Development panel integration, see [Agile Management - GitLab Jira Development panel integration](https://www.youtube.com/watch?v=VjVTOmMl85M&feature=youtu.be). + +We recommend that a GitLab group maintainer or group owner, or instance administrator (in the case of +self-managed GitLab) set up the integration to simplify administration. + +| If you use Jira on: | GitLab.com customers need: | GitLab self-managed customers need: | +|-|-|-| +| [Atlassian cloud](https://www.atlassian.com/cloud) | The [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview) application installed from the [Atlassian Marketplace](https://marketplace.atlassian.com). This offers real-time sync between GitLab and Jira. | The [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview), using a workaround process. See the documentation for [installing the GitLab Jira Cloud application for self-managed instances](connect-app.md#install-the-gitlab-jira-cloud-application-for-self-managed-instances) for more information. | +| Your own server | The Jira DVCS (distributed version control system) connector. This syncs data hourly. | The [Jira DVCS Connector](dvcs.md). | + +Each GitLab project can be configured to connect to an entire Jira instance. That means one GitLab +project can interact with _all_ Jira projects in that instance, once configured. For: + +- The [view Jira issues](issues.md#view-jira-issues) feature, you must associate a GitLab project with a + specific Jira project. +- Other features, you do not have to explicitly associate a GitLab project with any single Jira + project. + +If you have a single Jira instance, you can pre-fill the settings. For more information, read the +documentation for [central administration of project integrations](../../user/admin_area/settings/project_integration_management.md). + +To enable the Jira service in GitLab, you must: + +1. Configure the project in Jira. +1. Enter the correct values in GitLab. + +### Configure GitLab + +> **Notes:** +> +> - The supported Jira versions are `v6.x`, `v7.x`, and `v8.x`. +> - In order to support Oracle's Access Manager, GitLab sends additional cookies +> to enable Basic Auth. The cookie being added to each request is `OBBasicAuth` with +> a value of `fromDialog`. + +To enable the Jira integration in a project: + +1. Go to the project's [Integrations page](../../user/project/integrations/overview.md#accessing-integrations) and select the + **Jira** service. + +1. Select **Enable integration**. + +1. Select **Trigger** actions. + This determines whether a mention of a Jira issue in GitLab commits, merge requests, or both, + should link the Jira issue back to that source commit/MR and transition the Jira issue, if + indicated. + +1. To include a comment on the Jira issue when the above reference is made in GitLab, select + **Enable comments**. + +1. To transition Jira issues when a [closing reference](../../user/project/issues/managing_issues.md#closing-issues-automatically) is made in GitLab, + select **Enable Jira transitions**. + +1. Enter the further details on the page as described in the following table. + + | Field | Description | + | ----- | ----------- | + | `Web URL` | The base URL to the Jira instance web interface which is being linked to this GitLab project. For example, `https://jira.example.com`. | + | `Jira API URL` | The base URL to the Jira instance API. Web URL value is used if not set. For example, `https://jira-api.example.com`. Leave this field blank (or use the same value of `Web URL`) if using **Jira on Atlassian cloud**. | + | `Username or Email` | Created in [configure Jira](dvcs.md#configure-jira-for-dvcs) step. Use `username` for **Jira Server** or `email` for **Jira on Atlassian cloud**. | + | `Password/API token` | Created in [configure Jira](dvcs.md#configure-jira-for-dvcs) step. Use `password` for **Jira Server** or `API token` for **Jira on Atlassian cloud**. | + +1. To enable users to view Jira issues inside the GitLab project, select **Enable Jira issues** and + enter a Jira project key. **(PREMIUM)** + + You can only display issues from a single Jira project within a given GitLab project. + + WARNING: + If you enable Jira issues with the setting above, all users that have access to this GitLab project + are able to view all issues from the specified Jira project. + +1. To enable creation of issues for vulnerabilities, select **Enable Jira issues creation from vulnerabilities**. + + 1. Select the **Jira issue type**. If the dropdown is empty, select refresh (**{retry}**) and try again. + +1. To verify the Jira connection is working, select **Test settings**. + +1. Select **Save changes**. + +Your GitLab project can now interact with all Jira projects in your instance and the project now +displays a Jira link that opens the Jira project. + +## Usage + +After the integration is set up on GitLab and Jira, you can: + +- Refer to any Jira issue by its ID in GitLab branch names, commit messages, and merge request + titles. +- See the linked branches, commits, and merge requests in Jira issues (merge requests are + called "pull requests" in Jira issues). + +Jira issue IDs must be formatted in uppercase for the integration to work. + +![Branch, Commit and Pull Requests links on Jira issue](img/jira_dev_panel_jira_setup_3.png) + +Click the links to see your GitLab repository data. + +![GitLab commits details on a Jira issue](img/jira_dev_panel_jira_setup_4.png) + +![GitLab merge requests details on a Jira issue](img/jira_dev_panel_jira_setup_5.png) + +For more information on using Jira Smart Commits to track time against an issue, specify an issue transition, or add a custom comment, see the Atlassian page [Using Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html). + +## Limitations + +This integration is not supported on GitLab instances under a +[relative URL](https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-a-relative-url-for-gitlab). +For example, `http://example.com/gitlab`. diff --git a/doc/integration/jira/dvcs.md b/doc/integration/jira/dvcs.md index 1e6cf8e85f6..1d67dab9a84 100644 --- a/doc/integration/jira/dvcs.md +++ b/doc/integration/jira/dvcs.md @@ -80,7 +80,7 @@ it completes, refreshes every 60 minutes: To connect additional GitLab projects from other GitLab top-level groups, or personal namespaces, repeat the previous steps with additional Jira DVCS accounts. -After you configure the integration, read more about [how to test and use it](index.md#usage). +After you configure the integration, read more about [how to test and use it](development_panel.md#usage). ## Refresh data imported to Jira diff --git a/doc/user/project/integrations/img/jira_added_user_to_group.png b/doc/integration/jira/img/jira_added_user_to_group.png Binary files differindex f5120a8d42e..f5120a8d42e 100644 --- a/doc/user/project/integrations/img/jira_added_user_to_group.png +++ b/doc/integration/jira/img/jira_added_user_to_group.png diff --git a/doc/user/project/integrations/img/jira_create_new_group.png b/doc/integration/jira/img/jira_create_new_group.png Binary files differindex 4ab7a5eae4e..4ab7a5eae4e 100644 --- a/doc/user/project/integrations/img/jira_create_new_group.png +++ b/doc/integration/jira/img/jira_create_new_group.png diff --git a/doc/user/project/integrations/img/jira_group_access.png b/doc/integration/jira/img/jira_group_access.png Binary files differindex 42a9b4ae564..42a9b4ae564 100644 --- a/doc/user/project/integrations/img/jira_group_access.png +++ b/doc/integration/jira/img/jira_group_access.png diff --git a/doc/user/project/integrations/img/jira/jira_issue_detail_view_v13.10.png b/doc/integration/jira/img/jira_issue_detail_view_v13.10.png Binary files differindex bf1607a35fe..bf1607a35fe 100644 --- a/doc/user/project/integrations/img/jira/jira_issue_detail_view_v13.10.png +++ b/doc/integration/jira/img/jira_issue_detail_view_v13.10.png diff --git a/doc/user/project/integrations/img/jira_issue_reference.png b/doc/integration/jira/img/jira_issue_reference.png Binary files differindex db8bc4f0bb9..db8bc4f0bb9 100644 --- a/doc/user/project/integrations/img/jira_issue_reference.png +++ b/doc/integration/jira/img/jira_issue_reference.png diff --git a/doc/user/project/integrations/img/jira_merge_request_close.png b/doc/integration/jira/img/jira_merge_request_close.png Binary files differindex 9a176daf5f4..9a176daf5f4 100644 --- a/doc/user/project/integrations/img/jira_merge_request_close.png +++ b/doc/integration/jira/img/jira_merge_request_close.png diff --git a/doc/user/project/integrations/img/jira_project_settings.png b/doc/integration/jira/img/jira_project_settings.png Binary files differindex d96002b7db8..d96002b7db8 100644 --- a/doc/user/project/integrations/img/jira_project_settings.png +++ b/doc/integration/jira/img/jira_project_settings.png diff --git a/doc/user/project/integrations/img/jira_service_close_issue.png b/doc/integration/jira/img/jira_service_close_issue.png Binary files differindex 73d6498192c..73d6498192c 100644 --- a/doc/user/project/integrations/img/jira_service_close_issue.png +++ b/doc/integration/jira/img/jira_service_close_issue.png diff --git a/doc/user/project/integrations/img/jira/open_jira_issues_list_v13.2.png b/doc/integration/jira/img/open_jira_issues_list_v13.2.png Binary files differindex 0cf58433b25..0cf58433b25 100644 --- a/doc/user/project/integrations/img/jira/open_jira_issues_list_v13.2.png +++ b/doc/integration/jira/img/open_jira_issues_list_v13.2.png diff --git a/doc/integration/jira/index.md b/doc/integration/jira/index.md index 5992ee8da64..f081b17700e 100644 --- a/doc/integration/jira/index.md +++ b/doc/integration/jira/index.md @@ -4,74 +4,88 @@ group: Ecosystem 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 --- -# GitLab Jira Development panel integration **(FREE)** +# Jira integrations **(FREE)** -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/233149) to GitLab Free in 13.4. +If your organization uses [Jira](https://www.atlassian.com/software/jira) issues, +you can [migrate](../../user/project/import/jira.md) your issues from Jira and work +exclusively in GitLab. However, if you'd like to continue to use Jira, you can +integrate it with GitLab. GitLab offers two types of Jira integrations, and you +can use one or both depending on the capabilities you need. -The Jira Development panel integration allows you to reference Jira issues in GitLab, displaying -activity in the [Development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/) -in the issue. +## Compare Jira integrations -It complements the [GitLab Jira integration](../../user/project/integrations/jira.md). You may choose -to configure both integrations to take advantage of both sets of features. See a -[feature comparison](../../user/project/integrations/jira_integrations.md). +After you set up one or both of these integrations, you can cross-reference activity +in your GitLab project with any of your projects in Jira. -## Features - -| Your mention of Jira issue ID in GitLab context | Automated effect in Jira issue | -|---------------------------------------------------|--------------------------------------------------------------------------------------------------------| -| In a merge request | Link to the MR is displayed in Development panel. | -| In a branch name | Link to the branch is displayed in Development panel. | -| In a commit message | Link to the commit is displayed in Development panel. | -| In a commit message with Jira Smart Commit format | Displays your custom comment or logged time spent and/or performs specified issue transition on merge. | +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, see [Agile Management - GitLab-Jira Basic Integration](https://www.youtube.com/watch?v=fWvwkx5_00E&feature=youtu.be). -With this integration, you can access related GitLab merge requests, branches, and commits directly from a Jira issue, reflecting your work in GitLab. From the Development panel, you can open a detailed view and take actions including creating a new merge request from a branch. For more information, see [Usage](#usage). +### Per-project Jira integration -This integration connects all GitLab projects to projects in the Jira instance in either: +This integration connects a single GitLab project to a Jira instance. The Jira instance +can be hosted by you or in [Atlassian cloud](https://www.atlassian.com/cloud): -- A top-level group. A top-level GitLab group is one that does not have any parent group itself. All - the projects of that top-level group, as well as projects of the top-level group's subgroups nesting - down, are connected. -- A personal namespace, which then connects the projects in that personal namespace to Jira. +- *If your installation uses GitLab.com and Jira Cloud,* use the + [GitLab for Jira app](connect-app.md). +- *If either your Jira or GitLab installation is self-managed,* use the + [Jira DVCS Connector](dvcs.md). -This differs from the [Jira integration](../../user/project/integrations/jira.md), where the mapping is between one GitLab project and the entire Jira instance. +### Jira development panel integration -## Configuration +The [Jira development panel integration](development_panel.md) +connects all GitLab projects under a group or personal namespace. When configured, +relevant GitLab information, including related branches, commits, and merge requests, +displays in the [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/). -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview of how to configure Jira Development panel integration, see [Agile Management - GitLab Jira Development panel integration](https://www.youtube.com/watch?v=VjVTOmMl85M&feature=youtu.be). +### Direct feature comparison -We recommend that a GitLab group maintainer or group owner, or instance administrator (in the case of -self-managed GitLab) set up the integration to simplify administration. - -| If you use Jira on: | GitLab.com customers need: | GitLab self-managed customers need: | +| Capability | Jira integration | Jira Development panel integration | |-|-|-| -| [Atlassian cloud](https://www.atlassian.com/cloud) | The [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview) application installed from the [Atlassian Marketplace](https://marketplace.atlassian.com). This offers real-time sync between GitLab and Jira. | The [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview), using a workaround process. See the documentation for [installing the GitLab Jira Cloud application for self-managed instances](connect-app.md#install-the-gitlab-jira-cloud-application-for-self-managed-instances) for more information. | -| Your own server | The Jira DVCS (distributed version control system) connector. This syncs data hourly. | The [Jira DVCS Connector](dvcs.md). | +| Mention a Jira issue ID in a GitLab commit or merge request, and a link to the Jira issue is created. | Yes. | No. | +| Mention a Jira issue ID in GitLab and the Jira issue shows the GitLab issue or merge request. | Yes. A Jira comment with the GitLab issue or MR title links to GitLab. The first mention is also added to the Jira issue under **Web links**. | Yes, in the issue's Development panel. | +| Mention a Jira issue ID in a GitLab commit message and the Jira issue shows the commit message. | Yes. The entire commit message is displayed in the Jira issue as a comment and under **Web links**. Each message links back to the commit in GitLab. | Yes, in the issue's Development panel and optionally with a custom comment on the Jira issue using Jira [Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html). | +| Mention a Jira issue ID in a GitLab branch name and the Jira issue shows the branch name. | No. | Yes, in the issue's [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/). | +| Add Jira time tracking to an issue. | No. | Yes. Time can be specified using Jira Smart Commits. | +| Use a Git commit or merge request to transition or close a Jira issue. | Yes. Only a single transition type, typically configured to close the issue by setting it to Done. | Yes. Transition to any state using Jira Smart Commits. | +| Display a list of Jira issues. | Yes. **(PREMIUM)** | No. | +| Create a Jira issue from a vulnerability or finding. **(ULTIMATE)** | Yes. | No. | + +## Authentication in Jira -## Usage +The process for configuring Jira depends on whether you host Jira on your own server or on +[Atlassian cloud](https://www.atlassian.com/cloud): -After the integration is set up on GitLab and Jira, you can: +- **Jira Server** supports basic authentication. When connecting, a **username and password** are + required. Connecting to Jira Server via CAS is not possible. For more information, read + how to [set up a user in Jira Server](jira_server_configuration.md). +- **Jira on Atlassian cloud** supports authentication through an API token. When connecting to Jira on + Atlassian cloud, an email and API token are required. For more information, read + [set up a user in Jira on Atlassian cloud](jira_cloud_configuration.md). -- Refer to any Jira issue by its ID in GitLab branch names, commit messages, and merge request - titles. -- See the linked branches, commits, and merge requests in Jira issues (merge requests are - called "pull requests" in Jira issues). +## Troubleshooting -Jira issue IDs must be formatted in uppercase for the integration to work. +If these features do not work as expected, it is likely due to a problem with the way the integration settings were configured. -![Branch, Commit and Pull Requests links on Jira issue](img/jira_dev_panel_jira_setup_3.png) +### GitLab is unable to comment on a Jira issue -Click the links to see your GitLab repository data. +Make sure that the Jira user you set up for the integration has the +correct access permission to post comments on a Jira issue and also to transition +the issue, if you'd like GitLab to also be able to do so. +Jira issue references and update comments do not work if the GitLab issue tracker is disabled. -![GitLab commits details on a Jira issue](img/jira_dev_panel_jira_setup_4.png) +### GitLab is unable to close a Jira issue -![GitLab merge requests details on a Jira issue](img/jira_dev_panel_jira_setup_5.png) +Make sure the `Transition ID` you set within the Jira settings matches the one +your project needs to close an issue. -For more information on using Jira Smart Commits to track time against an issue, specify an issue transition, or add a custom comment, see the Atlassian page [Using Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html). +Make sure that the Jira issue is not already marked as resolved; that is, +the Jira issue resolution field is not set. (It should not be struck through in +Jira lists.) -## Limitations +### CAPTCHA -This integration is not supported on GitLab instances under a -[relative URL](https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-a-relative-url-for-gitlab). -For example, `http://example.com/gitlab`. +CAPTCHA may be triggered after several consecutive failed login attempts +which may lead to a `401 unauthorized` error when testing your Jira integration. +If CAPTCHA has been triggered, you can't use Jira's REST API to +authenticate with the Jira site. You need to log in to your Jira instance +and complete the CAPTCHA. diff --git a/doc/integration/jira/issues.md b/doc/integration/jira/issues.md new file mode 100644 index 00000000000..d2cab59742b --- /dev/null +++ b/doc/integration/jira/issues.md @@ -0,0 +1,173 @@ +--- +stage: Create +group: Ecosystem +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 +--- + +# Jira integration issue management **(FREE)** + +By now you should have [configured Jira](development_panel.md#configuration) and enabled the +[Jira service in GitLab](development_panel.md#configure-gitlab). If everything is set up correctly +you should be able to reference and close Jira issues by just mentioning their +ID in GitLab commits and merge requests. + +Jira issue IDs must be formatted in uppercase for the integration to work. + +## Reference Jira issues + +When GitLab project has Jira issue tracker configured and enabled, mentioning +Jira issues in GitLab automatically adds a comment in Jira issue with the +link back to GitLab. This means that in comments in merge requests and commits +referencing an issue, `PROJECT-7` for example, adds a comment in Jira issue in the +format: + +```plaintext +USER mentioned this issue in RESOURCE_NAME of [PROJECT_NAME|LINK_TO_COMMENT]: +ENTITY_TITLE +``` + +- `USER` A user that mentioned the issue. This is the link to the user profile in GitLab. +- `LINK_TO_THE_COMMENT` Link to the origin of mention with a name of the entity where Jira issue was mentioned. +- `RESOURCE_NAME` Kind of resource which referenced the issue. Can be a commit or merge request. +- `PROJECT_NAME` GitLab project name. +- `ENTITY_TITLE` Merge request title or commit message first line. + +![example of mentioning or closing the Jira issue](img/jira_issue_reference.png) + +For example, the following commit references the Jira issue with `PROJECT-1` as its ID: + +```shell +git commit -m "PROJECT-1 Fix spelling and grammar" +``` + +## Close Jira issues + +Jira issues can be closed directly from GitLab by using trigger words in +commits and merge requests. When a commit which contains the trigger word +followed by the Jira issue ID in the commit message is pushed, GitLab +adds a comment in the mentioned Jira issue and immediately closes it (provided +the transition ID was set up correctly). + +There are currently three trigger words, and you can use either one to achieve +the same goal: + +- `Resolves PROJECT-1` +- `Closes PROJECT-1` +- `Fixes PROJECT-1` + +where `PROJECT-1` is the ID of the Jira issue. + +Note the following: + +- Only commits and merges into the project's default branch (usually `master`) + close an issue in Jira. You can change your project's default branch under + [project settings](img/jira_project_settings.png). +- The Jira issue is not transitioned if it has a resolution. + +Let's consider the following example: + +1. For the project named `PROJECT` in Jira, we implemented a new feature + and created a merge request in GitLab. +1. This feature was requested in Jira issue `PROJECT-7` and the merge request + in GitLab contains the improvement +1. In the merge request description we use the issue closing trigger + `Closes PROJECT-7`. +1. Once the merge request is merged, the Jira issue is automatically closed + with a comment and an associated link to the commit that resolved the issue. + +In the following screenshot you can see what the link references to the Jira +issue look like. + +![A Git commit that causes the Jira issue to be closed](img/jira_merge_request_close.png) + +Once this merge request is merged, the Jira issue is automatically closed +with a link to the commit that resolved the issue. + +![The GitLab integration closes Jira issue](img/jira_service_close_issue.png) + +## View Jira issues **(PREMIUM)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3622) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. + +You can browse, search, and view issues from a selected Jira project directly in GitLab, +if your GitLab administrator [has configured it](development_panel.md#configure-gitlab): + +1. In the left navigation bar, go to **Jira > Issues list**. +1. The issue list sorts by **Created date** by default, with the newest issues listed at the top: + + ![Jira issues integration enabled](img/open_jira_issues_list_v13.2.png) + +1. To display the most recently updated issues first, click **Last updated**. +1. In GitLab versions 13.10 and later, you can view [individual Jira issues](#view-a-jira-issue). + +Issues are grouped into tabs based on their [Jira status](https://confluence.atlassian.com/adminjiraserver070/defining-status-field-values-749382903.html): + +- The **Open** tab displays all issues with a Jira status in any category other than Done. +- The **Closed** tab displays all issues with a Jira status categorized as Done. +- The **All** tab displays all issues of any status. + +## View a Jira issue + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299832) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.10 behind a feature flag, disabled by default. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/299832) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.11. + +When viewing the [Jira issues list](#view-jira-issues), select an issue from the +list to open it in GitLab: + +![Jira issue detail view](img/jira_issue_detail_view_v13.10.png) + +## Search and filter the issues list + +To refine the list of issues, use the search bar to search for any text +contained in an issue summary (title) or description. + +You can also filter by labels, status, reporter, and assignee using URL parameters. +Enhancements to be able to use these through the user interface are [planned](https://gitlab.com/groups/gitlab-org/-/epics/3622). + +- To filter issues by `labels`, specify one or more labels as part of the `labels[]` +parameter in the URL. When using multiple labels, only issues that contain all specified +labels are listed. `/-/integrations/jira/issues?labels[]=backend&labels[]=feature&labels[]=QA` + +- To filter issues by `status`, specify the `status` parameter in the URL. +`/-/integrations/jira/issues?status=In Progress` + +- To filter issues by `reporter`, specify a reporter's Jira display name for the +`author_username` parameter in the URL. `/-/integrations/jira/issues?author_username=John Smith` + +- To filter issues by `assignee`, specify their Jira display name for the +`assignee_username` parameter in the URL. `/-/integrations/jira/issues?assignee_username=John Smith` + +## Automatic issue transitions + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/...) in GitLab 13.10. + +In this mode the referenced Jira issue is transitioned to the next available status with a category of "Done". + +See the [Configure GitLab](development_panel.md#configure-gitlab) section, check the **Enable Jira transitions** setting and select the **Move to Done** option. + +## Custom issue transitions + +For advanced workflows you can specify custom Jira transition IDs. + +See the [Configure GitLab](development_panel.md#configure-gitlab) section, check the **Enable Jira transitions** setting, select the **Custom transitions** option, and enter your transition IDs in the text field. + +If you insert multiple transition IDs separated by `,` or `;`, the issue is moved to each state, one after another, using the given order. If a transition fails the sequence is aborted. + +To see the transition IDs on Jira Cloud, edit a workflow in the **Text** view. +The transition IDs display in the **Transitions** column. + +On Jira Server you can get the transition IDs in either of the following ways: + +1. By using the API, with a request like `https://yourcompany.atlassian.net/rest/api/2/issue/ISSUE-123/transitions` + using an issue that is in the appropriate "open" state +1. By mousing over the link for the transition you want and looking for the + "action" parameter in the URL + +Note that the transition ID may vary between workflows (for example, bug vs. story), +even if the status you are changing to is the same. + +## Disabling comments on Jira issues + +You can continue to have GitLab cross-link a source commit/MR with a Jira issue while disabling the comment added to the issue. + +See the [Configure GitLab](development_panel.md#configure-gitlab) section and uncheck the **Enable comments** setting. diff --git a/doc/integration/jira/jira_cloud_configuration.md b/doc/integration/jira/jira_cloud_configuration.md index e6026578cf8..fd58b3f33f7 100644 --- a/doc/integration/jira/jira_cloud_configuration.md +++ b/doc/integration/jira/jira_cloud_configuration.md @@ -15,8 +15,8 @@ on Atlassian cloud. To create the API token: 1. Select **Create API token** to display a modal window with an API token. 1. To copy the API token, select **Copy to clipboard**, or select **View** and write down the new API token. You need this value when you - [configure GitLab](../../user/project/integrations/jira.md#configure-gitlab). + [configure GitLab](development_panel.md#configure-gitlab). You need the newly created token, and the email address you used when you created it, when you -[configure GitLab](../../user/project/integrations/jira.md#configure-gitlab). +[configure GitLab](development_panel.md#configure-gitlab). diff --git a/doc/integration/jira/jira_server_configuration.md b/doc/integration/jira/jira_server_configuration.md index e37f2e10551..3573a1f8b1e 100644 --- a/doc/integration/jira/jira_server_configuration.md +++ b/doc/integration/jira/jira_server_configuration.md @@ -45,7 +45,7 @@ group to assign permissions to the user: select **User Management**. 1. From the sidebar, select **Groups**. - ![Jira create new user](../../user/project/integrations/img/jira_create_new_group.png) + ![Jira create new user](img/jira_create_new_group.png) 1. In the **Add group** section, enter a **Name** for the group (for example, `gitlab-developers`), and then select **Add group**. @@ -57,7 +57,7 @@ group to assign permissions to the user: Jira saves your selection, and `gitlab` should appear in the **Group member(s)** area. -![Jira added user to group](../../user/project/integrations/img/jira_added_user_to_group.png) +![Jira added user to group](img/jira_added_user_to_group.png) Next, create a permission scheme for your group. @@ -76,8 +76,8 @@ After creating the group in Jira, grant permissions to the group by creating a p 1. Next to **Administer Projects**, select **Edit**. In the **Group** list, select `gitlab-developers`. - ![Jira group access](../../user/project/integrations/img/jira_group_access.png) + ![Jira group access](img/jira_group_access.png) Write down the new Jira username and its password, as you need them when -[configuring GitLab](../../user/project/integrations/jira.md#configure-gitlab). +[configuring GitLab](development_panel.md#configure-gitlab). diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index 416db5b07fc..b98d28f8c9f 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -50,7 +50,7 @@ From a vulnerability you can create either: - [A Jira issue](#create-a-jira-issue-for-a-vulnerability). Creating a Jira issue requires that -[Jira integration](../../project/integrations/jira_integrations.md) is enabled on the project. Note +[Jira integration](../../../integration/jira/index.md) is enabled on the project. Note that when Jira integration is enabled, the GitLab issue feature is not available. ### Create a GitLab issue for a vulnerability diff --git a/doc/user/project/integrations/discord_notifications.md b/doc/user/project/integrations/discord_notifications.md index 624c0252f23..2ec657eec22 100644 --- a/doc/user/project/integrations/discord_notifications.md +++ b/doc/user/project/integrations/discord_notifications.md @@ -10,7 +10,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w The Discord Notifications service sends event notifications from GitLab to the channel for which the webhook was created. -To send GitLab event notifications to a Discord channel, create a webhook in Discord and configure it in GitLab. +To send GitLab event notifications to a Discord channel, [create a webhook in Discord](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks) +and configure it in GitLab. ## Create webhook diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index 90fdb1939b5..b91a8a1fb3b 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -1,332 +1,8 @@ --- -stage: Create -group: Ecosystem -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 +redirect_to: '../../../integration/jira/index.md' --- -# GitLab Jira integration **(FREE)** +This document was moved to [another location](../../../integration/jira/index.md). -You can use Jira to track work implemented in GitLab. The Jira integration with GitLab makes the -process of working across these systems more efficient. - -The GitLab Jira integration, available in every GitLab project by default, allows you to connect -to any Jira instance, whether on Atlassian cloud or self-managed. - -You can also install the [Jira Development Panel integration](../../../integration/jira/index.md). -For more information about the differences between the two integrations, see -[Jira integrations](jira_integrations.md). - -After you set up this integration, you can cross-reference activity in the GitLab project with any -of your projects in Jira. This includes the ability to close or transition Jira issues when work is -completed in GitLab and: - -- Mention a Jira issue ID in a commit message or MR (merge request) and: - - GitLab links to the Jira issue. - - The Jira issue adds a comment with details and a link back to the activity in GitLab. -- Mention that a commit or MR resolves or closes a specific Jira issue and when it's merged to the default branch: - - The GitLab MR displays a note that it closed the Jira issue. Prior to the merge, MRs indicate which issue they close. - - The Jira issue shows the activity and is closed or otherwise transitioned as specified in your GitLab settings. -- Run a pipeline on an MR linked to a Jira issue: - - The Jira issue shows the current pipeline status (in the sidebar as "builds"). -- Deploy to an environment from an MR linked to a Jira issue: - - The Jira issue shows the status of the deployment (in the sidebar as "deployments"). -- Create or modify a feature flag that mentions a Jira issue in its description: - - The Jira issue shows the details of the feature-flag (in the sidebar as "feature flags"). -- View a list of Jira issues directly in GitLab. **(PREMIUM)** -- Create a Jira issue from a vulnerability. **(ULTIMATE)** - -Additional features provided by the Jira Development Panel integration include: - -- In a Jira issue, display relevant GitLab information in the [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/), including related branches, commits, and merge requests. -- Use Jira [Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html) in GitLab to add Jira comments, log time spent on the issue, or apply any issue transition. -- Showing pipeline, deployment, and feature flags in Jira issues. - -## Configuration - -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview, see [Agile Management - GitLab-Jira Basic Integration](https://www.youtube.com/watch?v=fWvwkx5_00E&feature=youtu.be). - -Each GitLab project can be configured to connect to an entire Jira instance. That means one GitLab -project can interact with _all_ Jira projects in that instance, once configured. For: - -- The [view Jira issues](#view-jira-issues) feature, you must associate a GitLab project with a - specific Jira project. -- Other features, you do not have to explicitly associate a GitLab project with any single Jira - project. - -If you have a single Jira instance, you can pre-fill the settings. For more information, read the -documentation for [central administration of project integrations](../../admin_area/settings/project_integration_management.md). - -To enable the Jira service in GitLab, you must: - -1. Configure the project in Jira. -1. Enter the correct values in GitLab. - -### Configure Jira - -The process for configuring Jira depends on whether you host Jira on your own server or on -[Atlassian cloud](https://www.atlassian.com/cloud). - -#### Jira Server - -Jira Server supports basic authentication. When connecting, a **username and password** are -required. Connecting to Jira Server via CAS is not possible. For more information, see -[set up a user in Jira Server](../../../integration/jira/jira_server_configuration.md). - -#### Jira on Atlassian cloud - -Jira on Atlassian cloud supports authentication through an API token. When connecting to Jira on -Atlassian cloud, an **email and API token** are required. For more information, see -[set up a user in Jira on Atlassian cloud](../../../integration/jira/jira_cloud_configuration.md). - -### Configure GitLab - -> **Notes:** -> -> - The supported Jira versions are `v6.x`, `v7.x`, and `v8.x`. -> - In order to support Oracle's Access Manager, GitLab sends additional cookies -> to enable Basic Auth. The cookie being added to each request is `OBBasicAuth` with -> a value of `fromDialog`. - -To enable the Jira integration in a project: - -1. Go to the project's [Integrations page](overview.md#accessing-integrations) and select the - **Jira** service. - -1. Select **Enable integration**. - -1. Select **Trigger** actions. - This determines whether a mention of a Jira issue in GitLab commits, merge requests, or both, - should link the Jira issue back to that source commit/MR and transition the Jira issue, if - indicated. - -1. To include a comment on the Jira issue when the above reference is made in GitLab, select - **Enable comments**. - -1. To transition Jira issues when a [closing reference](../issues/managing_issues.md#closing-issues-automatically) is made in GitLab, - select **Enable Jira transitions**. - -1. Enter the further details on the page as described in the following table. - - | Field | Description | - | ----- | ----------- | - | `Web URL` | The base URL to the Jira instance web interface which is being linked to this GitLab project. For example, `https://jira.example.com`. | - | `Jira API URL` | The base URL to the Jira instance API. Web URL value is used if not set. For example, `https://jira-api.example.com`. Leave this field blank (or use the same value of `Web URL`) if using **Jira on Atlassian cloud**. | - | `Username or Email` | Created in [configure Jira](#configure-jira) step. Use `username` for **Jira Server** or `email` for **Jira on Atlassian cloud**. | - | `Password/API token` | Created in [configure Jira](#configure-jira) step. Use `password` for **Jira Server** or `API token` for **Jira on Atlassian cloud**. | - -1. To enable users to view Jira issues inside the GitLab project, select **Enable Jira issues** and - enter a Jira project key. **(PREMIUM)** - - You can only display issues from a single Jira project within a given GitLab project. - - WARNING: - If you enable Jira issues with the setting above, all users that have access to this GitLab project - are able to view all issues from the specified Jira project. - -1. To enable creation of issues for vulnerabilities, select **Enable Jira issues creation from vulnerabilities**. - - 1. Select the **Jira issue type**. If the dropdown is empty, select refresh (**{retry}**) and try again. - -1. To verify the Jira connection is working, select **Test settings**. - -1. Select **Save changes**. - -Your GitLab project can now interact with all Jira projects in your instance and the project now -displays a Jira link that opens the Jira project. - -#### Automatic issue transitions - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/...) in GitLab 13.10. - -In this mode the referenced Jira issue is transitioned to the next available status with a category of "Done". - -See the [Configure GitLab](#configure-gitlab) section, check the **Enable Jira transitions** setting and select the **Move to Done** option. - -#### Custom issue transitions - -For advanced workflows you can specify custom Jira transition IDs. - -See the [Configure GitLab](#configure-gitlab) section, check the **Enable Jira transitions** setting, select the **Custom transitions** option, and enter your transition IDs in the text field. - -If you insert multiple transition IDs separated by `,` or `;`, the issue is moved to each state, one after another, using the given order. If a transition fails the sequence is aborted. - -To see the transition IDs on Jira Cloud, edit a workflow in the **Text** view. -The transition IDs display in the **Transitions** column. - -On Jira Server you can get the transition IDs in either of the following ways: - -1. By using the API, with a request like `https://yourcompany.atlassian.net/rest/api/2/issue/ISSUE-123/transitions` - using an issue that is in the appropriate "open" state -1. By mousing over the link for the transition you want and looking for the - "action" parameter in the URL - -Note that the transition ID may vary between workflows (for example, bug vs. story), -even if the status you are changing to is the same. - -#### Disabling comments on Jira issues - -You can continue to have GitLab cross-link a source commit/MR with a Jira issue while disabling the comment added to the issue. - -See the [Configure GitLab](#configure-gitlab) section and uncheck the **Enable comments** setting. - -## Jira issues - -By now you should have [configured Jira](#configure-jira) and enabled the -[Jira service in GitLab](#configure-gitlab). If everything is set up correctly -you should be able to reference and close Jira issues by just mentioning their -ID in GitLab commits and merge requests. - -Jira issue IDs must be formatted in uppercase for the integration to work. - -### Reference Jira issues - -When GitLab project has Jira issue tracker configured and enabled, mentioning -Jira issues in GitLab automatically adds a comment in Jira issue with the -link back to GitLab. This means that in comments in merge requests and commits -referencing an issue, `PROJECT-7` for example, adds a comment in Jira issue in the -format: - -```plaintext -USER mentioned this issue in RESOURCE_NAME of [PROJECT_NAME|LINK_TO_COMMENT]: -ENTITY_TITLE -``` - -- `USER` A user that mentioned the issue. This is the link to the user profile in GitLab. -- `LINK_TO_THE_COMMENT` Link to the origin of mention with a name of the entity where Jira issue was mentioned. -- `RESOURCE_NAME` Kind of resource which referenced the issue. Can be a commit or merge request. -- `PROJECT_NAME` GitLab project name. -- `ENTITY_TITLE` Merge request title or commit message first line. - -![example of mentioning or closing the Jira issue](img/jira_issue_reference.png) - -For example, the following commit references the Jira issue with `PROJECT-1` as its ID: - -```shell -git commit -m "PROJECT-1 Fix spelling and grammar" -``` - -### Close Jira issues - -Jira issues can be closed directly from GitLab by using trigger words in -commits and merge requests. When a commit which contains the trigger word -followed by the Jira issue ID in the commit message is pushed, GitLab -adds a comment in the mentioned Jira issue and immediately closes it (provided -the transition ID was set up correctly). - -There are currently three trigger words, and you can use either one to achieve -the same goal: - -- `Resolves PROJECT-1` -- `Closes PROJECT-1` -- `Fixes PROJECT-1` - -where `PROJECT-1` is the ID of the Jira issue. - -Note the following: - -- Only commits and merges into the project's default branch (usually `master`) - close an issue in Jira. You can change your project's default branch under - [project settings](img/jira_project_settings.png). -- The Jira issue is not transitioned if it has a resolution. - -Let's consider the following example: - -1. For the project named `PROJECT` in Jira, we implemented a new feature - and created a merge request in GitLab. -1. This feature was requested in Jira issue `PROJECT-7` and the merge request - in GitLab contains the improvement -1. In the merge request description we use the issue closing trigger - `Closes PROJECT-7`. -1. Once the merge request is merged, the Jira issue is automatically closed - with a comment and an associated link to the commit that resolved the issue. - -In the following screenshot you can see what the link references to the Jira -issue look like. - -![A Git commit that causes the Jira issue to be closed](img/jira_merge_request_close.png) - -Once this merge request is merged, the Jira issue is automatically closed -with a link to the commit that resolved the issue. - -![The GitLab integration closes Jira issue](img/jira_service_close_issue.png) - -### View Jira issues **(PREMIUM)** - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3622) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. - -You can browse, search, and view issues from a selected Jira project directly in GitLab, -if your GitLab administrator [has configured it](#configure-gitlab): - -1. In the left navigation bar, go to **Jira > Issues list**. -1. The issue list sorts by **Created date** by default, with the newest issues listed at the top: - - ![Jira issues integration enabled](img/jira/open_jira_issues_list_v13.2.png) - -1. To display the most recently updated issues first, click **Last updated**. -1. In GitLab versions 13.10 and later, you can view [individual Jira issues](#view-a-jira-issue). - -Issues are grouped into tabs based on their [Jira status](https://confluence.atlassian.com/adminjiraserver070/defining-status-field-values-749382903.html): - -- The **Open** tab displays all issues with a Jira status in any category other than Done. -- The **Closed** tab displays all issues with a Jira status categorized as Done. -- The **All** tab displays all issues of any status. - -#### View a Jira issue - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299832) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.10 behind a feature flag, disabled by default. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/299832) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.11. - -When viewing the [Jira issues list](#view-jira-issues), select an issue from the -list to open it in GitLab: - -![Jira issue detail view](img/jira/jira_issue_detail_view_v13.10.png) - -#### Search and filter the issues list - -To refine the list of issues, use the search bar to search for any text -contained in an issue summary (title) or description. - -You can also filter by labels, status, reporter, and assignee using URL parameters. -Enhancements to be able to use these through the user interface are [planned](https://gitlab.com/groups/gitlab-org/-/epics/3622). - -- To filter issues by `labels`, specify one or more labels as part of the `labels[]` -parameter in the URL. When using multiple labels, only issues that contain all specified -labels are listed. `/-/integrations/jira/issues?labels[]=backend&labels[]=feature&labels[]=QA` - -- To filter issues by `status`, specify the `status` parameter in the URL. -`/-/integrations/jira/issues?status=In Progress` - -- To filter issues by `reporter`, specify a reporter's Jira display name for the -`author_username` parameter in the URL. `/-/integrations/jira/issues?author_username=John Smith` - -- To filter issues by `assignee`, specify their Jira display name for the -`assignee_username` parameter in the URL. `/-/integrations/jira/issues?assignee_username=John Smith` - -## Troubleshooting - -If these features do not work as expected, it is likely due to a problem with the way the integration settings were configured. - -### GitLab is unable to comment on a Jira issue - -Make sure that the Jira user you set up for the integration has the -correct access permission to post comments on a Jira issue and also to transition -the issue, if you'd like GitLab to also be able to do so. -Jira issue references and update comments do not work if the GitLab issue tracker is disabled. - -### GitLab is unable to close a Jira issue - -Make sure the `Transition ID` you set within the Jira settings matches the one -your project needs to close an issue. - -Make sure that the Jira issue is not already marked as resolved; that is, -the Jira issue resolution field is not set. (It should not be struck through in -Jira lists.) - -### CAPTCHA - -CAPTCHA may be triggered after several consecutive failed login attempts -which may lead to a `401 unauthorized` error when testing your Jira integration. -If CAPTCHA has been triggered, you can't use Jira's REST API to -authenticate with the Jira site. You need to log in to your Jira instance -and complete the CAPTCHA. +<!-- This redirect file can be deleted after 2021-07-07. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/jira_integrations.md b/doc/user/project/integrations/jira_integrations.md index 1f895a9e2fa..485b48df01b 100644 --- a/doc/user/project/integrations/jira_integrations.md +++ b/doc/user/project/integrations/jira_integrations.md @@ -1,34 +1,8 @@ --- -stage: Create -group: Ecosystem -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 +redirect_to: '../../../integration/jira/index.md' --- -# Jira integrations **(FREE)** +This document was moved to [another location](../../../integration/jira/index.md). -If your organization uses [Jira](https://www.atlassian.com/software/jira) issues, -you can [migrate](../../../user/project/import/jira.md) your issues from Jira and work -exclusively in GitLab. - -However, if you'd like to continue to use Jira, you can integrate it with GitLab. - -There are two ways to use GitLab with Jira: - -- [Jira integration](jira.md). Connect a GitLab project - to a Jira instance. The Jira instance can be hosted by you or in [Atlassian cloud](https://www.atlassian.com/cloud). -- [Jira Development panel integration](../../../integration/jira_development_panel.md). - Connect all GitLab projects under a group or personal namespace. - -The integration you choose depends on the capabilities you require. -You can also install both at the same time. - -| Capability | Jira integration | Jira Development panel integration | -|-|-|-| -| Mention a Jira issue ID in GitLab and a link to the Jira issue is created. | Yes. | No. | -| Mention a Jira issue ID in GitLab and the Jira issue shows the GitLab issue or merge request. | Yes. A Jira comment with the GitLab issue or MR title links to GitLab. The first mention is also added to the Jira issue under **Web links**. | Yes, in the issue's Development panel. | -| Mention a Jira issue ID in a GitLab commit message and the Jira issue shows the commit message. | Yes. The entire commit message is displayed in the Jira issue as a comment and under **Web links**. Each message links back to the commit in GitLab. | Yes, in the issue's Development panel and optionally with a custom comment on the Jira issue using Jira Smart Commits. | -| Mention a Jira issue ID in a GitLab branch name and the Jira issue shows the branch name. | No. | Yes, in the issue's Development panel. | -| Add Jira time tracking to an issue. | No. | Yes. Time can be specified using Jira Smart Commits. | -| Use a Git commit or merge request to transition or close a Jira issue. | Yes. Only a single transition type, typically configured to close the issue by setting it to Done. | Yes. Transition to any state using Jira Smart Commits. | -| Display a list of Jira issues. | Yes. **(PREMIUM)** | No. | -| Create a Jira issue from a vulnerability or finding. **(ULTIMATE)** | Yes. | No. | +<!-- This redirect file can be deleted after <2021-07-13>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index 53798ba664f..ca0d92b4f88 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -24,43 +24,43 @@ want to configure. Click on the service links to see further configuration instructions and details. -| Service | Description | Service Hooks | -| Asana | Add commit messages as comments to Asana tasks | No | -| Assembla | Project Management Software (Source Commits Endpoint) | No | -| [Atlassian Bamboo CI](bamboo.md) | A continuous integration and build server | Yes | -| Buildkite | Continuous integration and deployments | Yes | -| [Bugzilla](bugzilla.md) | Bugzilla issue tracker | No | -| Campfire | Simple web-based real-time group chat | No | -| [Confluence](../../../api/services.md#confluence-service) | Replaces the link to the internal wiki with a link to a Confluence Cloud Workspace | No | -| Custom Issue Tracker | Custom issue tracker | No | -| [Discord Notifications](discord_notifications.md) | Receive event notifications in Discord | No | -| Drone CI | Continuous Integration platform built on Docker, written in Go | Yes | -| [Emails on push](emails_on_push.md) | Email the commits and diff of each push to a list of recipients | No | -| External wiki | Replaces the link to the internal wiki with a link to an external wiki | No | -| Flowdock | Flowdock is a collaboration web app for technical teams | No | -| [Generic alerts](../../../operations/incident_management/integrations.md) **(ULTIMATE)** | Receive alerts on GitLab from any source | No | -| [GitHub](github.md) **(PREMIUM)** | Sends pipeline notifications to GitHub | No | -| [Hangouts Chat](hangouts_chat.md) | Receive events notifications in Google Hangouts Chat | No | -| [Irker (IRC gateway)](irker.md) | Send IRC messages, on update, to a list of recipients through an Irker gateway | No | -| [Jira](jira.md) | Jira issue tracker | No | -| [Jenkins](../../../integration/jenkins.md) **(STARTER)** | An extendable open source continuous integration server | Yes | -| JetBrains TeamCity CI | A continuous integration and build server | Yes | -| [Mattermost slash commands](mattermost_slash_commands.md) | Mattermost chat and ChatOps slash commands | No | -| [Mattermost Notifications](mattermost.md) | Receive event notifications in Mattermost | No | -| [Microsoft teams](microsoft_teams.md) | Receive notifications for actions that happen on GitLab into a room on Microsoft Teams using Office 365 Connectors | No | -| Packagist | Update your projects on Packagist, the main Composer repository | Yes | -| Pipelines emails | Email the pipeline status to a list of recipients | No | -| [Slack Notifications](slack.md) | Send GitLab events (for example, an issue was created) to Slack as notifications | No | -| [Slack slash commands](slack_slash_commands.md) **(FREE SELF)** | Use slash commands in Slack to control GitLab | No | -| [GitLab Slack application](gitlab_slack_application.md) **(FREE SAAS)** | Use Slack's official application | No | -| PivotalTracker | Project Management Software (Source Commits Endpoint) | No | -| [Prometheus](prometheus.md) | Monitor the performance of your deployed apps | No | -| Pushover | Pushover makes it easy to get real-time notifications on your Android device, iPhone, iPad, and Desktop | No | -| [Redmine](redmine.md) | Redmine issue tracker | No | -| [EWM](ewm.md) | EWM work item tracker | No | -| [Unify Circuit](unify_circuit.md) | Receive events notifications in Unify Circuit | No | -| [Webex Teams](webex_teams.md) | Receive events notifications in Webex Teams | No | -| [YouTrack](youtrack.md) | YouTrack issue tracker | No | +| Service | Description | Service hooks | +| --------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------- | +| [Asana](asana.md) | Add commit messages as comments to Asana tasks. | **{dotted-circle}** No | +| Assembla | Manage projects. | **{dotted-circle}** No | +| [Atlassian Bamboo CI](bamboo.md) | Run CI/CD pipelines with Atlassian Bamboo. | **{check-circle}** Yes | +| [Bugzilla](bugzilla.md) | Use Bugzilla as the issue tracker. | **{dotted-circle}** No | +| Buildkite | Run CI/CD pipelines with Buildkite. | **{check-circle}** Yes | +| Campfire | Connect to chat. | **{dotted-circle}** No | +| [Confluence Workspace](../../../api/services.md#confluence-service) | Replace the link to the internal wiki with a link to a Confluence Cloud Workspace. | **{dotted-circle}** No | +| [Custom issue tracker](custom_issue_tracker.md) | Use a custom issue tracker. | **{dotted-circle}** No | +| [Discord Notifications](discord_notifications.md) | Send notifications about project events to a Discord channel. | **{dotted-circle}** No | +| Drone CI | Run CI/CD pipelines with Drone. | **{check-circle}** Yes | +| [Emails on push](emails_on_push.md) | Send commits and diff of each push by email. | **{dotted-circle}** No | +| [EWM](ewm.md) | Use IBM Engineering Workflow Management as the issue tracker. | **{dotted-circle}** No | +| External wiki | Replace internal wiki link with external wiki link. | **{dotted-circle}** No | +| Flowdock | Use Flowdock with GitLab. | **{dotted-circle}** No | +| [GitHub](github.md) | Obtain statuses for commits and pull requests. | **{dotted-circle}** No | +| [Hangouts Chat](hangouts_chat.md) | Receive events notifications. | **{dotted-circle}** No | +| [Irker (IRC gateway)](irker.md) | Send IRC messages. | **{dotted-circle}** No | +| [Jenkins](../../../integration/jenkins.md) | Run CI/CD pipelines with Jenkins. | **{check-circle}** Yes | +| JetBrains TeamCity CI | Run CI/CD pipelines with TeamCity. | **{check-circle}** Yes | +| [Jira](jira.md) | Use Jira as the issue tracker. | **{dotted-circle}** No | +| [Mattermost notifications](mattermost.md) | Send notifications about project events to Mattermost channels. | **{dotted-circle}** No | +| [Mattermost slash commands](mattermost_slash_commands.md) | Perform common tasks with slash commands. | **{dotted-circle}** No | +| [Microsoft Teams notifications](microsoft_teams.md) | Receive event notifications. | **{dotted-circle}** No | +| Packagist | Update your projects. | **{check-circle}** Yes | +| Pipelines emails | Send the pipeline status to a list of recipients by email. | **{dotted-circle}** No | +| PivotalTracker | Use PivotalTracker as the issue tracker. | **{dotted-circle}** No | +| [Prometheus](prometheus.md) | Monitor application metrics. | **{dotted-circle}** No | +| Pushover | Get real-time notifications on your device. | **{dotted-circle}** No | +| [Redmine](redmine.md) | Use Redmine as the issue tracker. | **{dotted-circle}** No | +| [Slack application](gitlab_slack_application.md) | Use Slack's official GitLab application. | **{dotted-circle}** No | +| [Slack notifications](slack.md) | Send notifications about project events to Slack. | **{dotted-circle}** No | +| [Slack slash commands](slack_slash_commands.md) | Enable slash commands in workspace. | **{dotted-circle}** No | +| [Unify Circuit](unify_circuit.md) | Receive events notifications. | **{dotted-circle}** No | +| [Webex Teams](webex_teams.md) | Receive events notifications. | **{dotted-circle}** No | +| [YouTrack](youtrack.md) | Use YouTrack as the issue tracker. | **{dotted-circle}** No | ## Push hooks limit diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index c8922890deb..33ab5f6580d 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -18,26 +18,37 @@ submit them through a merge request to the repository you don't have access to. ## Creating a fork -Forking a project is, in most cases, a two-step process. +To fork an existing project in GitLab: -1. On the project's home page, in the top right, click the **Fork** button. +1. On the project's home page, in the top right, click **{fork}** **Fork**. - ![Fork button](img/forking_workflow_fork_button.png) + ![Fork button](img/forking_workflow_fork_button_v13_10.png) -1. Click a namespace to fork to. Only namespaces you have Developer and higher [permissions](../../permissions.md) for are shown. +1. Select the project to fork to: - NOTE: - The project path must be unique within the namespace. + - *(Recommended method)* Below **Select a namespace to fork the project**, identify + the project you want to fork to, and click **Select**. Only namespaces you have + Developer and higher [permissions](../../permissions.md) for are shown. + + ![Choose namespace](img/forking_workflow_choose_namespace_v13_10.png) - ![Choose namespace](img/forking_workflow_choose_namespace_v13_2.png) + - *(Experimental method)* If your GitLab administrator has + [enabled the experimental fork project form](#enable-or-disable-the-fork-project-form), read + [Create a fork with the fork project form](#create-a-fork-with-the-fork-project-form). + Only namespaces you have Developer and higher + [permissions](../../permissions.md) for are shown. + + NOTE: + The project path must be unique in the namespace. -The fork is created. The permissions you have in the namespace are your permissions in the fork. +GitLab creates your fork, and redirects you to the project page for your new fork. +The permissions you have in the namespace are your permissions in the fork. WARNING: When a public project with the repository feature set to **Members Only** is forked, the repository is public in the fork. The owner -of the fork must manually change the visibility. This is being -fixed in [#36662](https://gitlab.com/gitlab-org/gitlab/-/issues/36662). +of the fork must manually change the visibility. Issue +[#36662](https://gitlab.com/gitlab-org/gitlab/-/issues/36662) exists for this issue. ## Repository mirroring @@ -71,3 +82,44 @@ changes are added to the repository and branch you're merging into. ## Removing a fork relationship You can unlink your fork from its upstream project in the [advanced settings](../settings/index.md#removing-a-fork-relationship). + +## Create a fork with the fork project form **(FREE SELF)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15013) in GitLab 13.11. +> - It's [deployed behind a feature flag](../../../user/feature_flags.md), disabled by default. +> - It's disabled on GitLab.com. +> - It's not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-the-fork-project-form). **(FREE SELF)** + +This experimental version of the fork project form is available only if your GitLab +administrator has [enabled it](#enable-or-disable-the-fork-project-form): + +![Choose namespace](img/fork_form_v13_10.png) + +To use it, follow the instructions at [Creating a fork](#creating-a-fork) and provide: + +- The project name. +- The project URL. +- The project slug. +- *(Optional)* The project description. +- The visibility level for your fork. + +### Enable or disable the fork project form **(FREE SELF)** + +The new [fork project form](#create-a-fork-with-the-fork-project-form) is under +development and not ready for production use. It is deployed behind a feature flag +that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:fork_project_form) +``` + +To disable it: + +```ruby +Feature.disable(:fork_project_form) +``` diff --git a/doc/user/project/repository/img/fork_form_v13_10.png b/doc/user/project/repository/img/fork_form_v13_10.png Binary files differnew file mode 100644 index 00000000000..00c2f89a844 --- /dev/null +++ b/doc/user/project/repository/img/fork_form_v13_10.png diff --git a/doc/user/project/repository/img/forking_workflow_choose_namespace_v13_10.png b/doc/user/project/repository/img/forking_workflow_choose_namespace_v13_10.png Binary files differnew file mode 100644 index 00000000000..74f65cb663d --- /dev/null +++ b/doc/user/project/repository/img/forking_workflow_choose_namespace_v13_10.png diff --git a/doc/user/project/repository/img/forking_workflow_fork_button.png b/doc/user/project/repository/img/forking_workflow_fork_button.png Binary files differdeleted file mode 100644 index eea62892232..00000000000 --- a/doc/user/project/repository/img/forking_workflow_fork_button.png +++ /dev/null diff --git a/doc/user/project/repository/img/forking_workflow_fork_button_v13_10.png b/doc/user/project/repository/img/forking_workflow_fork_button_v13_10.png Binary files differnew file mode 100644 index 00000000000..376beb803a7 --- /dev/null +++ b/doc/user/project/repository/img/forking_workflow_fork_button_v13_10.png |