Доступ к Git-репозиторию проекта
Краткий обзор
- Находите URL-адреса репозиториев аппаратных и программных проектов и используйте их в том виде, в котором их возвращает API.
- Выполняйте аутентификацию для операций Git с помощью токена доступа к рабочему пространству и безопасно храните учётные данные.
- Клонируйте репозитории, создавайте коммиты и отправляйте изменения, в том числе в ветку `master`, чтобы платформа могла их обработать. При этом избегайте добавления больших архивов, которые не поддерживаются.
Altium 365 позволяет размещать Git-репозиторий с исходными файлами вашего проекта. Altium Designer работает с такими репозиториями как нативный клиент, но вы также можете работать с ними как с любым другим удалённым Git-репозиторием — clone, pull, push и т. д. с помощью стандартного клиента Git.
На этой странице описано, как:
-
Получить URL репозитория проекта через API Altium 365.
-
Аутентифицировать запросы Git с помощью токена доступа Altium 365.
-
Работать с Git-репозиторием
Шаг 1. Получение URL репозитория
Сведения о репозитории доступны через API Altium 365. Запросите список проектов, прочитайте поле repositoryUrl и используйте его значение в качестве адреса удалённого Git-репозитория.
Сведения о получении и использовании токенов Altium 365 см. в разделе Токены. Если вы ещё не знакомы с API, начните с Краткого руководства по началу работы с API Altium 365.
Аппаратные проекты
Для аппаратных проектов (печатных плат) поля репозитория доступны через desProjects:
query {
desProjects {
nodes {
repositoryUrl
}
}
}
Программные проекты
Для программных проектов те же поля доступны через sftSoftwareProjects:
query {
sftSoftwareProjects {
repositoryUrl
}
}
Поля ответа
Оба запроса возвращают одинаковые поля репозитория:
| Ваше приложение | Описание |
repositoryUrl |
URL удалённого Git-репозитория. Считайте его непрозрачным значением: запрашивайте через API и используйте без изменений. |
Пример ответа для аппаратного проекта:
{
"data": {
"desProjects": {
"nodes": [
{
"repositoryUrl": "{repositoryUrl}"
}
]
}
}
}
Шаг 2. Аутентификация
Git-репозитории Altium 365 используют базовую аутентификацию. В качестве пароля используйте access token API Altium 365. Токен должен быть выдан для рабочего пространства, которому принадлежит проект.
Значение username is ignored сервером, но должно быть непустой строкой. Подойдёт любое условное значение (например: token).
Заголовок Authorization
При межсервисных вызовах передавайте учётные данные в заголовке Authorization в кодировке base64 в формате username:password:
Authorization: Basic base64("token:{access-token}")
Командная строка Git
Клонируйте репозиторий, используя repositoryUrl, возвращённый API. При появлении запроса введите любое непустое имя пользователя, а в качестве пароля — свой токен доступа:
git clone {repositoryUrl}
# Username: "token" (any non-empty value)
# Password: {access-token}
Настройте помощник по работе с учётными данными Git, чтобы токен хранился безопасно и вам не приходилось вводить его при каждой операции. Доступные помощники зависят от платформы (например, osxkeychain в macOS, manager в Windows):
git config --global credential.helper osxkeychain
Учётные данные в URL репозитория
Вместо ввода по запросу можно передавать учётные данные в компоненте authority URL — Altium 365 поддерживает стандартный синтаксис 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 для клонирования, чтобы он не сохранялся в
.git/configили истории командной оболочки. -
Используйте короткоживущие токены для автоматизации. Для CI/CD и фоновых служб получайте короткоживущий токен доступа с помощью токена обновления, чтобы ограничить время, в течение которого учётные данные, передаваемые с каждым запросом, могут быть использованы при компрометации. См. Использование токена обновления.
Ограничения
Чтобы репозиторий проекта работал быстро и надёжно, Git-сервер отклоняет большие сжатые архивы: файлы .zip, .7z и .rar размером более 256 МБ. Отправка, содержащая такой файл, отклоняется:
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
См. База знаний: не удаётся сохранить проект из-за ошибки Git с кодом состояния 471 для получения подробной информации об этой ошибке в Altium Designer.