본문 바로가기
WIKI 기술 지식 베이스

GitHub Discovery

원문 보기 위키 갱신

GitHub 통합에는 GitHub 조직 또는 App 안에서 카탈로그 엔티티를 발견하기 위한 discovery 제공자가 있어요.

출처: 문서

본문

GitHub Provider

GitHub 통합에는 GitHub 조직 또는 App 안에서 카탈로그 엔티티를 발견하기 위한 discovery 제공자가 있어요. 제공자는 GitHub 조직 또는 App을 크롤링해서 구성된 경로에 일치하는 엔티티를 등록해요. 이는 정적 위치를 쓰거나 카탈로그에 항목을 수동으로 추가하는 것의 대안으로 유용할 수 있어요. 카탈로그에 엔티티를 수집하는 데 선호되는 방법입니다.

설치

GitHub 엔티티 제공자는 기본으로 설치되지 않으므로 백엔드에 추가해야 해요. 따라서 @backstage/plugin-catalog-backend-module-github에 대한 종속성을 백엔드 패키지에 추가해야 해요.

Backstage 루트 디렉터리에서

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

그런 다음 다음 줄을 추가해 백엔드를 업데이트하세요.

packages/backend/src/index.ts

backend.add(import('@backstage/plugin-catalog-backend'));backend.add(import('@backstage/plugin-catalog-backend-module-github'));

이벤트 지원

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

사전 준비

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

  • GitHub에서 웹훅 만들기

  • @backstage/plugin-events-backend-module-github 설치 및 구성

GitHub에서 웹훅 구성하기

공식 문서를 확인해 웹훅을 구성하고 요청을 보호할 수 있어요.

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

note

repository.transferred 이벤트를 받으려면 새 소유자 계정에 GitHub App이 설치되어 있어야 하고, App이 repository 이벤트를 구독해야 합니다. 이 이벤트는 소유권이 이전되는 계정에만 전송됩니다.

GitHub에서 웹훅을 만들 때 "Payload URL"은 대략 https://<your-instance-name>/api/events/http/github처럼 보이고, "Content Type"은 application/json이어야 해요.

GitHub Webhooks UI는 새 웹훅을 저장할 때 연결을 검증하기 위해 테스트 이벤트를 보내요. 실패하면 이 테스트 이벤트를 다시 보낼 수 있어요. 또한 나중에 문제를 해결해야 할 때 이벤트가 발생하고 있는지 검증하는 데 쓸 수 있는 Recent Deliveries 탭이 있어요.

GitHub 이벤트 모듈 설치 및 구성

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

먼저 패키지를 추가해야 해요.

Backstage 루트 디렉터리에서

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

그런 다음 백엔드에 추가해야 해요.

packages/backend/src/index.ts

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

마지막으로 구성해야 해요.

events:  modules:    github:      webhookSecret: ${GITHUB_WEBHOOK_SECRET}

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

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

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

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

events:  http:    topics:      - github

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

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

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

먼저 패키지를 추가해야 해요.

Backstage 루트 디렉터리에서

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

그런 다음 백엔드에 추가해야 해요.

packages/backend/src/index.ts

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

마지막으로 구성해야 해요.

events:  modules:    awsSqs:      awsSqsConsumingEventPublisher:        topics:          github:            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 모듈을 사용할 수도 있어요. 이렇게 하면 돼요.

먼저 패키지를 추가해야 해요.

Backstage 루트 디렉터리에서

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

그런 다음 백엔드에 추가해야 해요.

packages/backend/src/index.ts

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

마지막으로 구성해야 해요.

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/github-enterprise-events'            # The event system topic to transfer to. This can also be just a plain string            targetTopic: 'github.{{ event.attributes.x-github-event }}'

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

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

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

먼저 패키지를 추가해야 해요.

Backstage 루트 디렉터리에서

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

그런 다음 백엔드에 추가해야 해요.

packages/backend/src/index.ts

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

마지막으로 구성해야 해요.

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 제공자를 사용하려면 개인용 액세스 토큰 또는 GitHub Apps 중 하나로 GitHub 통합이 설정되어 있어야 해요. 개인용 액세스 토큰은 필수 스코프에 주의해야 하며, 컴포넌트를 읽으려면 최소한 repo 스코프가 필요해요. GitHub Apps는 컴포넌트를 읽으려면 최소한 Contents: Read-only 권한을 부여해야 해요.

그런 다음 카탈로그 제공자 구성에 github 구성을 추가할 수 있어요.

catalog:  providers:    github:      # the provider ID can be any camelCase string      providerId:        organization: 'backstage' # string        catalogPath: '/catalog-info.yaml' # string        filters:          branch: 'main' # string          repository: '.*' # Regex        schedule: # same options as in SchedulerServiceTaskScheduleDefinition          # 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 }      customProviderId:        organization: 'new-org' # string        catalogPath: '/custom/path/catalog-info.yaml' # string        filters: # optional filters          branch: 'develop' # optional string          repository: '.*' # optional Regex        pageSizes:          repositories: 25      wildcardProviderId:        organization: 'new-org' # string        catalogPath: '/groups/**/*.yaml' # this will search all folders for files that end in .yaml        filters: # optional filters          branch: 'develop' # optional string          repository: '.*' # optional Regex      topicProviderId:        organization: 'backstage' # string        catalogPath: '/catalog-info.yaml' # string        filters:          branch: 'main' # string          repository: '.*' # Regex          topic: 'backstage-exclude' # optional string      topicFilterProviderId:        organization: 'backstage' # string        catalogPath: '/catalog-info.yaml' # string        filters:          branch: 'main' # string          repository: '.*' # Regex          topic:            include: ['backstage-include'] # optional array of strings            exclude: ['experiments'] # optional array of strings      validateLocationsExist:        organization: 'backstage' # string        catalogPath: '/catalog-info.yaml' # string        filters:          branch: 'main' # string          repository: '.*' # Regex        validateLocationsExist: true # optional boole...

