> ## 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

> Guide for adding GitHub OAuth to `ale`

> Adding **GitHub OAuth** enables GitHub login and allows dashboard users to deploy services by selecting repositories from their GitHub accounts.

***

## Create GitHub App

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

> Navigate to **Settings > Developer Settings > GitHub Apps** and click [New GitHub App](https://github.com/settings/apps/new).

### Provide Basic Information

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

> Fill in the following details to set up your GitHub App:

* **GitHub App name**: Name for your GitHub App
* **Homepage URL**:
  * URL of the website where GitHub OAuth will be used.
  * Use `https://app.[domain]` (URL deployed with Ingress)
* **Callback URL (add using `Add Callback URL`)**:
  * `https://app.[domain]/api/oauth/github/callback`
  * `https://app.[domain]/api/oauth/github/connect/callback`

<Info>
  The **GitHub App name** will be used when registering GitHub OAuth in `ale`.
</Info>

<Tip>
  `https://app.[domain]/api/` is the API endpoint address for `ale`.
</Tip>

### Disable Webhook

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

> Uncheck the Active option in the Webhook section to disable it.

### Grant Permissions and Create APP

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

> In the Permissions section, grant the following permissions and click `Create GitHub 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>

## Get GitHub App Information

> To add GitHub OAuth to `ale`, you'll need **4 ID/Key values**.

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

### App ID and Client ID

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

> After the App is created with permissions, you can view the **App ID and Client ID**.

### Client Secret

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

> On the same page, click `Generate a new client secret` to create and view the **Client Secret**.

### Private Key

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

> Click `Generate a private key` at the bottom of the page to download the pem file.

## GitHub App Visibility

> By default, newly created GitHub Apps are **private** and can only be used by members of the organization where the App was created. To make the GitHub App available regardless of GitHub organization, follow the steps below.

<AccordionGroup>
  <Accordion title="Make GitHub App Public" defaultOpen={true}>
    <Frame>
      <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/authentication/images/01_16.png" />
    </Frame>

    > Click `Make public` in the **Danger Zone** section under the **Advanced** settings.
  </Accordion>
</AccordionGroup>

## Integrate GitHub App in ale

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

> Access the operations system, click the **Settings > Authentication > GitHub**, enter the values in previous steps into each field, and click `Apply`.

* **Enable Login**: Enable GitHub OAuth login
* **APP\_NAME**: GitHub App name
* **APP\_ID**: App ID
* **CLIENT\_ID**: Client ID
* **CLIENT\_SECRET**: Client secret
* **APP\_PRIVATE\_KEY**: Private key pem file value

<Info>
  After applying, check that the **Sign in with GitHub** button appears on the login page.

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

## Sign up with GitHub Account

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

> After signing up with a GitHub account, you'll see a message 'Admin approval is required.'

<Info>
  To approve (activate) signed up users, see the [User Management page](/en/operations/user-management#activation).
</Info>

<Warning>
  If the GitHub account logged into your browser is the same as the account that created the GitHub App, the GitHub authorization modal won't appear.
  To test GitHub OAuth, sign up with a different GitHub account in a new browser session.
</Warning>

<Tip>
  If you've [set your GitHub App to private](/en/authentication/github#github-app-visibility), users attempting to log in need to belong to the same organization as the account that created the GitHub App.
</Tip>

<Frame>
  <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/setup/ec2/images/en/04_25.png" />
</Frame>

> After administrator approval, attempting GitHub login will display the **Complete Registration** page.
> Enter appropriate space and name information, then click `Complete`.

<Info>
  Upon accessing the dashboard, a space with your specified name will be created, and it will be allocated [default resource values predetermined in the operations system](/en/operations/settings#resource-profile-management).
</Info>

<Tip>
  For information about user registration and management, refer to the [User Management page](/en/operations/user-management).
</Tip>