diff --git a/docs/integrations/images/automated-onboarding.png b/docs/integrations/images/automated-onboarding.png new file mode 100644 index 00000000..f60f6891 Binary files /dev/null and b/docs/integrations/images/automated-onboarding.png differ diff --git a/docs/integrations/images/enter-url.png b/docs/integrations/images/enter-url.png deleted file mode 100644 index b8a9883f..00000000 Binary files a/docs/integrations/images/enter-url.png and /dev/null differ diff --git a/docs/integrations/images/manual-onboarding.png b/docs/integrations/images/manual-onboarding.png new file mode 100644 index 00000000..cffb7f26 Binary files /dev/null and b/docs/integrations/images/manual-onboarding.png differ diff --git a/docs/integrations/images/self-hosted-gitlab-host-url.png b/docs/integrations/images/self-hosted-gitlab-host-url.png new file mode 100644 index 00000000..ebab65bc Binary files /dev/null and b/docs/integrations/images/self-hosted-gitlab-host-url.png differ diff --git a/docs/integrations/self-hosted-gitlab.md b/docs/integrations/self-hosted-gitlab.md index eccd5c52..a6a5f552 100644 --- a/docs/integrations/self-hosted-gitlab.md +++ b/docs/integrations/self-hosted-gitlab.md @@ -22,32 +22,57 @@ select Self-Hosted GitLab On this page, enter the URL of your self-managed GitLab instance and click submit. Once, you submit, we check our database for a record of your -organization. +organization and if we find an existing one, we are starting the login process. -![Untitled](./images/enter-url.png) +![Untitled](./images/self-hosted-gitlab-host-url.png) -### **Step 3: Enter Admin Personal Access Token (First time only)** +If the self-managed GitLab instance is not found, we initiate the onboarding process, which can be either manual or automated. -If this is the first time you are signing up with your instance, we need an -admin access token for setting up the CodeRabbit. +### **Step 3: Onboarding Manual or Automated** + +#### 1. Automated onboarding +![Untitled](./images/automated-onboarding.png) #### **Why do we need the Admin Access Token?** Admin access token is required to set up a new CodeRabbit bot user within your self-managed instance. The token is needed only once during the initial setup -process and is not stored in our database. Once the token is generated, you can -set its minimum expiration period. This is the standard approach used by other -products in this category. This is not automatically installing the CodeRabbit +process. Once the token is generated, you can set its minimum expiration period. +This is the standard approach used by other products in this category. +This is not automatically installing the CodeRabbit app across all projects. You will add CodeRabbit manually on the projects you wish, as the next step. -#### **Generating Admin Personal Access token** +#### 2. Manual onboarding + +For the manual onboarding process we need to create the [CodeRabbit user](#creating-coderabbit-user) and the [OAuth2 GitLab application](#creating-oauth2-application). +![Untitled](./images/manual-onboarding.png) + +#### **Creating CodeRabbit user** +This feature will work with any user from your organization, but we strongly suggest creating a +dedicated user called **CodeRabbitAI**. This ensures clarify about which user is used for our +application and allows for better fine-grained access control. + +To create users in GitLab, log in with an instance admin account and follow the steps provided in the [GitLab documentation](https://docs.gitlab.com/ee/user/profile/account/create_accounts.html#create-users-in-admin-area). +After the user is created, you can retrieve the **User ID** from that user's profile and generate an [**access token**](#generating-personal-access-token). +The access token is used to post reviews on merge requests. + +#### **Creating OAuth2 application** +For self-managed GitLab, we recommend creating an instance-wide application unless you want the reviews to be limited to a single group or user. + +Please follow the steps outlined in the [GitLab documentation](https://docs.gitlab.com/ee/integration/oauth_provider.html#create-an-instance-wide-application) for creating the application. + +Requirements: +1. Scopes: `api read_user email` +2. Callback URL: `https://app.coderabbit.ai/login` + +#### **Generating Personal Access token** GitLab offers an option to generate a personal access token for adding a new user and setting up the application in the self-managed instance. To generate the token, please follow the process outlined below: -1. Login to your self-hosted instance. Ensure sure you have admin rights. +1. Login to your self-hosted instance. For [automated onboarding](#1-automated-onboarding) ensure you have admin rights. 2. On the left sidebar, select your avatar. 3. Select Edit profile. 4. On the left sidebar, select Access Tokens. @@ -56,15 +81,15 @@ the token, please follow the process outlined below: setup, so the minimum expiry time is sufficient. 7. If you do not enter an expiry date, the expiry date is automatically set to 365 days later than the current date. -8. Make sure, you select the scope: `api` +8. Make sure, you select the scopes: `api user email` 9. Select Create personal access token. 10. Please note down this token as this will be visible one time only ![Untitled](./images/admin-access-token.png) -### **Step 4: Paste the token and click submit** +### **Step 4: Paste the details and click submit** -- Submit the access token. +- Submit the form. - We will handle the setup process for you. - On subsequent visits, your setup will be automatically detected, allowing for direct login. ![Untitled](./images/self-hosted-page.png)