diff options
Diffstat (limited to 'doc/user/project/integrations/github.md')
-rw-r--r-- | doc/user/project/integrations/github.md | 50 |
1 files changed, 29 insertions, 21 deletions
diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 47a81594ca9..9f1ea3796c6 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -6,17 +6,17 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitHub project integration **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3836) in GitLab Premium 10.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3836) in GitLab 10.6. -GitLab provides an integration for updating the pipeline statuses on GitHub. -This is especially useful if using GitLab for CI/CD only. - -This project integration is separate from the [instance wide GitHub integration](../import/github.md#mirror-a-repository-and-share-pipeline-status) -and is automatically configured on [GitHub import](../../../integration/github.md). +You can update GitHub with pipeline status updates from GitLab. +This integration can help you if you use GitLab for CI/CD. ![Pipeline status update on GitHub](img/github_status_check_pipeline_update.png) -## Configuration +This project integration is separate from the [instance-wide GitHub integration](../import/github.md#mirror-a-repository-and-share-pipeline-status) +and is automatically configured when you import a [GitHub project](../../../integration/github.md). + +## Configure the integration This integration requires a [GitHub API token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) with `repo:status` access granted. @@ -26,31 +26,39 @@ Complete these steps on GitHub: 1. Go to your **Personal access tokens** page at <https://github.com/settings/tokens>. 1. Select **Generate new token**. 1. Under **Note**, enter a name for the new token. -1. Ensure that `repo:status` is checked and select **Generate token**. +1. Ensure `repo:status` is selected and select **Generate token**. 1. Copy the generated token to use in GitLab. Complete these steps in GitLab: -1. Go to the project you want to configure. -1. Go to the [Integrations page](overview.md#accessing-integrations) +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. 1. Select **GitHub**. -1. Ensure that the **Active** toggle is enabled. -1. Paste the token you generated on GitHub. -1. Enter the path to your project on GitHub, such as `https://github.com/username/repository`. -1. (Optional) To disable static status check names, clear the **Enable static status check names** checkbox. -1. Select **Save changes** or optionally select **Test settings**. +1. Ensure the **Active** checkbox is selected. +1. In **Token**, paste the token you generated on GitHub. +1. In **Repository URL**, enter the path to your project on GitHub, such as `https://github.com/username/repository`. +1. Optional. To disable [static status check names](#static-or-dynamic-status-check-names), clear the **Enable static status check names** checkbox. +1. Optional. Select **Test settings**. +1. Select **Save changes**. After configuring the integration, see [Pipelines for external pull requests](../../../ci/ci_cd_for_external_repos/#pipelines-for-external-pull-requests) to configure pipelines to run for open pull requests. ### Static or dynamic status check names -> - Introduced in GitLab 11.5: using static status check names as opt-in option. -> - [In GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/issues/9931), static status check names is default behavior for new projects. +> - Introduced in GitLab 11.5 with static status check names as an opt-in option. +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/9931) in GitLab 12.4 to make static status check names the default behavior for new projects. + +A status check name can be static or dynamic: + +- **Static**: The hostname of your + GitLab instance is appended to the status check name. -This makes it possible to mark these status checks as **Required** on GitHub. +- **Dynamic**: The branch name is appended + to the status check name. -When **Enable static status check names** is checked on the integration page, your -GitLab instance host name is appended to a status check name. +The **Enable static status check names** option enables you to configure +required status checks in GitHub, which need a consistent (static) name to work correctly. -When unchecked, it uses dynamic status check names and appends the branch name. +If you [disable this option](#configure-the-integration), +GitLab uses dynamic status check names instead. |