Projekt-Git-Zugriff

Altium 365 kann ein Git-Repository für die Quelldateien Ihres Projekts hosten. Altium Designer arbeitet mit diesen Repositories als nativer Client, Sie können aber auch wie mit jedem anderen Git-Remote damit arbeiten — clone, pull, push usw. mit dem standardmäßigen Git-Client.

Diese Seite zeigt, wie Sie:

1. die Repository-URL eines Projekts über die Altium 365 API ermitteln.

2. Git-Anfragen mithilfe eines Altium 365-Zugriffstokens authentifizieren.

3. Mit dem Git-Repository arbeiten

Schritt 1: Repository-URL abrufen

Repository-Details werden über die Altium 365 API bereitgestellt. Fragen Sie Ihre Projekte ab, lesen Sie das Feld repositoryUrl aus und verwenden Sie es als Ihr Git-Remote. 

Siehe Tokens für Details zum Abrufen und Verwenden von Altium 365-Tokens. Wenn Sie neu bei der API sind, beginnen Sie mit dem Altium 365 API Quick Start Guide.

Hardwareprojekte

Hardwareprojekte (PCB) stellen die Repository-Felder über desProjectsbereit:

query {
  desProjects {
    nodes {
      repositoryUrl
    }
  }
}

Softwareprojekte

Softwareprojekte stellen dieselben Felder über sftSoftwareProjectsbereit:

query {
  sftSoftwareProjects {
    repositoryUrl
  }
}

Antwortfelder

Beide Abfragen geben dieselben Repository-Felder zurück:

Zum Beispiel eine Antwort für ein Hardwareprojekt:

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

Schritt 2: Authentifizierung

Altium 365 Git-Repositories authentifizieren mit basic authentication. Verwenden Sie Ihr Altium 365 API access token als Passwort. Das Token muss für den Workspace ausgestellt sein, dem das Projekt gehört.

Der username is ignored wird vom Server ignoriert, muss aber eine nicht leere Zeichenfolge sein. Jeder Platzhalter (zum Beispiel: token) funktioniert.

Authorization-Header

Für Service-zu-Service-Aufrufe übergeben Sie die Anmeldedaten im Header Authorization, Base64-kodiert als username:password:

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

Git-Befehlszeile

Klonen Sie mit der repositoryUrl , die von der API zurückgegeben wurde. Wenn Sie dazu aufgefordert werden, geben Sie einen beliebigen nicht leeren Benutzernamen und Ihr Zugriffstoken als Passwort ein:

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

Konfigurieren Sie einen Git credential helper, damit das Token sicher gespeichert wird und Sie nicht bei jedem Vorgang dazu aufgefordert werden. Die verfügbaren Helper variieren je nach Plattform (zum Beispiel osxkeychain unter macOS, manager unter Windows):

git config --global credential.helper osxkeychain

Anmeldedaten in der Repository-URL

Als Alternative zur Eingabeaufforderung akzeptiert Altium 365 Anmeldedaten in der authority component der URL — der standardmäßigen URI- username:password@ Syntax. Die API gibt niemals eine URL mit bereits eingetragenen Anmeldedaten zurück, daher konstruieren Sie diese Form selbst: Nehmen Sie die zurückgegebene repositoryUrl und fügen Sie {username}:{access-token}@ unmittelbar nach https:// ein.

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

Der Benutzername wird ignoriert (jeder nicht leere Wert); das Passwort ist dasselbe Zugriffstoken (JWT), das auch in den oben genannten Methoden verwendet wird.

Schritt 3: Mit dem Repository arbeiten

Nach dem Klonen verhält sich das Repository wie jedes standardmäßige Git-Remote:

cd <your-repository>

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

Ein ungültiges oder abgelaufenes Zugriffstoken führt dazu, dass Git-Operationen mit einem Authentifizierungsfehler fehlschlagen:

git clone {repositoryUrl}
# provide credentials when prompted

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

Sicherheit

• Behandeln Sie das Zugriffstoken wie ein Passwort. Speichern Sie es weder in der Versionsverwaltung noch betten Sie es in clientseitigen Code ein.

• Bevorzugen Sie einen Credential Helper statt das Token in die Clone-URL einzubetten, damit es nicht in .git/config oder im Verlauf Ihrer Shell gespeichert wird.

• Verwenden Sie kurzlebige Tokens für die Automatisierung. Für CI/CD und Hintergrunddienste sollten Sie ein kurzlebiges Zugriffstoken aus einem Refresh-Token beziehen, damit die Anmeldedaten, die mit jeder Anfrage übertragen werden, nur ein begrenztes Expositionsfenster haben. Siehe Using a Refresh Token.

Beschränkungen

Damit das Projekt-Repository schnell und zuverlässig bleibt, lehnt der Git-Server große komprimierte Archive ab: .zip, .7z und .rar Dateien, die größer als 256 MB sind. Ein Push, der eine solche Datei enthält, wird abgelehnt:

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

Siehe KB: Cannot save project due to Git error with status code 471 für Details zu diesem Fehler im Kontext von Altium Designer.

Siehe auch

• Altium 365 API Quick Start Guide

• Tokens