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

GitHub Apps

원문 보기 위키 갱신

Backstage는 백엔드 인증에 GitHub Apps를 사용하도록 구성할 수 있어요. 이는 더 높은 요청 빈도 제한과, Backstage가 사용자나 봇 계정 대신 애플리케이션으로 동작할 수 있다는 것 같은 이점을 제공해요.

출처: 문서

본문

Backstage는 백엔드 인증에 GitHub Apps를 사용하도록 구성할 수 있어요. 이는 더 높은 요청 빈도 제한, 그리고 Backstage가 사용자나 봇 계정 대신 애플리케이션으로 동작할 수 있다는 것 같은 이점을 제공해요.

또한 OAuth 앱과 각각의 스코프에 비해 훨씬 더 명확하고 나은 인증 모델을 제공해요.

주의사항

  • 이 인증 방법은 개인 저장소가 아니라 조직 저장소에 대해 인증하도록 설계됐어요.

  • Backstage가 처리하도록 같은 GitHub 조직에 여러 Backstage GitHub App을 설치하는 것은 불가능해요. 현재는 특정 저장소에 어떤 앱이 설치되어 있는지 확인하기 위해 등록된 모든 GitHub App을 살펴보지 않아요. 지금은 전역 조직 설치만 존중해요.

  • 앱 권한은 Backstage가 관리하지 않아요. 몇 가지 간단한 기본 권한과 함께 생성되며, 필요에 따라 자유롭게 변경할 수 있지만 지금은 Backstage가 아니라 GitHub 웹 콘솔에서 업데이트해야 해요. 기본값으로 설정되는 권한은 metadata:read와 contents:read예요.

  • 생성된 GitHub App은 기본적으로 비공개예요. github.com에서는 이것이 아마 원하는 것일 테지만, GitHub Enterprise에서는 GHE 조직 전체에 걸쳐 애플리케이션을 공유하기 위해 애플리케이션을 공개로 만드는 것을 권장해요.

CLI로 생성한 GitHub App은 기본적으로 읽기 접근 권한을 가져요. 필요하다면 GitHub에서 GitHub App 설정을 수동으로 업데이트해 앱에 더 많은 권한을 부여해야 해요.

CLI 사용하기(공개 GitHub만)

backstage-cli를 사용해 우리가 제공하는 매니페스트 파일로 GitHub App을 만들 수 있어요. 이렇게 하면 GitHub 앱을 만드는 데 필요한 작업 중 일부를 자동화할 수 있어요.

yarn backstage-cli create-github-app <github org>

backstage-cli create-github-app 명령어에 대해 더 자세히 읽을 수 있어요.

CLI 명령어를 끝내면 프로젝트 루트에 YAML 파일이 생성되는데, 이를 app-config.yaml의 include로 사용할 수 있어요. 이미 앱이 있다면 건너뛰어도 돼요.

생성된 앱의 웹훅은 기본적으로 비활성화되어 있고 smee.io를 가리키며, 로컬 개발용으로 의도됐다는 점 참고하세요. 또한 현재 Backstage에서 웹훅을 사용하는 부분은 없어요.

GitHub Enterprise

GitHub Enterprise는 매니페스트에서 앱 생성을 지원하지 않으므로, 다음 지침을 사용해 GitHub 애플리케이션을 수동으로 만들어야 해요.

애플리케이션이 생성되면 애플리케이션의 개인 키를 생성해 YAML 파일에 넣어야 해요.

YAML 파일은 다음 정보를 포함해야 해요. privateKey의 들여쓰기가 필요하다는 점 참고하세요.

appId: app idclientId: client idclientSecret: client secretwebhookSecret: webhook secretprivateKey: |  [REDACTED PRIVATE KEY]

통합 구성에 포함하기

create-github-app이 생성한 YAML 파일이나 GitHub Enterprise 지침을 따라 수동으로 자격 증명을 저장했다면, app-config.yaml의 integrations 섹션 아래에 포함할 수 있어요.

자격 증명 파일은 매우 민감하므로 어떤 종류의 버전 관리에도 커밋해서는 안 된다는 점 유의하세요. 대신 선호하는 보안 비밀 배포 방법을 사용하세요.

integrations:  github:    - host: github.com      apps:        - $include: example-backstage-app-credentials.yaml

또는 환경 변수를 사용할 수도 있어요.

integrations:  github:    - host: github.com      apps:        - appId: ${AUTH_ORG_APP_ID}          clientId: ${AUTH_ORG_CLIENT_ID}          clientSecret: ${AUTH_ORG_CLIENT_SECRET}          privateKey: ${AUTH_ORG1_PRIVATE_KEY}          webhookSecret: ${AUTH_ORG_WEBHOOK_SECRET}

note

두 예시 모두에서 apps는 배열이므로, 각각이 Caveats 섹션에서 언급한 대로 서로 다른 GitHub Org용이라면 $include나 환경 변수로 여러 GitHub App을 추가할 수 있습니다.

GitHub App 설치 제한하기

Backstage에 보이는 GitHub App 설치를 제한하고 싶다면 선택적으로 allowedInstallationOwners 옵션을 포함할 수 있어요. 여러 앱을 구성하면, Backstage가 URL에 사용할 앱을 더 쉽게 선택할 수 있어 약간의 성능 이점도 생겨요.

appId: app idallowedInstallationOwners: ['GlobexCorp']clientId: client idclientSecret: client secretwebhookSecret: webhook secretprivateKey: |  [REDACTED PRIVATE KEY]

이렇게 하면 허용 목록에 없는 설치의 사용을 Backstage가 차단해요.

앱 권한

GitHub App을 만들 때는 앱의 접근 수준을 정의하는 권한을 선택해야 해요. 필요한 권한은 통합을 어떻게 사용하느냐에 따라 달라져요.

소프트웨어 컴포넌트 읽기:

  • Contents: Read-only

  • Commit statuses: Read-only

조직 데이터 읽기:

  • Members: Read-only

소프트웨어 템플릿 게시:

  • Administration: Read & write(저장소 생성용)

  • Contents: Read & write

  • Metadata: Read-only

  • Pull requests: Read & write

  • Issues: Read & write

  • Workflows: Read & write(템플릿에 GitHub 워크플로가 포함된 경우)

  • Variables: Read & write(템플릿에 GitHub Action Repository Variables가 포함된 경우)

  • Secrets: Read & write(템플릿에 GitHub Action Repository Secrets가 포함된 경우)

  • Environments: Read & write(템플릿에 GitHub Environments가 포함된 경우)

권한 업데이트

GitHub App의 권한을 업데이트해야 할 때가 있을 수 있어요. GitHub App을 쉽게 찾으려면 다음 URL에서 찾을 수 있어요.

https://github.com/organizations/{ORG}/settings/apps/{APP_NAME}/permissions

권한을 변경하면 앱 소유자가 이메일을 받고, 변경 사항이 적용되기 전에 승인해야 한다는 점 유의하세요.

문제 해결

HttpError: This endpoint requires you to be authenticated.

이 메시지는 보통 내부적으로 NotFoundError: No app installation found를 감싸는데, 이는 조직에 앱을 설치하지 않았기 때문이에요. backstage-cli를 통해 조직의 멤버이자 앱 관리자로 만들었더라도 앱이 자동으로 설치되지는 않아요. 앱 설정 아래에서 Install 메뉴를 보려면 조직에서 Owner 역할을 보유해야 하며, 그런 다음 애플리케이션을 승인하려면 수동으로 Install을 눌러야 해요.

더 알아보기 (Learn more)