Atoms 프로젝트를 GitHub에 연결하여 코드를 비공개 리포지토리에 보관하고, Git 명령어를 사용하지 않고도 Atoms와 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 개인 액세스 토큰은 필요하지 않습니다. 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는 자동으로 동기화되지 않습니다. 한쪽에서 변경이 발생하면 동기화 컨트롤을 사용해 그 변경 사항을 다른 쪽으로 이동하세요.

작업	사용 시점	수행 결과
Push Changes	Atoms에서 변경을 했고 이를 GitHub로 보내고 싶을 때 사용합니다.	Atoms가 현재 프로젝트 파일을 선택된 GitHub 브랜치로 전송합니다.
Pull Updates	GitHub의 선택된 브랜치에서 변경이 발생했고 이를 Atoms로 가져오고 싶을 때 사용합니다.	Atoms가 GitHub의 최신 변경 사항으로 프로젝트를 업데이트합니다.

변경 사항을 푸시하거나 풀하기 전에 에이전트가 작업을 마칠 때까지 기다리고, 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로 변경 사항 푸시

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

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

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

GitHub에서 Atoms로 업데이트 가져오기

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

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

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

GitHub 연결 해제

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

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 애플리케이션만 취소합니다.