Перейти к основному содержимому
Открыть Markdown

Файлы и Git

Файловая система песочницы — общее рабочее пространство для браузерных изменений, команд, компонентов подготовки и Git. Для непосредственного просмотра используйте вкладку Файлы, для автоматизации — REST API файлов, а после клонирования запускайте обычные Git-команды.

Выбор интерфейса​

ЗадачаИнтерфейс
Просмотреть директорию или файлВкладка Файлы или REST API файлов
Немного изменить текст или MarkdownВкладка Файлы
Передать сгенерированные или бинарные данныеREST API файлов
Выполнить git status, pull, commit или pushТерминал или /exec
Начать с готовой рабочей копииrepo при создании песочницы или сохраненный секрет типа repo
Хранить данные независимо от одной песочницыХранилище

Файлы являются частью корневой файловой системы песочницы. Остановка и гибернация сохраняют эту файловую систему, удаление — нет. Хранилище аккаунта — отдельный сервис со своими правами доступа и жизненным циклом.

Работа через веб-интерфейс​

Откройте активную песочницу и выберите Файлы. Дерево начинается с / и раскрывает рабочую директорию шаблона. С помощью панели инструментов или перетаскивания в директорию можно:

  • загрузить один или несколько файлов;
  • создать директорию;
  • переименовать или переместить выбранный объект;
  • рекурсивно удалить выбранную директорию или удалить файл;
  • скачать выбранный файл;
  • просмотреть изображения и Markdown, изучить код и отредактировать текстовые файлы.

Окно просмотра проверяет изменения на диске в фоне, но сохраняет показанную копию до нажатия Перезагрузить. Сохранение правки перезаписывает целевой файл. Бинарные файлы передаются как base64 и не открываются в текстовом редакторе.

Вкладка «Файлы» — привилегированный файловый браузер

Она показывает файловую систему песочницы, а не только директорию проекта. Права доступа Unix продолжают действовать. Не меняйте системные файлы без явной необходимости и не выводите файлы с учетными данными, например ~/.gitconfig.

Автоматизация файловых операций​

Всем эндпоинтам нужен ID песочницы и bearer-токен. Путь может быть абсолютным, относительным к домашней директории (~/) настроенного пользователя по умолчанию или относительным к рабочей директории по умолчанию.

ОперацияЗапрос
Прочитать файлGET /v1/sandboxes/{id}/files?path=...
Записать или заменить файлPOST /v1/sandboxes/{id}/files
Загрузить multipart-файлы в директориюPOST /v1/sandboxes/{id}/files/upload?path=...
Скачать сырые байтыGET /v1/sandboxes/{id}/files/download?path=...
Получить содержимое директорииGET /v1/sandboxes/{id}/files/list?path=...&depth=...
Получить свойства одного объектаGET /v1/sandboxes/{id}/files/stat?path=...
Создать директорииPOST /v1/sandboxes/{id}/files/mkdir
Переместить или переименоватьPOST /v1/sandboxes/{id}/files/move
Удалить файл или дерево директорийDELETE /v1/sandboxes/{id}/files?path=...

Запишите текстовый файл и прочитайте его:

curl --fail-with-body --silent --show-error \
--request POST "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID/files" \
--header "Authorization: Bearer $JUSTRUN_PAT" \
--header "Content-Type: application/json" \
--data '{
"path": "~/workspace/config.json",
"content": "{\"mode\":\"development\"}\n",
"overwrite": true
}'

curl --fail-with-body --silent --show-error \
--get "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID/files" \
--header "Authorization: Bearer $JUSTRUN_PAT" \
--data-urlencode "path=~/workspace/config.json" |
jq

Ответ чтения содержит encoding: "utf-8" для текста и encoding: "base64" для распознанного бинарного содержимого. При записи бинарных данных передайте base64-строку и укажите "encoding": "base64".

