Kết nối dự án Atoms của bạn với GitHub để lưu mã của dự án trong một kho lưu trữ riêng tư và chuyển các thay đổi giữa Atoms và GitHub mà không cần dùng lệnh Git.

Hướng dẫn này giải thích toàn bộ quy trình thiết lập: kết nối tài khoản GitHub của bạn với Atoms, tạo kho lưu trữ, xác nhận rằng kết nối đang hoạt động và giữ cho các phiên bản dự án của bạn trên Atoms và GitHub được đồng bộ.

Cách kết nối hoạt động

Có 2 giai đoạn để kết nối GitHub:

1. Kết nối tài khoản GitHub của bạn. Việc này cấp cho Atoms quyền làm việc với GitHub thay mặt bạn.
2. Tạo kho lưu trữ cho dự án của bạn. Kho lưu trữ là không gian riêng tư trên GitHub nơi mã và lịch sử thay đổi của dự án được lưu trữ.

Hiện tại, Atoms tạo một kho lưu trữ riêng tư mới trong tài khoản GitHub cá nhân của người dùng đã kết nối. Bạn không thể kết nối với một kho lưu trữ hiện có, tạo kho lưu trữ dưới một tổ chức hoặc đặt kho lưu trữ ở chế độ công khai thông qua trình kết nối.

Trước khi bắt đầu

Trước khi kết nối dự án của bạn với GitHub, hãy đảm bảo rằng:

• Gói Atoms của bạn bao gồm kết nối GitHub. Nếu bạn đang dùng gói Free, việc chọn GitHub sẽ đưa bạn đến trang Plans.
• Chỉ chủ sở hữu không gian làm việc mới có thể kết nối hoặc ngắt kết nối GitHub. Nếu bạn là người chỉnh sửa, hãy yêu cầu chủ sở hữu không gian làm việc thực hiện bước này.
• Bạn có tài khoản GitHub hoặc sẵn sàng tạo một tài khoản trong quá trình thiết lập.
• Trình duyệt của bạn cho phép cửa sổ bật lên từ Atoms.
• Hiện không có Agent nào đang làm việc trên dự án của bạn.

Bạn không cần token truy cập cá nhân GitHub để kết nối tài khoản của mình. Không bao giờ dán token GitHub, mật khẩu hoặc thông tin xác thực khác vào Chat.

Kết nối tài khoản GitHub của bạn

Mở trình kết nối GitHub

1. Mở dự án bạn muốn kết nối.
2. Nhấp vào tên dự án ở góc trên bên phải của bảng chat.
3. Chọn Connectors trong menu thả xuống xuất hiện.
4. Tìm Github trong danh sách các trình kết nối khả dụng và nhấp vào connect.

Bạn cũng có thể mở Settings → Connectors → GitHub và chọn Connect.

Mở Settings → Connectors và chọn Connect cho GitHub.

Ủy quyền Atoms trong GitHub

Nếu Connected Account đã hiển thị tài khoản GitHub bạn muốn dùng, thì tài khoản đó đã được ủy quyền. Bạn có thể tiếp tục đến bước Create a private repository.

1. Atoms mở một cửa sổ ủy quyền GitHub. Đăng nhập vào tài khoản GitHub bạn muốn kết nối hoặc tạo tài khoản mới nếu cần.
2. Kiểm tra rằng bạn đã đăng nhập đúng tài khoản GitHub.
3. Xem lại các quyền mà Atoms yêu cầu. Nếu bạn đồng ý, hãy chọn Authorize Atoms-Agents.
4. Quay lại Atoms và chờ thông báo Connect success.
5. Trong Atoms, mở Connectors và xác nhận rằng tài khoản GitHub của bạn hiển thị là đã kết nối.

Atoms yêu cầu các quyền OAuth repo, read:user và workflow. Các quyền này cho phép Atoms đọc và ghi các kho lưu trữ công khai và riêng tư mà tài khoản đã kết nối có thể truy cập, đọc thông tin hồ sơ cơ bản và thêm hoặc cập nhật các tệp quy trình làm việc GitHub Actions.

Việc ủy quyền này áp dụng cho tài khoản GitHub đã kết nối và không bị giới hạn ở kho lưu trữ được tạo cho dự án Atoms hiện tại. Atoms không thể truy cập các kho lưu trữ mà chính tài khoản đã kết nối không thể truy cập, và chính sách của tổ chức có thể áp dụng thêm các hạn chế.

