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

# 계정 & 인증

> 토큰/OAuth/SSH 계정 관리

ParalleLane에 Git 호스트 계정을 한 번 등록해 두면 저장소마다 어떤 신원과 인증을 쓸지 골라 끼울 수 있습니다. 선택한 값은 Git 네이티브 설정(`.git/config`, credential 저장소, SSH)에 그대로 기록되므로 터미널 등 ParalleLane 밖에서도 동일하게 적용됩니다.

<Frame>
  <img src="https://mintcdn.com/railgit/1HhHpeGsA-i8McQ3/images/settings-accounts.png?fit=max&auto=format&n=1HhHpeGsA-i8McQ3&q=85&s=0f65d40936ebe3e2adab3c3c46e72573" alt="토큰·OAuth·SSH 계정 카드가 나열되고 각 카드에 서버 종류와 인증 방식 배지가 붙은 계정(Accounts) 설정 화면" width="2906" height="1784" data-path="images/settings-accounts.png" />
</Frame>

## 계정은 어디서 관리하나요

계정 관련 화면은 두 곳으로 나뉩니다.

<CardGroup cols={2}>
  <Card title="설정 → ParalleLane → 계정(Accounts)" icon="user">
    머신에 등록된 모든 계정을 추가·편집·삭제합니다. 계정은 이름/이메일 + 인증 방식(토큰·OAuth·SSH)으로 구성됩니다.
  </Card>

  <Card title="설정 → 프로젝트(Projects) → 계정(Account)" icon="folder-git">
    저장소별로 어떤 계정을 쓸지 선택합니다. 선택하는 순간 그 저장소의 Git 설정에 기록됩니다.
  </Card>
</CardGroup>

설정 화면 상단의 **ParalleLane** 탭과 **프로젝트(Projects)** 탭에서 각각 접근합니다. 설정 화면 여는 방법은 [설정](/settings/preferences)을 참고하세요.

## 계정 추가하기

계정 추가는 "플랫폼을 먼저 고르고, 그 플랫폼에 맞는 필드만 채우는" 흐름입니다.

<Steps>
  <Step title="계정 추가 열기">
    **설정 → ParalleLane → 계정(Accounts)** 패널 헤더 오른쪽의 **계정 추가** 버튼을 누르면 플랫폼 선택 드롭다운이 열립니다.
  </Step>

  <Step title="플랫폼 선택">
    GitHub / GitHub Enterprise / GitLab / GitLab Server / Bitbucket / Bitbucket Server / SSH 중 하나를 고릅니다. 선택한 플랫폼에 맞는 입력 폼이 열립니다.
  </Step>

  <Step title="인증 정보 입력">
    아래 탭에서 인증 방식별 입력 방법을 확인하세요. 공통으로 **라벨 (선택)**, **git user.name**, **git user.email**을 입력합니다. 라벨을 비우면 목록에 git 이름이 표시됩니다.
  </Step>

  <Step title="추가">
    **추가** 버튼을 누르면 계정 카드가 목록에 나타납니다.
  </Step>
</Steps>

<Frame>
  <img src="https://mintcdn.com/railgit/1HhHpeGsA-i8McQ3/images/settings-account-add-token.png?fit=max&auto=format&n=1HhHpeGsA-i8McQ3&q=85&s=5c53c4f658fef912701a6a1545efa10b" alt="인증 유형 선택과 git user.name·user.email 입력란이 있는 GitHub 계정 추가 모달" width="886" height="820" data-path="images/settings-account-add-token.png" />
</Frame>

<Note>
  GitHub(github.com)과 Bitbucket Cloud에는 **인증 유형(Authentication Type)** 드롭다운이 함께 표시됩니다. 신규 GitHub 계정은 이 드롭다운이 **OAuth로 이미 선택**되어 있어(선택된 값이 **GitHub으로 로그인**으로 표시됩니다) 드롭다운을 건드릴 필요 없이 바로 로그인을 시작할 수 있습니다. 토큰을 직접 붙여넣으려면 드롭다운에서 **Personal Access Token**으로 바꾸세요. Bitbucket Cloud는 OAuth 항목이 \*\*OAuth (준비 중)\*\*으로 비활성 표시되며 **App Password**만 선택할 수 있습니다.
</Note>

