プロジェクト Git アクセス

Altium 365 は、プロジェクトのソースファイル用 Git リポジトリをホストできます。Altium Designer はこれらのリポジトリに対して native client として動作しますが、標準の 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 リポジトリは、 basic authentication を使用して認証します。パスワードとして 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 はプラットフォームによって異なります（たとえば macOS では osxkeychain、Windows では manager）:

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 やバックグラウンドサービスでは、リフレッシュトークンから短命なアクセストークンを取得し、各リクエストで使用される資格情報の露出期間を限定してください。詳細は Using a Refresh Token を参照してください。

制限

プロジェクト リポジトリを高速かつ安定して維持するため、Git サーバーは大きな圧縮アーカイブを拒否します: .zip、.7z、および .rar で、256 MB を超えるファイルです。これらのファイルを含む push は拒否されます:

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