Quyền truy cập Git của dự án

Altium 365 có thể lưu trữ một kho Git cho các tệp mã nguồn của dự án bạn. Altium Designer làm việc với các kho này như một ứng dụng khách gốc, nhưng bạn cũng có thể làm việc với chúng như với bất kỳ Git remote nào khác — clone, pull, push, v.v. bằng ứng dụng khách Git tiêu chuẩn.

Trang này trình bày cách:

1. Tìm URL kho lưu trữ của một dự án thông qua API Altium 365.

2. Xác thực các yêu cầu Git bằng access token của Altium 365.

3. Làm việc với kho Git

Bước 1: Lấy URL Kho lưu trữ

Chi tiết kho lưu trữ được cung cấp thông qua API Altium 365. Truy vấn các dự án của bạn, đọc trường repositoryUrl và dùng nó làm Git remote của bạn. 

Xem Tokens để biết chi tiết về cách lấy và sử dụng token Altium 365. Nếu bạn mới dùng API, hãy bắt đầu với Altium 365 API Quick Start Guide.

Dự án phần cứng

Các dự án phần cứng (PCB) cung cấp các trường kho lưu trữ thông qua desProjects:

query {
  desProjects {
    nodes {
      repositoryUrl
    }
  }
}

Dự án phần mềm

Các dự án phần mềm cung cấp cùng các trường thông qua sftSoftwareProjects:

query {
  sftSoftwareProjects {
    repositoryUrl
  }
}

Các trường phản hồi

Cả hai truy vấn đều trả về cùng các trường kho lưu trữ:

Ví dụ, phản hồi của một dự án phần cứng:

{
  "data": {
    "desProjects": {
      "nodes": [
        {
          "repositoryUrl": "{repositoryUrl}"
        }
      ]
    }
  }
}

Bước 2: Xác thực

Các kho Git của Altium 365 xác thực bằng xác thực cơ bản. Sử dụng API access token của Altium 365 làm mật khẩu. Token phải được cấp cho Workspace sở hữu dự án.

username is ignored được máy chủ bỏ qua nhưng phải là một chuỗi không rỗng. Bất kỳ giá trị giữ chỗ nào (ví dụ: token) đều dùng được.

Header Authorization

Đối với các lệnh gọi service-to-service, truyền thông tin xác thực trong header Authorization , được mã hóa base64 theo dạng username:password:

Authorization: Basic base64("token:{access-token}")

Dòng lệnh Git

Clone bằng repositoryUrl được API trả về. Khi được nhắc, nhập bất kỳ tên người dùng không rỗng nào và access token của bạn làm mật khẩu:

git clone {repositoryUrl}
# Username: "token" (any non-empty value)
# Password: {access-token}

Cấu hình một Git credential helper để token được lưu trữ an toàn và bạn không bị yêu cầu nhập lại ở mỗi thao tác. Các helper khả dụng sẽ khác nhau tùy nền tảng (ví dụ osxkeychain trên macOS, manager trên Windows):

git config --global credential.helper osxkeychain

Thông tin xác thực trong URL kho lưu trữ

Thay vì dùng lời nhắc nhập, Altium 365 chấp nhận thông tin xác thực trong thành phần authority của URL — cú pháp URI username:password@ tiêu chuẩn. API không bao giờ trả về URL đã điền sẵn thông tin xác thực, nên bạn phải tự tạo dạng này: lấy repositoryUrl được trả về và chèn {username}:{access-token}@ ngay sau https://.

git clone https://token:{access-token}@<returned-url>
# <returned-url> is the repositoryUrl with the leading "https://" removed

Tên người dùng sẽ bị bỏ qua (chỉ cần là giá trị không rỗng bất kỳ); mật khẩu là cùng access token (JWT) được dùng trong các phương thức ở trên.

Bước 3: Làm việc với Kho lưu trữ

Sau khi clone, kho lưu trữ hoạt động như bất kỳ Git remote tiêu chuẩn nào:

cd <your-repository>

# Make changes, then push as usual
git add .
git commit -m "Update firmware sources"
git push

Access token không hợp lệ hoặc đã hết hạn sẽ khiến các thao tác Git thất bại với lỗi xác thực:

git clone {repositoryUrl}
# provide credentials when prompted

Cloning into '<your-repository>'...
bad input: 07KCg
fatal: Authentication failed for '{repositoryUrl}'

Bảo mật

• Hãy coi access token như một mật khẩu. Không commit nó vào hệ thống quản lý mã nguồn hoặc nhúng nó vào mã phía client.

• Ưu tiên dùng credential helper thay vì nhúng token vào URL clone, để token không bị ghi vào .git/config hoặc lịch sử shell của bạn.

• Sử dụng token có thời hạn ngắn cho tự động hóa. Đối với CI/CD và các dịch vụ chạy nền, hãy lấy access token có thời hạn ngắn từ refresh token để thông tin xác thực đi kèm mỗi yêu cầu chỉ có khoảng thời gian phơi lộ giới hạn. Xem Using a Refresh Token.

Giới hạn

Để giữ cho kho lưu trữ của dự án nhanh và đáng tin cậy, máy chủ Git từ chối các tệp lưu trữ nén lớn: .zip, .7z và .rar có kích thước lớn hơn 256 MB. Một lệnh push có chứa tệp như vậy sẽ bị từ chối:

git push

Enumerating objects: 4, done.
Counting objects: 100% (4/4), done.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 282.56 MiB | 1.09 MiB/s, done.
Total 3 (delta 1), reused 0 (delta 0), pack-reused 0
error: RPC failed; HTTP 471 curl 22 The requested URL returned error: 471
send-pack: unexpected disconnect while reading sideband packet
fatal: the remote end hung up unexpectedly
Everything up-to-date

Xem KB: Cannot save project due to Git error with status code 471 để biết chi tiết về lỗi này trong ngữ cảnh Altium Designer.

Xem thêm

• Altium 365 API Quick Start Guide

• Tokens