From 94cf7931683dd10817454db5e2c3bb30e65496d1 Mon Sep 17 00:00:00 2001 From: hpal Date: Wed, 23 Oct 2024 18:54:21 +0100 Subject: [PATCH 1/4] Update GitLab installation with FAQ --- .../git/gitlab/installation.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab/installation.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab/installation.md index 6b9ad2d75..96128fc12 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab/installation.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab/installation.md @@ -27,7 +27,6 @@ This page outlines the following steps: - If you choose the real-time & always-on installation method, a Kubernetes cluster to install the integration on. - Your Port user role is set to `Admin`. - ## Setup ### Create a GitLab group access token @@ -495,3 +494,20 @@ pipeline { + +### FAQ + +#### Do I need to commit to a new repository for it to appear in Port when using GitLab? + +
+Answer (click to expand) + +Yes, a commit is necessary for a new repository to appear in Port when using GitLab. Here's why: + +- **Webhook Limitations**: GitLab does not support `project_create` events for system hooks. This means that simply creating a new repository will not trigger a webhook event to update Port. +- **Initial Commit Requirement**: To have the repository appear in Port, you need to make an initial commit. This action will trigger a webhook event (if configured) and update Port in real-time. +- **Scheduled Resync**: If a repository is created without an initial commit, it will be picked up during the next scheduled resync. + +This behavior is due to the current capabilities of GitLab's webhook system. For more information on available webhook events in GitLab, see the [official GitLab documentation on webhook events](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html). + +
From 77bf95f6bdf6adbd7c2c657ed4c005066beebea6 Mon Sep 17 00:00:00 2001 From: hpal Date: Wed, 23 Oct 2024 19:05:24 +0100 Subject: [PATCH 2/4] Update installation.md --- .../git/gitlab/installation.md | 41 +++++++------------ 1 file changed, 15 insertions(+), 26 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab/installation.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab/installation.md index 96128fc12..e3ccecd83 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab/installation.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab/installation.md @@ -161,20 +161,23 @@ By default, if `appHost` is provided, the integration will create group webhooks #### System Webhooks -To create a system hook there are two options: +To create a system hook in GitLab, you must set `useSystemHook: true` and choose one of these setup methods: -:::note -In both options you'll need to provide the `useSystemHook` parameter with the value `true`. -::: +1. **Automatic Setup** - Provide a token with admin privileges using the `tokenMapping` parameter +2. **Manual Setup** - Create the system hook yourself in GitLab: + - Follow GitLab's [system hook setup guide](https://docs.gitlab.com/ee/administration/system_hooks.html#create-a-system-hook) + - Set the URL to `{appHost}/integration/system/hook` (e.g., `https://my-gitlab-integration.com/integration/system/hook`) + - Enable the supported triggers: `push` and `merge_request` + +:::info Repository Setup and Initial Commit +Due to GitLab webhook limitations, new repositories require special handling: -1. Provide a token with admin privileges in GitLab using the `tokenMapping` parameter. - - When choosing this option, the integration will create the system hook in your GitLab account automatically. -2. Create the system hook manually - - Follow the instructions for creating a system hook in GitLab [here](https://docs.gitlab.com/ee/administration/system_hooks.html#create-a-system-hook). - - In the `URL` field, provide the `appHost` parameter value with the path `/integration/system/hook`. e.g. `https://my-gitlab-integration.com/integration/system/hook`. - - From the `Triggers` section, the GitLab integration currently supports the following events: - - `push` - - `merge_request` +- A repository will only appear in Port after its first commit +- This is because GitLab webhooks don't support `project_create` events +- Empty repositories (no commits) will only appear after the next scheduled resync + +For more details, see GitLab's [webhook events documentation](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html). +::: ![GitLab System Hook](/img/integrations/gitlab/GitLabSystemHook.png) @@ -495,19 +498,5 @@ pipeline { -### FAQ -#### Do I need to commit to a new repository for it to appear in Port when using GitLab? -
-Answer (click to expand) - -Yes, a commit is necessary for a new repository to appear in Port when using GitLab. Here's why: - -- **Webhook Limitations**: GitLab does not support `project_create` events for system hooks. This means that simply creating a new repository will not trigger a webhook event to update Port. -- **Initial Commit Requirement**: To have the repository appear in Port, you need to make an initial commit. This action will trigger a webhook event (if configured) and update Port in real-time. -- **Scheduled Resync**: If a repository is created without an initial commit, it will be picked up during the next scheduled resync. - -This behavior is due to the current capabilities of GitLab's webhook system. For more information on available webhook events in GitLab, see the [official GitLab documentation on webhook events](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html). - -
From 7abd632c0c462ffb424031ae2f3c1d4f84036a56 Mon Sep 17 00:00:00 2001 From: hpal Date: Thu, 31 Oct 2024 17:02:49 +0000 Subject: [PATCH 3/4] Update installation.md --- .../sync-data-to-catalog/git/gitlab/installation.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab/installation.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab/installation.md index e3ccecd83..e83c71236 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab/installation.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab/installation.md @@ -161,19 +161,18 @@ By default, if `appHost` is provided, the integration will create group webhooks #### System Webhooks -To create a system hook in GitLab, you must set `useSystemHook: true` and choose one of these setup methods: +To create a system hook in GitLab, you must set `useSystemHook: true` and choose one of the following setup methods: -1. **Automatic Setup** - Provide a token with admin privileges using the `tokenMapping` parameter +1. **Automatic Setup** - Provide a token with admin privileges using the `tokenMapping` parameter. 2. **Manual Setup** - Create the system hook yourself in GitLab: - - Follow GitLab's [system hook setup guide](https://docs.gitlab.com/ee/administration/system_hooks.html#create-a-system-hook) - - Set the URL to `{appHost}/integration/system/hook` (e.g., `https://my-gitlab-integration.com/integration/system/hook`) - - Enable the supported triggers: `push` and `merge_request` + - Follow GitLab's [system hook setup guide](https://docs.gitlab.com/ee/administration/system_hooks.html#create-a-system-hook). + - Set the URL to `{appHost}/integration/system/hook` (e.g., `https://my-gitlab-integration.com/integration/system/hook`). + - Enable the supported triggers: `push` and `merge_request`. :::info Repository Setup and Initial Commit Due to GitLab webhook limitations, new repositories require special handling: -- A repository will only appear in Port after its first commit -- This is because GitLab webhooks don't support `project_create` events +- A repository will only appear in Port after its first commit (GitLab webhooks don't support `project_create` events) - Empty repositories (no commits) will only appear after the next scheduled resync For more details, see GitLab's [webhook events documentation](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html). From 797127b96e59fa58241e851e61e289e184d33791 Mon Sep 17 00:00:00 2001 From: hadar-co Date: Tue, 24 Dec 2024 14:37:48 +0200 Subject: [PATCH 4/4] Update docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab/installation.md --- .../sync-data-to-catalog/git/gitlab/installation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab/installation.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab/installation.md index b657c13d6..47bff9ae6 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab/installation.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab/installation.md @@ -176,8 +176,8 @@ To create a system hook in GitLab, you must set `useSystemHook: true` and choose :::info Repository Setup and Initial Commit Due to GitLab webhook limitations, new repositories require special handling: -- A repository will only appear in Port after its first commit (GitLab webhooks don't support `project_create` events) -- Empty repositories (no commits) will only appear after the next scheduled resync +- A repository will only appear in Port after its first commit (GitLab webhooks don't support `project_create` events). +- Empty repositories (no commits) will only appear after the next scheduled resync. For more details, see GitLab's [webhook events documentation](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html). :::