GitHub 연동

이 가이드는 전체 설정 과정을 설명합니다. 여기에는 GitHub 계정을 Atoms에 연결하는 방법, 리포지토리를 만드는 방법, 연결이 정상적으로 작동하는지 확인하는 방법, 그리고 프로젝트의 Atoms 버전과 GitHub 버전을 동기화 상태로 유지하는 방법이 포함됩니다.

연결 작동 방식

GitHub 연결은 2단계로 이루어집니다.

1. GitHub 계정 연결. 이 단계에서 Atoms가 사용자를 대신해 GitHub에서 작업할 수 있도록 권한을 부여합니다.
2. 프로젝트용 리포지토리 만들기. 리포지토리는 프로젝트의 코드와 변경 기록이 저장되는 GitHub 내 비공개 공간입니다.

현재 Atoms는 연결된 사용자의 개인 GitHub 계정에 새 비공개 리포지토리 를 생성합니다. 기존 리포지토리에 연결하거나, 조직 아래에 리포지토리를 만들거나, 커넥터를 통해 공개로 설정할 수는 없습니다.

시작하기 전에

프로젝트를 GitHub에 연결하기 전에 다음 사항을 확인하세요.

• 사용 중인 Atoms 플랜에 GitHub 연결 이 포함되어 있어야 합니다. Free 플랜을 사용 중이라면 GitHub를 선택할 때 Plans 페이지로 이동합니다.
• 워크스페이스 소유자 만 GitHub를 연결하거나 연결 해제할 수 있습니다. 편집자라면 워크스페이스 소유자에게 이 단계를 수행해 달라고 요청하세요.
• GitHub 계정이 있거나 설정 중에 새로 만들 준비가 되어 있어야 합니다.
• 브라우저가 Atoms의 팝업 창을 허용해야 합니다.
• 현재 프로젝트에서 작업 중인 에이전트 가 없어야 합니다.

계정을 연결하기 위해 GitHub personal access token은 필요하지 않습니다. GitHub 토큰, 비밀번호 또는 기타 자격 증명을 절대로 Chat에 붙여넣지 마세요.

GitHub 계정 연결

GitHub 커넥터 열기

1. 연결하려는 프로젝트를 엽니다.
2. 채팅 패널 오른쪽 상단에서 프로젝트 이름을 클릭합니다.
3. 표시되는 드롭다운 메뉴에서 Connectors 를 선택합니다.
4. 사용 가능한 커넥터 목록에서 Github 를 찾은 다음 connect 를 클릭합니다.

또는 Settings → Connectors → GitHub 를 열고 Connect 를 선택할 수도 있습니다.

Settings → Connectors를 열고 GitHub의 Connect를 선택합니다.

GitHub에서 Atoms 승인

Connected Account 에 이미 사용하려는 GitHub 계정이 표시되어 있다면, 이미 승인이 완료된 상태입니다. 계속해서 비공개 리포지토리 만들기 로 진행할 수 있습니다.

1. Atoms가 GitHub 승인 창을 엽니다. 연결하려는 GitHub 계정으로 로그인하거나, 필요하면 새 계정을 만듭니다.
2. 올바른 GitHub 계정으로 로그인되어 있는지 확인합니다.
3. Atoms가 요청하는 권한을 검토합니다. 동의하면 Authorize Atoms-Agents 를 선택합니다.
4. Atoms로 돌아와 Connect success 메시지가 나타날 때까지 기다립니다.
5. Atoms에서 Connectors 를 열고 GitHub 계정이 연결된 것으로 표시되는지 확인합니다.

Atoms는 repo, read:user, workflow OAuth 권한을 요청합니다. 이 권한을 통해 Atoms는 연결된 계정이 접근할 수 있는 공개 및 비공개 리포지토리를 읽고 쓸 수 있으며, 기본 프로필 정보를 읽고, GitHub Actions 워크플로 파일을 추가하거나 업데이트할 수 있습니다.

이 승인은 연결된 GitHub 계정에 적용되며 현재 Atoms 프로젝트를 위해 생성된 리포지토리에만 제한되지 않습니다. Atoms는 연결된 계정 자체가 접근할 수 없는 리포지토리에는 접근할 수 없으며, 조직 정책에 따라 추가 제한이 적용될 수 있습니다.

