https://docs-production-katalon.netlify.app/assets/js/48b569df.dbd0e68e.js

1"use strict";(self.webpackChunkKatalon_Docs=self.webpackChunkKatalon_Docs||[]).push([[3061],{9470:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>a,contentTitle:()=>l,default:()=>h,frontMatter:()=>o,metadata:()=>i,toc:()=>c});const i=JSON.parse('{"id":"integrations/repository/gitlab-integration","title":"GitLab Integration","description":"This document explains how to set up and manage a GitLab integration in Katalon True Platform.","source":"@site/docs/katalon-platform/integrations/repository/gitlab-integration.md","sourceDirName":"integrations/repository","slug":"/integrations/repository/gitlab-integration","permalink":"/katalon-platform/integrations/repository/gitlab-integration","draft":false,"unlisted":false,"tags":[],"version":"current","lastUpdatedAt":1778059093000,"frontMatter":{"title":"GitLab Integration"},"sidebar":"katalon-platform","previous":{"title":"GitHub Integration","permalink":"/katalon-platform/integrations/repository/github-integration"},"next":{"title":"Bitbucket Integration","permalink":"/katalon-platform/integrations/repository/bitbucket-integration"}}');var s=t(74848),r=t(28453);const o={title:"GitLab Integration"},l=void 0,a={},c=[{value:"Step 1: Authorize the GitLab Connection (Account-level)",id:"step-1-authorize-the-gitlab-connection-account-level",level:2},{value:"Result",id:"result",level:4},{value:"Step 2: Link Repository to Project (Project-level)",id:"step-2-link-repository-to-project-project-level",level:2},{value:"Step 3: Enable Updates to GitLab",id:"step-3-enable-updates-to-gitlab",level:2},{value:"View Test Cases or Test Suites Synced from GitLab",id:"view-test-cases-or-test-suites-synced-from-gitlab",level:2},{value:"Managing Your GitLab Integration",id:"managing-your-gitlab-integration",level:2},{value:"Disconnect a GitLab Connection",id:"disconnect-a-gitlab-connection",level:3},{value:"Archive a Linked Repo",id:"archive-a-linked-repo",level:3},{value:"Restore an Archived Integration",id:"restore-an-archived-integration",level:3}];function d(e){const n={a:"a",admonition:"admonition",blockquote:"blockquote",br:"br",code:"code",h2:"h2",h3:"h3",h4:"h4",hr:"hr",li:"li",ol:"ol",p:"p",strong:"strong",ul:"ul",...(0,r.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(n.p,{children:"This document explains how to set up and manage a GitLab integration in Katalon True Platform."}),"\n",(0,s.jsx)(n.p,{children:"Connect GitLab to Katalon True Platform to sync test cases and test suites between the two systems."}),"\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.strong,{children:"Find your starting point:"})}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["Setting up GitLab for the first time? \u2192 Start at ",(0,s.jsx)(n.strong,{children:"Step 1"})]}),"\n",(0,s.jsxs)(n.li,{children:["Your org is already connected and you just need to link a repo? \u2192 Skip to ",(0,s.jsx)(n.strong,{children:"Step 2"})]}),"\n",(0,s.jsxs)(n.li,{children:["You just need to push your edits back to GitLab? \u2192 Skip to ",(0,s.jsx)(n.strong,{children:"Step 3"})]}),"\n"]}),"\n",(0,s.jsx)(n.hr,{}),"\n",(0,s.jsx)(n.h2,{id:"step-1-authorize-the-gitlab-connection-account-level",children:"Step 1: Authorize the GitLab Connection (Account-level)"}),"\n",(0,s.jsx)(n.p,{children:"This step establishes the connection between Katalon True Platform and GitLab. No data is synced yet."}),"\n",(0,s.jsx)(n.admonition,{title:"requirements",type:"warning",children:(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["You must have the ",(0,s.jsx)(n.strong,{children:"Account Admin or System Admin"})," role in Katalon True Platform to perform this action."]}),"\n",(0,s.jsxs)(n.li,{children:["The ",(0,s.jsx)(n.strong,{children:"Personal Access Token (PAT)"})," must be created by a user with ",(0,s.jsx)(n.strong,{children:"full access to all repositories"})," in the GitLab organization. If using a PAT with limited permissions may cause errors when integrating repositories at the project level."]}),"\n"]})}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:["Go to ",(0,s.jsx)(n.strong,{children:"Account Settings > Integrations"})," and click ",(0,s.jsx)(n.strong,{children:(0,s.jsx)(n.code,{children:"+ Create Integration"})}),"."]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:["In the ",(0,s.jsx)(n.strong,{children:"Available Integration"})," list, select ",(0,s.jsx)(n.strong,{children:"GitLab"}),"."]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsx)(n.p,{children:"Fill in the required fields:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Integration Name"}),": a custom label (max 50 characters)."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Organization Account URL"}),": your GitLab org URL, e.g. ",(0,s.jsx)(n.code,{children:"https://gitlab.com/your-org-name"}),"."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"GitLab Personal Access Token"}),": To generate a PAT, refer to this ",(0,s.jsx)(n.a,{href:"https://docs.gitlab.com/user/profile/personal_access_tokens/",children:"GitLab documentation on creating a personal access token"}),"."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Description (Optional)"}),": Max 255 characters."]}),"\n"]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:["If connecting to ",(0,s.jsx)(n.strong,{children:"GitLab Enterprise Server or a self-managed instance"}),", fill in the same fields above."]}),"\n"]}),"\n"]}),"\n",(0,s.jsxs)(n.blockquote,{children:["\n",(0,s.jsxs)(n.p,{children:["Supported version: ",(0,s.jsx)(n.strong,{children:"Gitlab Server 18.0.1-ee and above"}),". You can optionally configure a Cloud Tunnel for local testing. See ",(0,s.jsx)(n.a,{href:"/katalon-testcloud/local-testing-with-testcloud/local-testing-with-testcloud-in-testops",children:"Local testing with Test Execution - Cloud"})," in Katalon True Platform for steps to install the agent, generate tunnel, and manage tunnel availability."]}),"\n"]}),"\n",(0,s.jsxs)(n.ol,{start:"5",children:["\n",(0,s.jsxs)(n.li,{children:["Click ",(0,s.jsx)(n.strong,{children:"Test Connection"})," to validate, then ",(0,s.jsx)(n.strong,{children:"Save"}),"."]}),"\n"]}),"\n",(0,s.jsx)(n.h4,{id:"result",children:"Result"}),"\n",(0,s.jsxs)(n.p,{children:["To verify if the connection is active, navigate to\xa0",(0,s.jsx)(n.strong,{children:"Account Settings > Integrations"}),". Your GitLab integration will be listed under the\xa0",(0,s.jsx)(n.strong,{children:"Integration list"}),"."]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["If the status initially shows as\xa0",(0,s.jsx)(n.strong,{children:"Inactive"}),", reload the page to update the status to\xa0",(0,s.jsx)(n.strong,{children:"Active"}),"."]}),"\n",(0,s.jsxs)(n.li,{children:["If the status shows\xa0",(0,s.jsx)(n.strong,{children:"Error"}),", verify all required configuration fields, especially the Personal Access Token (PAT), and confirm it is valid and configured correctly in the account-level integration."]}),"\n"]}),"\n",(0,s.jsx)(n.hr,{}),"\n",(0,s.jsx)(n.h2,{id:"step-2-link-repository-to-project-project-level",children:"Step 2: Link Repository to Project (Project-level)"}

