GitLab Discovery

원문 보기 위키 갱신 2026.10.07

GitLab 통합에는 GitLab에서 카탈로그 엔티티를 발견하기 위한 특별한 엔티티 제공자가 있어요. 엔티티 제공자는 GitLab 인스턴스를 크롤링해서 구성된 경로에 일치하는 엔티티를 등록해요. 이는 정적 위치를 쓰거나 카탈로그에 항목을 수동으로 추가하는 것의 대안으로 유용할 수 있어요.

출처: 문서

본문

이 제공자는 GitLab Webhook을 기반으로 GitLab 데이터를 수집하도록 구성할 수도 있어요. 현재 허용되는 이벤트는:

push.

설치

이 제공자는 기본 제공자 중 하나가 아니므로 먼저 gitlab 카탈로그 플러그인을 설치해야 해요.

Backstage 루트 디렉터리에서

yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-gitlab

그런 다음 백엔드 초기화에 다음을 추가하세요.

packages/backend/src/index.ts

// optional if you want HTTP endpoints to receive external events// backend.add(import('@backstage/plugin-events-backend'));// optional if you want to use AWS SQS instead of HTTP endpoints to receive external events// backend.add(import('@backstage/plugin-events-backend-module-aws-sqs'));// optional - event router for gitlab. See.: https://github.com/backstage/backstage/blob/master/plugins/events-backend-module-gitlab/README.md// backend.add(eventsModuleGitlabEventRouter);// optional - token validator for the gitlab topic// backend.add(eventsModuleGitlabWebhook);backend.add(import('@backstage/plugin-catalog-backend-module-gitlab'));

이벤트 지원

GitLab용 카탈로그 모듈에는 이벤트 지원이 활성화되어 있어요. 이 모듈은 관련 토픽(gitlab.push)을 구독하며, 이 이벤트들이 EventsService를 통해 게시될 것으로 기대해요.

사전 준비

내장 이벤트 지원을 사용하기 위한 사전 준비가 두 가지 있어요.

GitLab에서 그룹 수준 또는 프로젝트 수준 웹훅 만들기
@backstage/plugin-events-backend-module-gitlab 설치 및 구성

GitLab에서 웹훅 구성하기

그룹 수준 웹훅을 구성하거나 프로젝트 수준 웹훅을 구성할 수 있어요. 구성 방법은 공식 문서를 참고하세요.

웹훅(들)은 push 이벤트에 반응하도록 구성해야 해요.

GitLab에서 웹훅을 만들 때 "URL"은 대략 https://<your-instance-name>/api/events/http/gitlab처럼 보여요.

GitLab 이벤트 모듈 설치 및 구성

내장 이벤트 지원을 사용하려면 @backstage/plugin-events-backend-module-gitlab을 설치하고 구성해야 해요. 이 모듈은 일반 토픽 gitlab에서 받은 이벤트를 이벤트 유형에 따라 더 구체적인 토픽(예: gitlab.push)으로 라우팅해요. 내장 이벤트 지원이 기대하는 것이 바로 이런 더 구체적인 이벤트예요.

GitLab 이벤트 패키지 추가:

Backstage 루트 디렉터리에서

yarn --cwd packages/backend add @backstage/plugin-events-backend-module-gitlab

GitLab 이벤트 모듈을 Backstage 백엔드에 추가:

packages/backend/src/index.ts

backend.add(import('@backstage/plugin-events-backend'));backend.add(import('@backstage/plugin-events-backend-module-gitlab'));

GitLab 이벤트 모듈 구성:

app-config.yaml

events:  modules:    gitlab:      webhookSecret: ${GITLAB_WEBHOOK_SECRET}

이 마지막 단계는 기술적으로 선택 사항이지만, 받는 이벤트가 외부 악의적인 행위자가 아니라 GitLab에서 온 것인지 확실히 하기 위해 포함하는 게 좋아요.

이 예시에서 ${GITLAB_WEBHOOK_SECRET}의 값은 GitLab에서 웹훅을 만들 때 사용한 것과 같은 값이어야 해요.

HTTP 엔드포인트를 사용한 이벤트 설정

HTTP 엔드포인트를 사용한 이벤트는 Events 백엔드의 내장 기능이므로, app-config.yaml에 추가 구성만 하면 돼요. 다음과 같이 생겼어요.

app-config.yaml

events:  http:    topics:      - gitlab