GitHub 권한을 검토하고 Authorize Atoms-Agents를 선택합니다.

비공개 리포지토리 만들기

GitHub 계정 승인을 마친 후에는 프로젝트 코드를 저장할 비공개 리포지토리를 만듭니다.

1. Connected Account 아래에서 표시된 사용자 이름이 사용하려는 GitHub 계정과 일치하는지 확인합니다.
2. Create New Repository 아래에서 리포지토리 이름을 입력합니다. 이름은 다음 조건을 충족해야 합니다.
   • 1~100자여야 합니다.
   • 영문자, 숫자, 하이픈(-), 밑줄(_), 마침표(.)만 사용할 수 있습니다.
3. Create 를 선택합니다.
4. GitHub repository connected successfully! 메시지가 나타날 때까지 기다립니다.

Atoms는 연결된 사용자의 개인 GitHub 계정에 새 비공개 리포지토리 를 만들고, 이를 현재 Atoms 프로젝트에 연결한 다음, 프로젝트의 현재 파일을 GitHub에 업로드하려고 시도합니다.

이름을 입력하고 새 비공개 리포지토리를 만듭니다.

연결이 정상적으로 작동했는지 확인하기

리포지토리를 본격적으로 사용하기 전에 Atoms와 GitHub 양쪽에서 연결 상태를 확인하세요.

1. Atoms에서 Repository Status 가 Connected 로 표시되는지 확인합니다.
2. Branches 아래에서 한 브랜치에 체크 표시가 있는지 확인합니다. 이 브랜치가 현재 Atoms 프로젝트에 연결된 브랜치입니다. GitHub가 익숙하지 않다면 이 브랜치를 그대로 선택된 상태로 유지하세요.
3. View on GitHub 를 선택합니다.
4. GitHub에서 다음 사항을 확인합니다.
   • 올바른 GitHub 계정에 속해 있는지
   • Private 로 표시되는지
   • 예상한 프로젝트 파일이 포함되어 있는지
   • 최소 하나의 commit 이 있는지

리포지토리가 비어 있고 Atoms에서 Push Changes 를 사용할 수 있다면, 이를 선택하고 작업이 끝날 때까지 기다리세요. 그런 다음 GitHub에서 리포지토리 페이지를 새로고침하고 프로젝트 파일이 표시되는지 확인합니다.

Atoms에서 연결된 리포지토리와 선택된 브랜치를 확인합니다.

GitHub에서 비공개 리포지토리와 프로젝트 파일을 확인합니다.

Atoms와 GitHub를 동기화 상태로 유지하기

Atoms와 GitHub는 자동으로 동기화되지 않습니다. 한쪽에서 변경이 발생하면 동기화 컨트롤을 사용해 그 변경 사항을 다른 쪽으로 이동해야 합니다.

Action	Use it when	What happens
Push Changes	Atoms에서 변경했고 이를 GitHub로 보내고 싶을 때	Atoms가 현재 프로젝트 파일을 선택된 GitHub 브랜치로 전송합니다.
Pull Updates	GitHub의 선택된 브랜치에서 변경이 발생했고 이를 Atoms로 가져오고 싶을 때	Atoms가 GitHub의 최신 변경 사항으로 프로젝트를 업데이트합니다.

변경 사항을 push하거나 pull하기 전에 에이전트 가 작업을 마칠 때까지 기다리고, Chat에서 프로젝트의 최신 버전을 보고 있는지 확인하세요. History 에서 이전 버전을 열었다면 Chat 하단의 최신 버전 카드로 돌아간 다음 GitHub 를 다시 여세요.

최신 버전에 있지 않으면 Atoms는 You must be on the latest version to pull updates or push changes. 를 표시합니다.

동기화하기 전에 선택된 브랜치가 업데이트하려는 브랜치인지도 확인하세요.

Atoms와 GitHub 양쪽 모두에 유지해야 할 변경 사항이 있다면 아직 동기화하지 마세요. 먼저 중요한 작업의 사본을 저장하거나, GitHub에 익숙한 사람에게 별도 브랜치에 변경 사항을 보존해 달라고 요청하세요.