<Note>
  Basic은 계정을 최대 2개까지 등록할 수 있습니다. 한도에 도달하면 **계정 추가** 버튼에 **PRO** 배지가 붙고, 눌렀을 때 드롭다운 대신 업그레이드 안내가 표시됩니다. GitHub Enterprise·GitLab Server·Bitbucket Server 같은 셀프호스트 항목에도 Basic에서는 **PRO** 배지가 붙고 선택하면 업그레이드 안내로 이어집니다. 현재 요금제는 [요금제 & 라이선스](/settings/plan-license)에서 확인하세요.
</Note>

<Tabs>
  <Tab title="개인 액세스 토큰">
    GitHub·GitLab·Bitbucket 등 대부분의 호스트에서 쓰는 기본 방식입니다.

    * 호스트: Cloud(github.com 등)는 고정, Enterprise/Server 계열은 **host** 칸에 직접 입력합니다.
    * Bitbucket과 Bitbucket Server는 **username** 칸이 추가로 나타나며, 비워 두면 저장할 수 없습니다.
    * **토큰** 입력란에 발급받은 개인 액세스 토큰(GitHub `ghp_…`, GitLab `glpat-…`, Bitbucket 앱 비밀번호, Bitbucket Server HTTP 액세스 토큰)을 붙여넣습니다.
    * **토큰 생성 페이지 열기** 링크로 해당 호스트의 토큰 발급 화면을 바로 열 수 있고, \*\*필요 권한(최소)\*\*에서 요구 스코프를 확인할 수 있습니다.
    * **검증** 버튼을 누르면 토큰이 확인되고, 비어 있던 **git user.name**·**git user.email**이 계정 정보로 채워지며 username과 아바타가 함께 저장됩니다.

    <Note>토큰은 OS 키체인(macOS 키체인, Windows 자격 증명 관리자 등)에 저장되며, 평문으로 디스크에 남지 않습니다.</Note>

    <Warning>새 토큰을 입력했다면 **검증**이 성공해야 **추가**·**저장** 버튼이 활성화됩니다. 이미 저장된 계정을 편집할 때 토큰 칸을 비워 두고 인증 방식을 바꾸지 않으면 기존 토큰이 그대로 유지되므로 다시 검증할 필요가 없습니다.</Warning>
  </Tab>

  <Tab title="GitHub OAuth">
    GitHub에서는 토큰을 직접 발급하지 않고 브라우저 로그인(디바이스 코드, Device Flow)으로 계정을 연결할 수 있습니다. 신규 GitHub 계정은 이 방식이 **기본으로 선택되어 있으므로** 인증 유형 드롭다운을 열 필요가 없습니다.

    <Steps>
      <Step title="로그인 시작">
        GitHub 계정 폼에서 **GitHub으로 로그인** 버튼을 누릅니다.
      </Step>

      <Step title="코드 확인 및 브라우저 인증">
        폼 안에 "아래 코드를 GitHub에 입력하세요." 안내와 큰 글씨의 사용자 코드(예: `PLNE-2026`)가 나타납니다. **코드 복사**로 코드를 복사하고, **GitHub에서 인증하기** 버튼으로 브라우저의 인증 페이지를 엽니다. 같은 카드 아래에 "브라우저에서 승인을 기다리는 중…"이 함께 표시됩니다.
      </Step>

      <Step title="승인 완료">
        브라우저에서 코드를 입력·승인하면 ParalleLane이 자동으로 토큰을 받아 카드가 **@사용자명 계정으로 로그인됨**으로 바뀌고, 비어 있던 이름·이메일을 채웁니다. 다른 계정으로 다시 하려면 **다른 계정으로 로그인**을 누릅니다.
      </Step>

      <Step title="추가">
        **추가**를 눌러 계정을 저장합니다.
      </Step>
    </Steps>

    <Frame>
      <img src="https://mintcdn.com/railgit/1HhHpeGsA-i8McQ3/images/settings-account-add-oauth.png?fit=max&auto=format&n=1HhHpeGsA-i8McQ3&q=85&s=0e48c13513149ed67fa6f348057cfed0" alt="디바이스 코드 PLNE-2026과 GitHub에서 인증하기 버튼, 승인 대기 문구가 한 카드에 표시된 GitHub 계정 추가 모달" width="886" height="1004" data-path="images/settings-account-add-oauth.png" />
    </Frame>

    <Warning>
      OAuth 로그인은 GitHub(github.com) 계정에만 동작합니다. GitHub Enterprise·GitLab·GitLab Server·Bitbucket Server는 토큰 방식만 사용하고, Bitbucket Cloud의 OAuth 항목은 \*\*OAuth (준비 중)\*\*으로 비활성 표시됩니다.
    </Warning>

    <Note>
      실행 중인 빌드에 GitHub 로그인이 구성되어 있지 않으면 상황에 따라 두 가지 안내가 표시됩니다.

      * **새 계정을 추가할 때**: 인증 유형이 자동으로 토큰 입력으로 되돌아가고 **GitHub 로그인 사용 불가** — "이 빌드는 GitHub 로그인을 지원하지 않습니다. 대신 개인 액세스 토큰을 사용하세요."가 표시됩니다.
      * **이미 OAuth로 저장된 계정을 편집할 때**: 인증 방식과 자격 증명을 그대로 유지하며 "이 빌드에서는 GitHub 로그인을 사용할 수 없지만, 이 계정의 기존 로그인 자격 증명은 그대로 유지되어 계속 작동합니다."가 표시됩니다.
    </Note>
  </Tab>

  <Tab title="SSH 키">
    SSH 계정은 특정 호스트에 묶이지 않습니다. 키만 지정하면 됩니다.

    * **키 선택** 드롭다운에서 `~/.ssh`에 있는 기존 키를 고르거나, **새 SSH 키 만들기**로 키를 생성합니다.
    * **공개키 복사**로 공개키를 복사한 뒤, GitHub/GitLab/Bitbucket 계정 설정의 SSH 키 항목에 등록합니다. **GitHub에 등록** 같은 링크로 등록 페이지를 바로 열 수 있습니다.
    * **SSH 폴더 열기**로 `~/.ssh` 폴더를 Finder에서 엽니다.

    <Tip>SSH 계정을 저장소에 적용하려면 그 저장소의 원격 URL이 SSH 형식(`git@…`)이어야 키가 실제로 사용됩니다. HTTPS 원격이면 경고가 표시됩니다.</Tip>
  </Tab>