그러면 이런 엔드포인트가 노출돼요: http://localhost/api/events/http/gitlab

AWS SQS 모듈을 사용한 이벤트 설정

HTTP 엔드포인트 대신 AWS SQS 모듈을 사용할 수도 있어요. 이렇게 하면 돼요.

AWS SQS 이벤트 패키지 추가:

Backstage 루트 디렉터리에서

yarn --cwd packages/backend add @backstage/plugins-events-backend-module-aws-sqs

AWS SQS 이벤트 모듈을 Backstage 백엔드에 추가:

packages/backend/src/index.ts

backend.add(import('@backstage/plugin-events-backend'));backend.add(import('@backstage/plugin-events-backend-module-gitlab'));backend.add(import('@backstage/plugins-events-backend-module-aws-sqs'));

AWS SQS 이벤트 모듈 구성:

app-config.yaml

events:  modules:    awsSqs:      awsSqsConsumingEventPublisher:        topics:          gitlab:            queue:              url: 'https://sqs.us-east-2.amazonaws.com/123456789012/MyQueue'              region: us-east-2

AWS SQS 모듈 README에 구성 옵션에 대한 자세한 내용이 있으며, 위 예시에는 필수 옵션만 포함되어 있어요.

Google Pub/Sub 모듈을 사용한 이벤트 설정

HTTP 엔드포인트 대신 Google Pub/Sub 모듈을 사용할 수도 있어요. 이렇게 하면 돼요.

Google Pub/Sub 이벤트 패키지 추가:

Backstage 루트 디렉터리에서

yarn --cwd packages/backend add @backstage/plugin-events-backend-module-google-pubsub

Google Pub/Sub 이벤트 모듈을 Backstage 백엔드에 추가:

packages/backend/src/index.ts

backend.add(import('@backstage/plugin-events-backend'));backend.add(import('@backstage/plugin-events-backend-module-gitlab'));backend.add(import('@backstage/plugin-events-backend-module-google-pubsub'));

Google Pub/Sub 이벤트 모듈 구성:

app-config.yaml

events:  modules:    googlePubSub:      googlePubSubConsumingEventPublisher:        subscriptions:          # A unique key for your subscription, to be used in logging and metrics          mySubscription:            # The fully qualified name of the subscription            subscriptionName: 'projects/my-google-project/subscriptions/gitlab-events'            # The event system topic to transfer to. This can also be just a plain string            targetTopic: 'gitlab.{{ event.attributes.x-gitlab-event }}'

Google Pub/Sub 모듈 README에 구성 옵션에 대한 자세한 내용이 있으며, 위 예시에는 필수 옵션만 포함되어 있어요.

Kafka 모듈을 사용한 이벤트 설정

HTTP 엔드포인트 대신 Kafka 모듈을 사용할 수도 있어요. 이렇게 하면 돼요.

Kafka 이벤트 패키지 추가:

Backstage 루트 디렉터리에서

yarn --cwd packages/backend add @backstage/plugin-events-backend-module-kafka

Kafka 이벤트 모듈을 Backstage 백엔드에 추가:

packages/backend/src/index.ts

backend.add(import('@backstage/plugin-events-backend'));backend.add(import('@backstage/plugin-events-backend-module-gitlab'));backend.add(import('@backstage/plugin-events-backend-module-kafka'));

Kafka 이벤트 모듈 구성:

app-config.yaml

events:  modules:    kafka:      kafkaConsumingEventPublisher:        # Client ID used by Backstage to identify when connecting to the Kafka cluster.        clientId: your-client-id        # List of brokers in the Kafka cluster to connect to.        brokers:          - broker1          - broker2        topics:          # Replace with actual topic name as expected by subscribers          - topic: 'backstage.topic'            kafka:              # The Kafka topics to subscribe to.              topics:                - topic1              # The GroupId to be used by the topic consumers.              groupId: your-group-id

Kafka 모듈 README에 구성 옵션에 대한 자세한 내용이 있으며, 위 예시에는 필수 옵션만 포함되어 있어요.

구성

discovery 제공자를 사용하려면 token으로 GitLab 통합이 설정되어 있어야 해요. 그런 다음 카탈로그 구성에 그룹별 제공자 구성을 추가할 수 있어요.

note

아래와 같이 schedule이 구성에 설정되어 있어야 합니다.

app-config.yaml

