프로젝트 Git 액세스

Altium 365는 프로젝트의 소스 파일을 위한 Git 리포지토리를 호스팅할 수 있습니다. Altium Designer는 이러한 리포지토리와 네이티브 클라이언트로 작동하지만, 표준 Git 클라이언트를 사용해 다른 Git 원격 저장소처럼 — clone, pull, push 등으로도 작업할 수 있습니다.

이 페이지에서는 다음 내용을 설명합니다:

1. Altium 365 API를 통해 프로젝트의 리포지토리 URL 확인

2. Altium 365 액세스 토큰을 사용한 Git 요청 인증

3. Git 리포지토리 작업

1단계: 리포지토리 URL 가져오기

리포지토리 세부 정보는 Altium 365 API를 통해 제공됩니다. 프로젝트를 조회하고 repositoryUrl 필드를 읽은 다음, 이를 Git 원격 저장소로 사용하십시오. 

See Tokens 에서 Altium 365 토큰의 획득 및 사용 방법에 대한 자세한 내용을 확인하십시오. API가 처음이라면 Altium 365 API Quick Start Guide부터 시작하십시오.

하드웨어 프로젝트

하드웨어(PCB) 프로젝트는 리포지토리 필드를 desProjects를 통해 제공합니다:

query {
  desProjects {
    nodes {
      repositoryUrl
    }
  }
}

소프트웨어 프로젝트

소프트웨어 프로젝트는 동일한 필드를 sftSoftwareProjects를 통해 제공합니다:

query {
  sftSoftwareProjects {
    repositoryUrl
  }
}

응답 필드

두 쿼리 모두 동일한 리포지토리 필드를 반환합니다:

예를 들어, 하드웨어 프로젝트 응답은 다음과 같습니다:

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

2단계: 인증

Altium 365 Git 리포지토리는 기본 인증을 사용합니다. Altium 365 API access token 를 비밀번호로 사용하십시오. 이 토큰은 프로젝트를 소유한 Workspace용으로 발급된 것이어야 합니다.

username is ignored 는 서버에서 무시되지만 비어 있지 않은 문자열이어야 합니다. 아무 플레이스홀더(예: token)나 사용할 수 있습니다.

Authorization 헤더

서비스 간 호출의 경우, 자격 증명을 Authorization 헤더에 전달하고, 이를 username:password 형식으로 base64 인코딩하십시오:

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

Git 명령줄

API가 반환한 repositoryUrl 를 사용해 클론하십시오. 프롬프트가 표시되면 비어 있지 않은 아무 사용자 이름과 액세스 토큰을 비밀번호로 입력하십시오:

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

Git credential helper를 구성하면 토큰이 안전하게 저장되고 모든 작업마다 다시 묻지 않게 됩니다. 사용 가능한 helper는 플랫폼에 따라 다릅니다(예: osxkeychain macOS에서는, manager Windows에서는):

git config --global credential.helper osxkeychain

리포지토리 URL의 자격 증명

프롬프트를 사용하는 대신, Altium 365는 URL의 authority component에 포함된 자격 증명도 허용합니다 — 이는 표준 URI username:password@ 구문입니다. API는 자격 증명이 미리 채워진 URL을 절대 반환하지 않으므로, 이 형식은 직접 구성해야 합니다: 반환된 repositoryUrl 를 가져와 {username}:{access-token}@ 를 https:// 바로 뒤에 삽입하십시오.

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

사용자 이름은 무시되며(비어 있지 않은 아무 값이나 가능), 비밀번호는 위 방법들에서 사용한 것과 동일한 액세스 토큰(JWT)입니다.

3단계: 리포지토리 작업

클론이 완료되면 이 리포지토리는 다른 표준 Git 원격 저장소처럼 동작합니다:

cd <your-repository>

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

잘못되었거나 만료된 액세스 토큰을 사용하면 Git 작업이 인증 오류와 함께 실패합니다:

git clone {repositoryUrl}
# provide credentials when prompted

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

보안

• 액세스 토큰은 비밀번호처럼 취급하십시오. 소스 제어에 커밋하거나 클라이언트 측 코드에 포함하지 마십시오.

• 클론 URL에 토큰을 포함하는 대신 credential helper를 사용하는 것이 좋습니다. 이렇게 하면 토큰이 .git/config 또는 셸 히스토리에 기록되지 않습니다.

• 자동화에는 수명이 짧은 토큰을 사용하십시오. CI/CD 및 백그라운드 서비스의 경우, refresh token으로부터 수명이 짧은 액세스 토큰을 받아 각 요청과 함께 전달되는 자격 증명의 노출 시간을 제한하십시오. 자세한 내용은 Using a Refresh Token을 참조하십시오.

제한 사항

프로젝트 리포지토리를 빠르고 안정적으로 유지하기 위해 Git 서버는 대용량 압축 아카이브를 거부합니다: .zip, .7z, .rar 파일이 256MB를 초과하면 안 됩니다. 이러한 파일이 포함된 푸시는 거부됩니다:

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

Altium Designer 환경에서 이 오류에 대한 자세한 내용은 KB: Cannot save project due to Git error with status code 471 를 참조하십시오.

추가 참조

• Altium 365 API Quick Start Guide

• Tokens