이 제공자는 고유한 제공자 ID를 통해 여러 조직과 앱을 지원해요.

note

제공자 ID 수준을 건너뛰는 것도 가능하지만 권장되지는 않습니다. 그렇게 하면 default가 제공자 ID로 사용됩니다.

  • catalogPath (선택): 기본값: /catalog-info.yaml. catalog-info.yaml 파일을 찾을 경로. 경로와/또는 파일 이름을 검색하려면 와일드카드 - *, ** 또는 minimatch가 지원하는 glob 패턴 - 를 사용할 수 있어요. validateLocationsExist 옵션이 true로 설정되어 있으면 와일드카드를 사용할 수 없어요.

  • filters (선택):

  • branch (선택): 브랜치 이름을 기준으로 결과를 필터링하는 데 사용하는 문자열. 브랜치 이름에는 슬래시(/) 문자가 포함될 수 없어요. 기본값은 저장소의 기본 브랜치예요.

  • repository (선택): 저장소 이름을 기준으로 결과를 필터링하는 데 사용하는 정규식.

  • topic (선택): 아래 두 필터를 동시에 사용할 수 있지만 제외 필터가 우선순위가 가장 높아요. 위 예시에서 backstage-include 토픽이 있는 저장소도 experiments 토픽을 함께 갖고 있다면 여전히 제외돼요.

  • include (선택): 연결된 GitHub 토픽을 기준으로 결과를 포함시키는 데 사용하는 문자열 배열. 구성되면 포함 필터에 있는 토픽(들)을 하나(또는 여러 개) 가진 저장소만 수집돼요.

  • exclude (선택): 연결된 GitHub 토픽을 기준으로 결과를 걸러내는 데 사용하는 문자열 배열. 구성되면 제외 필터에 있는 토픽(들)을 하나(또는 여러 개) 가진 저장소를 제외한 모든 저장소가 수집돼요.

  • visibility (선택): 가시성을 기준으로 결과를 필터링하는 데 사용하는 문자열 배열. 사용 가능한 옵션은 private, internal, public이에요. 구성되면(비어 있지 않으면) 필터에 있는 가시성을 가진 저장소만 수집돼요.

  • allowArchived (선택): 보관된(archived) 저장소를 포함할지 여부. 기본값은 false.

  • host (선택): GitHub Enterprise 인스턴스의 호스트 이름. integrations.github에 정의된 호스트와 일치해야 해요.

  • organization (필수, app이 설정되지 않은 경우): 조직 계정/워크스페이스의 이름. 여러 조직을 추가하려면 제공자 구성을 각각 하나씩 추가하거나 app을 지정해야 해요.

  • app (필수, organization이 설정되지 않은 경우): GitHub App의 ID.

  • validateLocationsExist (선택): 내보내기 전에 존재하는 위치를 검증할지 여부. 이 옵션은 소스 저장소에 존재하지 않는 카탈로그 정보 파일에 대한 위치를 생성하지 않도록 해줘요. 기본값은 false. GitHub API가 저장소 객체를 쿼리하는 데 제한이 있기 때문에, 이 옵션은 catalogPath의 와일드카드와 함께 사용할 수 없어요.

  • schedule:

  • frequency: 작업을 얼마나 자주 실행할지. 시스템은 호출이 겹치지 않도록 최선을 다해요.

  • timeout: 단일 작업 호출이 걸릴 수 있는 최대 시간.

  • initialDelay (선택): 첫 호출 전에 지나야 하는 시간.

  • scope (선택): 'global' 또는 'local'. 동시성 제어 범위를 설정해요.

  • pageSizes (선택): GitHub GraphQL API 쿼리의 페이지 크기를 구성해요. RESOURCE_LIMITS_EXCEEDED 오류를 방지하는 데 도움이 될 수 있어요.

  • repositories (선택): 페이지당 가져올 저장소 수. 기본값은 25. API 리소스 한도에 부딪히면 이 값을 줄이세요.

GitHub API 요청 빈도 제한

GitHub는 API 요청을 시간당 5,000회(엔터프라이즈 계정은 그 이상)로 제한해요. 아래 스니펫은 35분마다 Backstage 카탈로그 데이터를 새로고침하며, 발견된 각 위치에 대해 API 요청을 한 번 발행해요.

요청이 너무 잦으면 요청 빈도 제한으로 조절(throttle)될 수 있어요. app-config.yaml 파일에서 schedule을 제어해 카탈로그의 새로고침 빈도를 변경할 수 있어요.

schedule:  frequency: { minutes: 35 }  timeout: { minutes: 3 }

스케줄링에 대한 더 자세한 내용은 SchedulerServiceTaskScheduleDefinition 페이지에서 확인할 수 있어요.

또는(또는 추가로) GitHub에서 훨씬 더 높은 요청 빈도 제한을 가진 github-apps 인증을 구성할 수 있어요.

이것은 GitHub 엔티티를 카탈로그에 추가하는 어떤 방법에도 해당되지만, 자동 discovery에서는 특히 걸리기 쉬워요.

더 알아보기 (Learn more)