catalog:  providers:    gitlab:      yourProviderId:        host: gitlab-host # Identifies one of the hosts set up in the integrations        branch: main # Optional. Used to discover on a specific branch        fallbackBranch: master # Optional. Fallback to be used if there is no default branch configured at the Gitlab repository. It is only used, if `branch` is undefined. Uses `master` as default        skipForkedRepos: false # Optional. If the project is a fork, skip repository        includeArchivedRepos: false # Optional. If project is archived, include repository        group: example-group # Optional (unless useSearch is true). Group and subgroup (if needed) to look for repositories. If not present the whole instance will be scanned        groupPattern: # Optional. Filters for groups based on a list of RegEx. Default, no filters.          - '^somegroup$'          - 'anothergroup'        entityFilename: catalog-info.yaml # Optional. Defaults to `catalog-info.yaml`        useSearch: false # Optional. Whether to use the GitLab group search API to find files. Requires Gitlab 'Premium' or 'Ultimate' licenses.  Defaults to `false`        projectPattern: '[\\s\\S]*' # Optional. Filters found projects based on provided pattern. Defaults to `[\\s\\S]*`, which means to not filter anything        excludeRepos: [] # Optional. A list of project paths that should be excluded from discovery, e.g. group/subgroup/repo. Should not start or end with a slash.        schedule: # Same options as in SchedulerServiceTaskScheduleDefinition. Optional for the Legacy Backend System          # supports cron, ISO duration, "human duration" as used in code          frequency: { minutes: 30 }          # supports ISO duration, "human duration" as used in code          timeout: { minutes: 3 }

대체 프로세서

엔티티 제공자 GitlabDiscoveryEntityProvider의 대안으로 GitLabDiscoveryProcessor를 여전히 사용할 수 있어요.

gitlab-discovery 타입을 주목하세요. 이것은 일반 url 프로세서가 아니에요.

대상은 세 부분으로 이루어져 있어요.

기본 URL(이 경우 https://gitlab.com)
그룹 경로(이 경우 group/subgroup). 선택 사항이에요. 이 경로를 생략하면 프로세서가 전체 GitLab 인스턴스를 스캔해요.
각 저장소 안에서 카탈로그 YAML 파일을 찾을 경로. 보통 /blob/main/catalog-info.yaml, /blob/master/catalog-info.yaml 또는 각 저장소의 루트 디렉터리에 저장된 카탈로그 파일에 대한 비슷한 변형이에요. 저장소의 기본 브랜치를 사용하려면 * 와일드카드를 사용하세요, 예: /blob/*/catalog-info.yaml

마지막으로 백엔드의 카탈로그 초기화 코드에 프로세서를 추가해야 해요.

packages/backend/src/plugins/catalog.ts

import { GitLabDiscoveryProcessor } from '@backstage/plugin-catalog-backend-module-gitlab';export default async function createPlugin(  env: PluginEnvironment,): Promise<Router> {  const builder = await CatalogBuilder.create(env);  builder.addProcessor(    GitLabDiscoveryProcessor.fromConfig(env.config, { logger: env.logger }),  );  // ..}

그리고 다음을 app-config.yaml에 추가하세요.

catalog:  locations:    - type: gitlab-discovery      target: https://gitlab.com/group/subgroup/blob/main/catalog-info.yaml

컴포넌트 정의가 있는 파일이 프로젝트에 존재하지 않을 때 location 객체를 만들고 싶지 않다면 skipReposWithoutExactFileMatch 옵션을 설정할 수 있어요. 그러면 404 상태 코드로 gitlab에 보내는 요청 수를 줄일 수 있어요.

프로젝트가 포크일 때 location 객체를 만들고 싶지 않다면 skipForkedRepos 옵션을 설정할 수 있어요.

프로젝트가 보관(archived)되었을 때 location 객체를 만들고 싶다면 includeArchivedRepos 옵션을 설정할 수 있어요.

GitLab Discovery

본문

설치

이벤트 지원

사전 준비

GitLab에서 웹훅 구성하기

GitLab 이벤트 모듈 설치 및 구성

HTTP 엔드포인트를 사용한 이벤트 설정

AWS SQS 모듈을 사용한 이벤트 설정

Google Pub/Sub 모듈을 사용한 이벤트 설정

Kafka 모듈을 사용한 이벤트 설정

구성

대체 프로세서

더 알아보기 (Learn more)