Xem lại quyền GitHub và chọn Authorize Atoms-Agents.

Tạo kho lưu trữ riêng tư

Sau khi ủy quyền tài khoản GitHub của bạn, hãy tạo kho lưu trữ riêng tư sẽ lưu mã dự án của bạn.

1. Trong Connected Account, kiểm tra rằng tên người dùng hiển thị khớp với tài khoản GitHub bạn muốn dùng.
2. Trong Create New Repository, nhập tên cho kho lưu trữ. Tên phải:
   • chứa từ 1–100 ký tự;
   • chỉ dùng chữ cái, số, dấu gạch nối (-), dấu gạch dưới (_) hoặc dấu chấm (.).
3. Chọn Create.
4. Chờ thông báo GitHub repository connected successfully!.

Atoms tạo một kho lưu trữ riêng tư mới trong tài khoản GitHub cá nhân của người dùng đã kết nối, liên kết kho đó với dự án Atoms hiện tại, rồi cố gắng tải các tệp hiện tại của dự án lên GitHub.

Nhập tên và tạo một kho lưu trữ riêng tư mới.

Kiểm tra kết nối đã hoạt động

Kiểm tra kết nối trong cả Atoms và GitHub trước khi dựa vào kho lưu trữ này.

1. Trong Atoms, xác nhận rằng Repository Status hiển thị Connected.
2. Trong Branches, kiểm tra rằng một nhánh có dấu chọn. Đây là nhánh hiện đang được kết nối với dự án Atoms của bạn. Nếu bạn mới dùng GitHub, hãy giữ nguyên nhánh này được chọn.
3. Chọn View on GitHub.
4. Trong GitHub, xác nhận rằng kho lưu trữ:
   • thuộc đúng tài khoản GitHub;
   • được đánh dấu là Private;
   • chứa các tệp dự án như mong đợi; và
   • có ít nhất một commit.

Nếu kho lưu trữ trống và Push Changes khả dụng trong Atoms, hãy chọn nó và chờ thao tác hoàn tất. Sau đó làm mới trang kho lưu trữ trong GitHub và kiểm tra rằng các tệp dự án hiện đã xuất hiện.

Kiểm tra kho lưu trữ đã kết nối và nhánh đã chọn trong Atoms.

Xác minh kho lưu trữ riêng tư và các tệp dự án trong GitHub.

Giữ Atoms và GitHub đồng bộ

Atoms và GitHub không tự động đồng bộ. Khi có thay đổi được thực hiện ở một bên, hãy dùng các điều khiển đồng bộ hóa để chuyển những thay đổi đó sang bên còn lại.

Thao tác	Dùng khi	Điều gì xảy ra
Push Changes	Bạn đã thực hiện thay đổi trong Atoms và muốn gửi chúng sang GitHub.	Atoms gửi các tệp dự án hiện tại đến nhánh GitHub đã chọn.
Pull Updates	Các thay đổi đã được thực hiện trên nhánh đã chọn trong GitHub và bạn muốn đưa chúng vào Atoms.	Atoms cập nhật dự án với những thay đổi mới nhất từ GitHub.

Trước khi đẩy hoặc kéo thay đổi, hãy chờ Agent hoàn tất và đảm bảo rằng bạn đang xem phiên bản mới nhất của dự án trong Chat. Nếu bạn đã mở một phiên bản cũ hơn từ History, hãy quay lại thẻ phiên bản mới nhất ở cuối Chat, rồi mở lại GitHub.

Nếu bạn không ở phiên bản mới nhất, Atoms sẽ hiển thị You must be on the latest version to pull updates or push changes.

Trước khi đồng bộ hóa, cũng hãy kiểm tra rằng nhánh đã chọn là nhánh bạn muốn cập nhật.

Nếu cả Atoms và GitHub đều chứa những thay đổi mà bạn cần giữ lại, đừng đồng bộ chúng ngay. Hãy lưu một bản sao của phần công việc quan trọng trước hoặc nhờ người quen thuộc với GitHub bảo toàn các thay đổi trên một nhánh riêng.