</Tabs>

## 연결 상태 확인

각 계정 카드에는 라벨(비우면 git 이름), 이름·이메일, 서버 종류 배지와 인증 방식 배지가 표시됩니다. 전역 기본 계정에는 **글로벌** 배지가, 특정 저장소에 적용된 계정에는 `# 저장소명` 배지가 함께 붙습니다. 카드의 **상태 확인** 버튼으로 상태를 갱신합니다.

* **토큰/OAuth 계정**: 제목 옆에 `Online` / `Offline`과 username이 표시됩니다. **상태 확인**은 토큰을 재검증해 이 표시와 아바타를 갱신합니다.
* **SSH 계정**: `Online` / `Offline` 표시가 없습니다. **상태 확인**을 누르면 테스트할 호스트를 고르는 팝오버가 열리고(github.com·gitlab.com·bitbucket.org 프리셋 또는 직접 입력), 인증에 성공한 호스트 목록이 카드에 나열됩니다.

카드의 **편집**으로 라벨·이름·이메일·토큰을 수정하고, **삭제**로 계정과 키체인의 토큰을 함께 제거합니다.

<Note>전역 기본 계정이거나 어떤 저장소에 적용된 계정은 **삭제** 버튼이 비활성 상태이며, "사용 중인 계정은 삭제할 수 없습니다" 툴팁이 표시됩니다. 먼저 해당 저장소와 [설정 → ParalleLane → Git](/settings/preferences)의 **기본 계정**에서 다른 계정으로 바꾸세요.</Note>

## 저장소에 계정 적용하기

저장소가 어떤 계정을 쓸지는 \*\*설정 → 프로젝트(Projects) → 계정(Account)\*\*에서 정합니다.

<Steps>
  <Step title="프로젝트 선택">
    설정 상단 **프로젝트(Projects)** 탭으로 전환하고, 프로젝트 드롭다운에서 저장소를 고릅니다.
  </Step>

  <Step title="계정 선택">
    **이 저장소의 계정** 드롭다운에서 **Global (머신 전역 설정)** 또는 등록된 계정 중 하나를 선택합니다. 선택하는 즉시 저장소의 Git 설정에 반영되고 "계정이 적용되었습니다." 토스트가 표시됩니다.
  </Step>
</Steps>