1),"\n",(0,s.jsx)(n.p,{children:"This step shows how to connect a specific GitLab repository/branch to your Katalon True Platform project and sync test data."}),"\n",(0,s.jsx)(n.admonition,{title:"requirements:",type:"caution",children:(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["Only ",(0,s.jsx)(n.strong,{children:"Project Admins"})," can perform this step. Even ",(0,s.jsx)(n.strong,{children:"Account Admins"})," and ",(0,s.jsx)(n.strong,{children:"System Admins"})," need the Project Admin role in the specific project to configure this"]}),"\n",(0,s.jsx)(n.li,{children:"A GitLab account must already be connected at the Account-level (Step 1)"}),"\n"]})}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:["Navigate to your ",(0,s.jsx)(n.strong,{children:"specific project's UI > Settings > Integrations"}),"."]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:["On your linked GitLab connection, click the right edge and select ",(0,s.jsx)(n.strong,{children:"New configuration (Settings icon)"}),"."]}),"\n"]}),"\n"]}),"\n",(0,s.jsx)("img",{src:"https://tw-cdn.katalon.com/katalon-platform/integration/repository/gitlab-list-project-config.png",alt:"GitLab Setting icon",width:"800"}),"\n",(0,s.jsxs)(n.ol,{start:"3",children:["\n",(0,s.jsx)(n.li,{children:"Fill in the required fields:"}),"\n"]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Display Name"}),": A custom name for the linked project (max 50 characters)."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"URL"}),": The URL to the desired repository, branch, or directory from ",(0,s.jsx)(n.strong,{children:"the linked GitLab account"}),". Copy and paste the URL into this field.","\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["For example: If you linked a connection under ",(0,s.jsx)(n.code,{children:"https://gitlab.com/your-group-name"}),", then the URL should look like:",(0,s.jsx)(n.br,{}),"\n",(0,s.jsx)(n.code,{children:"https://gitlab.com/katalon-test/katalon-project/tree/test/Test%20Casesn"})]}),"\n"]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Link existing test execution results with test cases having the exact same paths and names (Optional)"}),": Enable this if you want Katalon True Platform to automatically attach existing test results to test cases and test suites whose paths and names match your GitLab structure."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Description (Optional)"}),": A brief description of this linked project (max 255 characters)."]}),"\n"]}),"\n",(0,s.jsx)("img",{src:"https://tw-cdn.katalon.com/katalon-platform/integration/repository/gitlab-fields-project.png",alt:"Gitlab fields",width:"700"}),"\n",(0,s.jsxs)(n.ol,{start:"4",children:["\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:["Click ",(0,s.jsx)(n.strong,{children:"Proceed"})," to sync data and finalize the connection. Katalon True Platform automatically syncs your project with the GitLab repository."]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"A GitLab webhook is created automatically, enabling real-time updates such as test results and GitLab action triggers."}),"\n",(0,s.jsxs)(n.li,{children:["If webhook creation succeeds \u2192 The integration status updates to ",(0,s.jsx)(n.strong,{children:"Active"}),"."]}),"\n",(0,s.jsxs)(n.li,{children:['If webhook creation fails \u2192 The status shows Inactive, with an error message: "Failed to create GitLab webhook. Please try again." You can retry by clicking ',(0,s.jsx)(n.strong,{children:"Proceed"})," again once the issue is resolved."]}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.strong,{children:"Additional behavior:"})}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["If the status initially shows as ",(0,s.jsx)(n.strong,{children:"Inactive"}),", reload the page to update the status to ",(0,s.jsx)(n.strong,{children:"Active"}),"."]}),"\n",(0,s.jsxs)(n.li,{children:["If you modify the connection details and click ",(0,s.jsx)(n.strong,{children:"Save"}),", the changes are saved, but the status may remain ",(0,s.jsx)(n.strong,{children:"Inactive"}),".\nTo sync data and finalize the connection, you must click ",(0,s.jsx)(n.strong,{children:"Proceed"}),"."]}),"\n"]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:["[Optional] To edit an existing linked GitLab integration, click the ",(0,s.jsx)(n.strong,{children:"Edit (pen)"})," icon, make the necessary changes, and click ",(0,s.jsx)(n.strong,{children:"Proceed"}),". After editing, reload the page to ensure data is refreshed."]}),"\n"]}),"\n"]}),"\n",(0,s.jsx)(n.hr,{}),"\n",(0,s.jsx)(n.h2,{id:"step-3-enable-updates-to-gitlab",children:"Step 3: Enable Updates to GitLab"}),"\n",(0,s.jsx)(n.p,{children:"This step is only required if you edit test cases in Katalon True Platform and want those changes to sync to GitLab."}),"\n",(0,s.jsx)(n.admonition,{title:"Before enabling sync from Katalon True Platform to GitLab, ensure that:",type:"caution",children:(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["GitLab is connected at the ",(0,s.jsx)(n.strong,{children:"account level (Step 1)"})]}),"\n",(0,s.jsxs)(n.li,{children:["A repository is linked at the ",(0,s.jsx)(n.strong,{children:"project level (Step 2)"})]}),"\n",(0,s.jsxs)(n.li,{children:["You have ",(0,s.jsx)(n.strong,{children:"write permissions"})," for the repository in GitLab"]}),"\n"]})}),"\n",(0,s.jsx)(n.p,{children:"By default, changes you make in Katalon True Platform (such as priority, assignee, or structure) remain local. To push these changes back to GitLab, you need to provide your own Personal Access Token (PAT). Katalon True Platform uses this token to 

1sync changes on your behalf."}),"\n",(0,s.jsx)(n.p,{children:"Each user must complete this setup individually."}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:["Go to ",(0,s.jsx)(n.strong,{children:"User Settings > Personal Integration"}),"."]}),"\n",(0,s.jsx)(n.li,{children:"Click the settings icon next to the integration you want to configure."}),"\n",(0,s.jsxs)(n.li,{children:["Enter your ",(0,s.jsx)(n.strong,{children:"User Email"})," and ",(0,s.jsx)(n.strong,{children:"GitLab Personal Access Token (PAT)"}),"."]}),"\n",(0,s.jsxs)(n.li,{children:["Click ",(0,s.jsx)(n.strong,{children:"Save"}),"."]}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"Once saved, any edits you make to artifacts in linked repositories within Katalon True Platform will automatically sync back to GitLab."}),"\n",(0,s.jsx)(n.hr,{}),"\n",(0,s.jsx)(n.h2,{id:"view-test-cases-or-test-suites-synced-from-gitlab",children:"View Test Cases or Test Suites Synced from GitLab"}),"\n",(0,s.jsxs)(n.p,{children:["To view test cases or test suites synced from the linked GitLab integration, navigate to ",(0,s.jsx)(n.strong,{children:"Tests > Test Cases/Test Suites"}),"."]}),"\n",(0,s.jsx)("img",{src:"https://tw-cdn.katalon.com/katalon-platform/integration/repository/gitlab-linked-test.png",alt:"GitLab linked in Tests folder",width:"1000"}),"\n",(0,s.jsx)(n.hr,{}),"\n",(0,s.jsx)(n.h2,{id:"managing-your-gitlab-integration",children:"Managing Your GitLab Integration"}),"\n",(0,s.jsx)(n.p,{children:"Katalon True Platform provides multiple ways to manage GitLab integrations without losing historical data. This section covers how to disconnect, archive, and restore an integration when needed."}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["Use ",(0,s.jsx)(n.strong,{children:"Disconnect"})," to disable Gitlab integration ",(0,s.jsx)(n.strong,{children:"across all projects"})," (Account-level)."]}),"\n",(0,s.jsxs)(n.li,{children:["Use ",(0,s.jsx)(n.strong,{children:"Archive"})," to disable Gitlab connection for ",(0,s.jsx)(n.strong,{children:"a single project"})," (Project-level)."]}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"Katalon does not support permanently deleting integrations. This ensures audit history is preserved and enhances security and traceability."}),"\n",(0,s.jsx)(n.h3,{id:"disconnect-a-gitlab-connection",children:"Disconnect a GitLab Connection"}),"\n",(0,s.jsxs)(n.blockquote,{children:["\n",(0,s.jsxs)(n.p,{children:["Required role: ",(0,s.jsx)(n.strong,{children:"Account Admin"})," or ",(0,s.jsx)(n.strong,{children:"System Admin"}),"."]}),"\n"]}),"\n",(0,s.jsxs)(n.p,{children:["Disconnecting makes the integration inactive across ",(0,s.jsx)(n.strong,{children:"all projects"}),". Katalon True Platform does not support fully deleting integrations, in order to preserve audit history."]}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:["Go to ",(0,s.jsx)(n.strong,{children:"Account Settings > Integrations"}),"."]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:["Click the ",(0,s.jsx)(n.strong,{children:"Disconnect"})," icon next to the connection."]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:["Confirm by clicking ",(0,s.jsx)(n.strong,{children:"Disconnect"})," in the dialog."]}),"\n",(0,s.jsxs)(n.p,{children:["=> The status changes to ",(0,s.jsx)(n.strong,{children:"Inactive"}),". All projects using this integration lose the ability to sync with GitLab."]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:["To reconnect, click the ",(0,s.jsx)(n.strong,{children:"Reconnect"})," icon next to the integration and confirm. All projects will resume syncing once reconnected."]}),"\n"]}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:"archive-a-linked-repo",children:"Archive a Linked Repo"}),"\n",(0,s.jsxs)(n.blockquote,{children:["\n",(0,s.jsxs)(n.p,{children:["Required role: ",(0,s.jsx)(n.strong,{children:"Account Admin"})," or ",(0,s.jsx)(n.strong,{children:"System Admin"}),"."]}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"Archiving disables the connection for that project only \u2014 other projects using the same GitLab integration are unaffected. Archived configurations no longer appear in Project Settings, and any scheduled test runs will be canceled at runtime."}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:["Go to ",(0,s.jsx)(n.strong,{children:"Project Settings > Integrations"}),"."]}),"\n",(0,s.jsxs)(n.li,{children:["Click the right edge of your linked connection and select ",(0,s.jsx)(n.strong,{children:"Archive"}),"."]}

1),"\n",(0,s.jsxs)(n.li,{children:["Confirm by clicking ",(0,s.jsx)(n.strong,{children:"Archive"})," in the dialog."]}),"\n"]}),"\n",(0,s.jsxs)(n.p,{children:["Result: The integration no longer appears in the ",(0,s.jsx)(n.strong,{children:"Test Cases/Test Suites module"}),". Any scheduled test runs in the ",(0,s.jsx)(n.strong,{children:"Execution module"})," will be automatically canceled at runtime."]}),"\n",(0,s.jsx)(n.h3,{id:"restore-an-archived-integration",children:"Restore an Archived Integration"}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:["Go to ",(0,s.jsx)(n.strong,{children:"Project Settings > Integrations"}),"."]}),"\n",(0,s.jsxs)(n.li,{children:["Click ",(0,s.jsx)(n.strong,{children:"New configuration"})," (settings icon) on the GitLab connection."]}),"\n",(0,s.jsxs)(n.li,{children:["Enter the same repository URL as the archived configuration and click ",(0,s.jsx)(n.strong,{children:"Proceed"}),"."]}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"Katalon True Platform will restore the archived configuration rather than creating a duplicate."})]})}function h(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(d,{...e})}):d(e)}},28453:(e,n,t)=>{t.d(n,{R:()=>o,x:()=>l});var i=t(96540);const s={},r=i.createContext(s);function o(e){const n=i.useContext(r);return i.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function l(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:o(e.components),i.createElement(r.Provider,{value:n},e.children)}}}]);