Nếu Repository Status hiển thị Upstream Changes Available, GitHub đang chứa các thay đổi mà Atoms chưa có. Hãy xem lại kho lưu trữ trước khi chọn một thao tác.

Dùng Pull Updates và Push Changes cho nhánh đã chọn.

Đẩy thay đổi từ Atoms sang GitHub

1. Hoàn tất việc thay đổi trong Atoms và chờ Agent ngừng làm việc.
2. Đảm bảo rằng bạn đang xem phiên bản mới nhất của dự án.
3. Mở Settings → Connectors → GitHub và kiểm tra rằng nhánh đúng đã được chọn.
4. Chọn Push Changes.
5. Giữ trang mở trong khi các thay đổi đang được đẩy lên.
6. Khi Changes pushed successfully xuất hiện, hãy chọn View on GitHub và kiểm tra rằng các tệp dự án mới nhất có ở đó.

Push Changes chỉ khả dụng khi Atoms có các thay đổi chưa được gửi đến GitHub. Tùy chọn này sẽ không khả dụng khi Agent đang làm việc hoặc khi bạn đang xem một phiên bản cũ hơn của dự án.

Khi bạn chọn Push Changes, các thay đổi sẽ được gửi đến GitHub ngay lập tức mà không yêu cầu xác nhận. Nếu cùng một tệp đã được thay đổi ở cả Atoms và GitHub, phiên bản trong Atoms sẽ được ưu tiên và sẽ ghi đè phiên bản hiện đang được lưu trong GitHub.

Kéo cập nhật từ GitHub vào Atoms

Không giống như đẩy thay đổi, kéo thay đổi yêu cầu xác nhận trước. Nếu cùng một tệp đã được thay đổi ở cả GitHub và Atoms, phiên bản GitHub sẽ được ưu tiên và sẽ ghi đè phiên bản hiện tại trong Atoms.

1. Mở Settings → Connectors → GitHub.
2. Kiểm tra rằng Repository Status hiển thị các thay đổi mới từ GitHub và nhánh đúng đã được chọn.
3. Chọn Pull Updates.
4. Đọc cảnh báo Pull May Affect Project. Nếu bạn muốn đưa các thay đổi từ GitHub vào dự án Atoms hiện tại của mình, hãy chọn Confirm.
5. Giữ trang mở trong khi các thay đổi đang được kéo về.
6. Khi Changes pulled successfully xuất hiện, hãy mở Trình xem App và kiểm tra các phần của dự án bị ảnh hưởng bởi các thay đổi để đảm bảo mọi thứ vẫn hoạt động như mong đợi.

Pull Updates chỉ khả dụng khi nhánh GitHub đã chọn chứa các thay đổi chưa được đưa vào Atoms.

Ngắt kết nối GitHub

Ngắt kết nối GitHub khi bạn không còn muốn Atoms truy cập tài khoản đã kết nối nữa. Kho lưu trữ GitHub và các tệp của nó vẫn sẽ còn trong GitHub, nhưng Atoms sẽ không còn có thể đẩy hoặc kéo thay đổi.

Ủy quyền GitHub áp dụng cho tài khoản đã kết nối. Việc thu hồi quyền truy cập sẽ ngắt kết nối mọi dự án Atoms đang dùng tài khoản GitHub đó, vì vậy hãy kiểm tra các dự án khác của bạn trước khi tiếp tục.

1. Mở Settings → Connectors → GitHub.
2. Chọn Disconnect.
3. Trong phần xác nhận Disconnect GitHub, chọn Disconnect một lần nữa.
4. GitHub sẽ tự động mở trang ủy quyền liên quan. Nếu không, trong GitHub hãy vào Settings → Applications → Authorized OAuth Apps.
5. Tìm Atoms, chọn ... ở bên phải hàng của ứng dụng đó, rồi chọn Revoke. Không chọn Revoke all; thao tác đó sẽ xóa quyền truy cập của mọi ứng dụng OAuth đã được ủy quyền được liệt kê trên trang.
6. Thực hiện mọi bước xác nhận cần thiết từ Github.
7. Quay lại Atoms và mở lại trình kết nối GitHub để xác nhận rằng tài khoản không còn được kết nối nữa.

Chọn Disconnect trong trình kết nối GitHub.

Chỉ thu hồi ứng dụng OAuth Atoms trong GitHub.