Новые файлы создаются с правами 0644, а недостающие родительские директории — автоматически. Укажите overwrite: false, если замена существующего файла должна завершаться ошибкой. Запись идет во временный соседний файл, который переименовывается после получения всего содержимого запроса; сервис не пишет через символическую ссылку и не заменяет ее.

Лимит тела HTTP-запроса настраивается в инсталляции и по умолчанию равен 20 МиБ. Внутренний файловый сервис может задавать дополнительный лимит загрузки. Превышение любого из них — 413 request.payload_too_large, и это означает, что не записано ничего: незавершенная загрузка отменяется, прежнее содержимое файла остается нетронутым. Для больших долговечных артефактов используйте хранилище, а не файловую систему песочницы как объектное хранилище.

Клонирование репозитория при создании​

Собственный API создания принимает один высокоуровневый объект repo:

{
"template": "base",
"repo": {
"url": "https://github.com/acme/service.git",
"ref": "main",
"path": "~/service",
"depth": 1,
"required": true
},
"wait_until_ready": true
}

url должен использовать https:// или ssh://. Необязательный путь назначения начинается с ~/, не может содержать .. и по умолчанию равен ~/<repository-name>. ref превращается в git clone --branch, а depth включает клонирование с неполной историей.

Клонирование — шаг подготовки, а не часть загрузки VM. Песочница уже может показывать running, пока provisioning.status остается in_progress. wait_until_ready: true заставляет запрос создания ждать завершения подготовки; иначе опрашивайте песочницу до ready или failed.

По умолчанию клонирование считается обязательным. Его ошибка переводит песочницу в failed; у подготовки V1 нет действия повтора, поэтому исправьте причину и создайте песочницу заново. При required: false шаг клонирования может завершиться ошибкой, а песочница останется доступной.

Аутентификация приватных репозиториев​

Не добавляйте токен в URL репозитория. Создайте секрет типа git_credential для HTTPS или секрет типа ssh_key для SSH URL, затем выберите секрет при создании песочницы. Сохраненный секрет типа repo может ссылаться по имени на соответствующий секрет git_credential.

Учетные данные HTTPS материализуются в помощник учетных данных Git, доступный только владельцу, внутри ~/.gitconfig пользователя по умолчанию. SSH-ключи помещаются в ~/.ssh этого пользователя. Клонирование запускается неинтерактивно от того же пользователя, поэтому отсутствующие учетные данные или неверный доступ приводят к ошибке, а не к зависшему запросу ввода.

После подготовки используется Git из выбранного шаблона:

curl --fail-with-body --silent --show-error \
--request POST "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID/exec" \
--header "Authorization: Bearer $JUSTRUN_PAT" \
--header "Content-Type: application/json" \
--data '{
"cmd": "git",
"args": ["-C", "/home/user/service", "status", "--short"]
}' |
jq '{exit_code, stdout, stderr}'

Отдельного REST API для команд git status, pull, commit или push нет. Используйте Терминал, если Git нужен интерактивный ввод, и /exec для детерминированной автоматизации. Считайте push внешним побочным эффектом и выдавайте учетным данным репозитория только необходимые права на рабочие процессы.

Границы ошибок​

  • Файловым операциям нужна активная среда выполнения. Сначала возобновите или разбудите песочницу.
  • Ответы чтения буферизуют целый файл. Для крупных файлов используйте скачивание сырых байтов или хранилище.
  • Удаление директории рекурсивно, а публичного API для отмены нет.
  • Путь клонирования принадлежит пользователю по умолчанию. Git, запущенный от другого Unix-пользователя, может не увидеть те же учетные данные в домашней директории или из-за владельца файлов.
  • Остановка сохраняет рабочее дерево, но завершает процессы Git; гибернация сохраняет память, однако удаленные сетевые соединения нужно устанавливать заново.
  • Не выводите значения секретов, помощников учетных данных, приватных ключей или URL удаленных репозиториев с аутентификацией в логи и пакеты данных для поддержки.