<Frame>
  <img src="https://mintcdn.com/railgit/1HhHpeGsA-i8McQ3/images/settings-account-per-repo.png?fit=max&auto=format&n=1HhHpeGsA-i8McQ3&q=85&s=1f2df95e7c0b94e3cf50d39e76d4366e" alt="프로젝트(Projects) 탭에서 선택한 저장소의 계정을 고르는 계정 설정 화면" width="2906" height="1784" data-path="images/settings-account-per-repo.png" />
</Frame>

선택에 따라 다음이 기록됩니다.

| 선택         | 기록되는 내용                                                                              |
| ---------- | ------------------------------------------------------------------------------------ |
| **Global** | ParalleLane이 넣었던 저장소 로컬 오버라이드를 제거하고, 머신 전역 Git 설정을 따릅니다.                             |
| **SSH 계정** | `user.name`/`user.email`과 `core.sshCommand`를 저장소 로컬 설정에 기록합니다.                       |
| **토큰 계정**  | `user.name`/`user.email`을 기록하고, 원격 URL의 사용자 정보를 갱신하며, 토큰을 Git credential 저장소에 저장합니다. |

<Note>계정 적용 대상 원격은 `origin` 하나입니다. `Global`은 머신 전역 기본 계정을 따르며, 이 전역 기본 계정은 [설정 → ParalleLane → Git](/settings/preferences)의 **기본 계정**에서 지정합니다.</Note>

## 아바타

토큰/OAuth 계정은 계정을 만들 때 호스트 API에서 프로필 사진을 가져오고, 실패하거나 사진이 없으면 이메일 기반 Gravatar를 사용합니다. SSH·Global 계정은 이메일 Gravatar를 사용합니다.

이미 저장된 계정은 **편집** 화면에서 아바타를 직접 다시 가져올 수 있습니다. 이름·이메일 입력란 아래에 **아바타** 행이 나타나고, 현재 아바타 미리보기와 함께 다음 버튼이 표시됩니다.

| 버튼                 | 표시 조건                      | 동작                          |
| ------------------ | -------------------------- | --------------------------- |
| **Gravatar에서 동기화** | 저장된 모든 계정                  | 계정 이메일의 Gravatar를 다시 가져옵니다. |
| **GitHub에서 동기화**   | 저장된 GitHub 계정(토큰·OAuth 모두) | GitHub 프로필 사진을 다시 가져옵니다.    |

동기화 중에는 버튼이 **동기화 중…** 으로 바뀌고, 끝나면 성공 또는 실패 토스트가 표시됩니다.

<Note>
  이메일이나 인증 방식을 바꾸고 아직 저장하지 않으면 두 버튼이 비활성화되고 "아바타를 동기화하기 전에 이메일 또는 인증 방식 변경사항을 저장하세요."가 표시됩니다. **저장**을 먼저 누른 뒤 동기화하세요.
</Note>

## 인증 오류 해결

Push, Pull, Fetch 또는 Clone이 실패하면 ParalleLane은 원본 Git 오류와 함께 가능한 원인을 구분해 안내합니다.

| 안내                 | 확인할 내용                                                              |
| ------------------ | ------------------------------------------------------------------- |
| 경로별 자격증명 불일치       | 저장소의 `credential.useHttpPath`를 끄거나 해당 저장소 경로에 맞는 credential을 등록합니다. |
| 저장된 HTTPS 자격증명 없음  | 프로젝트 계정을 다시 선택하고 토큰이 OS credential 저장소에 남아 있는지 확인합니다.               |
| 토큰 또는 비밀번호 거절      | 토큰 만료·폐기 여부, username과 필요한 scope를 확인합니다.                            |
| 저장소 권한 부족          | 선택 계정의 collaborator/team 권한과 조직 SSO 승인을 확인합니다.                      |
| 저장소를 찾을 수 없음       | remote URL과 비공개 저장소 조회 권한을 확인합니다.                                   |
| SSH 공개키 거절         | 저장소 계정이 올바른 개인키를 쓰는지, 공개키가 Git 호스트에 등록됐는지 확인합니다.                    |
| SSH host key 검증 실패 | `known_hosts` 항목을 확인하고 서버 키 변경이 정상적인지 먼저 검증합니다.                     |

<Warning>
  ParalleLane은 오류를 진단하기 위해 토큰 값을 읽거나 로그에 남기지 않습니다. 안내 아래의 원본 Git 오류를 함께 확인하되, 자격증명을 문서나 이슈에 붙여넣지 마세요.
</Warning>