Repository Status 가 Upstream Changes Available 로 표시되면 GitHub에 Atoms에 아직 없는 변경 사항이 있다는 뜻입니다. 작업을 선택하기 전에 리포지토리를 검토하세요.

선택된 브랜치에 대해 Pull Updates와 Push Changes를 사용합니다.

Atoms에서 GitHub로 변경 사항 push하기

1. Atoms에서 변경 작업을 마치고 에이전트 가 작업을 멈출 때까지 기다립니다.
2. 프로젝트의 최신 버전을 보고 있는지 확인합니다.
3. Settings → Connectors → GitHub 를 열고 올바른 브랜치가 선택되어 있는지 확인합니다.
4. Push Changes 를 선택합니다.
5. 변경 사항이 push되는 동안 페이지를 열어 둡니다.
6. Changes pushed successfully 가 표시되면 View on GitHub 를 선택하고 최신 프로젝트 파일이 있는지 확인합니다.

Push Changes 는 Atoms에 아직 GitHub로 전송되지 않은 변경 사항이 있을 때만 사용할 수 있습니다. 에이전트 가 작업 중이거나 프로젝트의 이전 버전을 보고 있을 때는 사용할 수 없습니다.

Push Changes 를 선택하면 확인 절차 없이 변경 사항이 즉시 GitHub로 전송됩니다. 같은 파일이 Atoms와 GitHub 양쪽에서 모두 변경된 경우, Atoms 버전이 우선하며 현재 GitHub에 저장된 버전을 덮어씁니다.

GitHub에서 Atoms로 업데이트 pull하기

push와 달리, 변경 사항을 pull하려면 먼저 확인이 필요합니다. 같은 파일이 GitHub와 Atoms 양쪽에서 모두 변경된 경우 GitHub 버전이 우선하며 Atoms의 현재 버전을 덮어씁니다.

1. Settings → Connectors → GitHub 를 엽니다.
2. Repository Status 에 GitHub의 새 변경 사항이 표시되고 올바른 브랜치가 선택되어 있는지 확인합니다.
3. Pull Updates 를 선택합니다.
4. Pull May Affect Project 경고를 읽습니다. GitHub 변경 사항을 현재 Atoms 프로젝트로 가져오려면 Confirm 을 선택합니다.
5. 변경 사항이 pull되는 동안 페이지를 열어 둡니다.
6. Changes pulled successfully 가 표시되면 App 뷰어 를 열고 변경의 영향을 받은 프로젝트 부분을 테스트하여 모든 것이 예상대로 계속 작동하는지 확인합니다.

Pull Updates 는 선택된 GitHub 브랜치에 아직 Atoms로 가져오지 않은 변경 사항이 있을 때만 사용할 수 있습니다.

GitHub 연결 해제

더 이상 Atoms가 연결된 계정에 접근하지 않도록 하려면 GitHub 연결을 해제하세요. GitHub 리포지토리와 그 파일은 GitHub에 그대로 남지만, Atoms는 더 이상 변경 사항을 push하거나 pull할 수 없습니다.

GitHub 승인은 연결된 계정에 적용됩니다. 접근 권한을 취소하면 해당 GitHub 계정을 사용하는 모든 Atoms 프로젝트의 연결이 해제되므로, 계속하기 전에 다른 프로젝트도 확인하세요.

1. Settings → Connectors → GitHub 를 엽니다.
2. Disconnect 를 선택합니다.
3. Disconnect GitHub 확인 창에서 다시 Disconnect 를 선택합니다.
4. GitHub가 관련 승인 페이지를 자동으로 열어야 합니다. 열리지 않으면 GitHub에서 Settings → Applications → Authorized OAuth Apps 로 이동합니다.
5. Atoms 를 찾고 해당 행 오른쪽의 ... 를 선택한 다음 Revoke 를 선택합니다. Revoke all 은 선택하지 마세요. 이 작업은 페이지에 나열된 승인된 모든 OAuth 앱의 접근 권한을 제거합니다.
6. Github에서 필요한 확인 단계를 진행합니다.
7. Atoms로 돌아와 GitHub 커넥터를 다시 열고 계정 연결이 해제되었는지 확인합니다.

GitHub 커넥터에서 Disconnect를 선택합니다.

GitHub에서 Atoms OAuth 애플리케이션만 Revoke합니다.