> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ale.run/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub

> GitHub OAuth를 `ale` 에 추가하는 가이드입니다.

> **GitHub OAuth**를 추가하면 GitHub 로그인이 활성화 되고, 대시보드 사용자는 연동한 GitHub 계정의 저장소를 선택해 서비스를 배포할 수 있게 됩니다.

***

## GitHub Apps 생성

<Frame>
  <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/authentication/images/01_01.png" />
</Frame>

> GitHub에 로그인 후, **Settings > Developer Settings > GitHub Apps** 페이지에서 [New GitHub App](https://github.com/settings/apps/new)을 클릭하면, GitHub App 생성 과정이 시작됩니다.

### 기본정보 입력

<Frame>
  <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/authentication/images/01_02.png" />
</Frame>

> GitHub App을 생성하기 위한 정보를 아래와 같이 입력하세요.

* **GitHub App name** : GitHub App 이름
* **Homepage URL**
  * GitHub OAuth를 적용할 홈페이지 URL
  * Ingress로 배포한 URL인 `https://app.[도메인]`
* **Callback URL(`Add Callbak URL`로 항목 추가)**
  * `https://app.[도메인]/api/oauth/github/callback`
  * `https://app.[도메인]/api/oauth/github/connect/callback`

<Info>
  이 화면에서 입력한 **GitHub App name**은 `ale` 에 GitHub OAuth 등록시 사용됩니다.
</Info>

<Tip>
  `https://app.[도메인]/api/` 는 `ale` 의 API엔드포인트 주소입니다.
</Tip>

### Webhook 비활성화

<Frame>
  <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/authentication/images/01_03.png" />
</Frame>

> Webhook 항목의 Active 체크를 해제하여 비활성화하세요.

### 권한 부여 및 APP 생성

<Frame>
  <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/authentication/images/01_04.png" />
</Frame>

> Permission 항목에서 아래의 권한을 부여하고, `Create GitHub App` 버튼으로 APP을 생성하세요.

<AccordionGroup>
  <Accordion title="Repository permissions (9)">
    * **Read and Write**
      * Actions
      * Administration
      * Commit statuses
      * Contents
      * Deployments
      * Issues
      * Pull requests
      * Workflows
    * **Read-only**
      * Metadata
  </Accordion>

  <Accordion title="Organization permissions (2)">
    * **Read and Write**
      * Administration
    * **Read-only**
      * Members
  </Accordion>

  <Accordion title="Account permissions (1)">
    * **Read-only**
      * Email addresses
  </Accordion>
</AccordionGroup>

## GitHub App 정보 조회

> `ale` 에 GitHub OAuth를 추가하기 위해 GitHub App Name 이외에 **4개의 ID, Key 값이 필요합니다.**

* **App ID**
* **Client ID**
* **Cleint Secret**
* **Private Key**

### App ID, Client ID 조회

<Frame>
  <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/authentication/images/01_05.png" />
</Frame>

> 권한 부여 후 App이 생성되면, **App ID 와 Client ID**를 조회할 수 있습니다.

### Client Secret 조회

<Frame>
  <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/authentication/images/01_06.png" />
</Frame>

> 같은 화면에서 `Generate a new client secret`을 클릭해 **Client Secret**을 생성하고 조회하세요.

### Private Key 조회

<Frame>
  <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/authentication/images/01_08.png" />
</Frame>

> 화면 하단부의 `Generate a private key`를 클릭하면 pem 파일이 다운로드 됩니다.

## GitHub App 공개 설정

> 생성된 GitHub App의 공개 설정에 관한 기본값은 **비공개**이며, App을 생성한 계정이 속한 조직의 사용자만 GitHub App을 사용할 수 있게됩니다. GitHub 조직과 상관없이 GitHub App을 사용할 수 있게 하려면 아래를 참고하세요.

<AccordionGroup>
  <Accordion title="GitHub App을 공개상태로 설정하기" defaultOpen={true}>
    <Frame>
      <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/authentication/images/01_16.png" />
    </Frame>

    > 좌측의 **Advanced** 메뉴에서 **Danger Zone** 항목의 `Make public`을 클릭하세요.
  </Accordion>
</AccordionGroup>

## ale 운영 시스템에 등록

<Frame>
  <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/authentication/images/01_10.png" />
</Frame>

> 운영 시스템에 접속해 **설정 > 인증수단 > GitHub** 드롭다운을 클릭한 후, 앞 단계에서 조회한 값들을 각 필드에 입력하고 `적용하기`를 클릭하세요.

* **로그인 사용** : OAuth 로그인 적용 여부
* **APP\_NAME** : GitHub App 이름
* **APP\_ID** : App ID
* **CLIENT\_ID** : Client ID
* **CLIENT\_SECRET** : Client secret
* **APP\_PRIVATE\_KEY**: Private ket pem 파일 값

<Info>
  적용 완료 후 대시보드에 접속하면 다음과 같이 **GitHub 계정으로 로그인** 버튼이 표시됩니다.

  <Frame>
    <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/authentication/images/01_11.png" />
  </Frame>
</Info>

## Github 계정으로 로그인

<Frame>
  <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/authentication/images/01_12.png" />
</Frame>

> 사용자의 첫번째 GitHub login 시, `Authorize [GitHub App 이름]`를 클릭하면 가입 신청이 진행되고, 관리자 승인 관련 메세지가 표시됩니다.

<Info>
  가입 신청한 사용자의 승인(활성화)는 [사용자 관리 페이지](/ko/operations/user-management#%EC%82%AC%EC%9A%A9%EC%9E%90-%ED%99%9C%EC%84%B1%ED%99%94)를 참고하세요.
</Info>

<Warning>
  만약 브라우저에 로그인 된 GitHub 계정이 GitHub App을 생성했던 계정과 동일하다면 위와 같은 창이 표시되지 않습니다.
  새로운 브라우저 세션에서 GitHub App을 생성했던 계정이 아닌 다른 GitHub 계정으로 인증을 진행하세요.
</Warning>

<Tip>
  [GitHub App을 비공개로 설정](/ko/authentication/github#github-app-%EA%B3%B5%EA%B0%9C-%EC%84%A4%EC%A0%95)한 경우, 로그인하려는 다른 계정이 GitHub App을 생성한 계정의 조직에 속해있어야 GitHub 계정으로 로그인할 수 있습니다.
</Tip>

<Frame>
  <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/authentication/images/01_14.png" />
</Frame>

> 관리자 승인 이후 GitHub login을 시도하면 **가입 완료하기** 페이지가 표시됩니다.
> 스페이스 및 이름을 적절하게 작성하고 `완료하기`를 클릭하세요.

<Info>
  대시보드 접속과 함께 지정한 이름의 스페이스가 생성되며, [운영 시스템에서 미리 정한 Default 값의 리소스](/ko/operations/settings#%EB%A6%AC%EC%86%8C%EC%8A%A4-%ED%94%84%EB%A1%9C%ED%8C%8C%EC%9D%BC-%EA%B4%80%EB%A6%AC)가 부여됩니다.
</Info>

<Tip>
  사용자 등록 및 관리에 관한 내용은 [사용자 관리 페이지](/ko/operations/user-management)를 참고하세요.
</Tip>