#Управление репозиториями и артефактами

#Контекст

CodeScoring.Save хранит и раздаёт артефакты для команды разработки: сборщик публикует пакет, а IDE, CI-агенты и пользователи скачивают его по тому же URL, не выходя за периметр компании.

Все артефакты лежат в репозиториях, репозитории сгруппированы в проекты. Это та же иерархия, что и в интерфейсе:

Проект — это контейнер, в котором живут репозитории команды. Репозиторий — конкретное хранилище одного формата (Maven, npm, Docker и т.д.) одного из двух типов. Артефакт — то, что в нём лежит и что качают клиенты.

#Два типа репозиториев

CodeScoring.Save поддерживает только два типа репозиториев, и каждый решает свою задачу.

Proxy-репозиторий — кэширующий прокси к внешнему источнику (например, Maven Central или npmjs.com). Когда клиент впервые запрашивает артефакт, Save качает его из upstream, кэширует и отдаёт. Все последующие запросы идут уже из кэша — это ускоряет сборки и снижает зависимость от внешних сервисов. На proxy-репозитории дополнительно работают политики безопасности OSA Proxy (если он настроен), которые могут заблокировать скачивание небезопасных компонентов.

Hosted-репозиторий — собственное хранилище, в которое команда публикует свои артефакты. Сюда попадают внутренние библиотеки, проверенные сторонние компоненты и build-artifacts.

В одном проекте может быть произвольное количество репозиториев обоих типов.

#URL-схема доступа

Внешний клиент (Maven, npm, Docker и т.д.) обращается к репозиторию по URL вида:

https://save.example.com/cs-save/<format>/<project>/<repository>/<artifact-path>

Для OCI / Docker используется стандартный префикс /v2/, как требует OCI Distribution Spec. Дополнительно поддерживается Nexus-совместимая маршрутизация плоских URL — см. Работа с OCI / Docker.

#Структура веб-интерфейса

Слева расположена вертикальная навигация со следующими разделами:

• Projects — основной раздел: список проектов, внутри каждого — список репозиториев, внутри каждого репозитория — дерево артефактов;
• Cleanup — политики автоматической очистки ненужных артефактов;
• Settings — управление учётными записями, ролями, сервисными аккаунтами, конфигурацией, ключом активации и журналом аудита.

В верхней части интерфейса находится глобальный поиск — открывается по клавише / и ищет одновременно по проектам, репозиториям и артефактам с подсказками в реальном времени.

#Базовый сценарий: подключить свой первый репозиторий

#Шаг 1. Создайте проект

Проект — это контейнер, в котором будут жить репозитории. Удобно делить проекты по командам, продуктам или окружениям.

1. В боковом меню выберите Projects.
2. Нажмите кнопку Create project в правом верхнем углу.
3. Заполните форму:
   • Name — человеко-читаемое название проекта (например, Backend Team);
   • Color — цвет для визуального различения проектов в списке;
   • Key — URL-safe идентификатор проекта (например, backend-team). Если оставить пустым, будет сгенерирован автоматически из Name, даже если Name не использует латиницу. Изменить Key после создания нельзя;
   • Description — необязательное описание проекта;
   • Cleanup policy — раздел двухпанельного селектора с уже созданными политиками очистки. Можно оставить пустым и привязать политики позже.
4. Нажмите Create project.

После создания откроется страница проекта со списком репозиториев (пока пустым) и его метаданными в шапке.

#Шаг 2. Создайте репозиторий в проекте

Внутри проекта создаётся репозиторий — конкретное хранилище для артефактов одного формата.

1. Откройте только что созданный проект.

2. Нажмите Create repository в правом верхнем углу страницы проекта.

3. Заполните общие поля:

   • Name — человеко-читаемое название (например, Maven Central (proxy)). Если в названии есть формат и тип (например, npm proxy), ссылка под полем сама заполнит Format, Type и Proxy URL (публичный upstream);
   • Color — цвет для удобства;
   • Key — URL-safe идентификатор (например, maven-central). Изменить после создания нельзя;
   • Description — необязательное описание, до 100 символов.

4. Выберите Format: OCI (Docker / Helm), Maven / Gradle, NPM, NuGet, PyPI, Raw / Generic, Go Modules, Debian / APT, RPM, PHP / Composer или Alpine / APK. После создания формат и тип поменять нельзя.

5. Выберите Type:

   • Proxy — для проксирования внешнего реестра;
   • Hosted — для собственного хранилища.

6. Если выбран тип Proxy, появятся дополнительные поля:

   • Proxy URL — адрес upstream-репозитория (например, https://repo1.maven.org/maven2/);
   • Cache TTL, seconds — время жизни кэша метаданных в секундах. Для типичных внешних реестров достаточно 86400 (сутки).

   В зависимости от формата на форме появляются и специфичные поля — например, Authentication для upstream или RPM metadata folder depth.

7. При необходимости привяжите Cleanup policy — список уже созданных политик автоматической очистки.

8. Нажмите Create repository.

После создания откроется страница репозитория. В шапке отображается статус (Enabled/Disabled), формат, тип, даты создания и обновления, а для proxy-репозитория — кликабельная ссылка Remote URL, ведущая на upstream.

#Шаг 3. Получите готовые сниппеты для подключения клиентов

На странице репозитория в правой части шапки находится кнопка со значком «звено цепи». По клику она открывает popover Useful snippets — набор готовых фрагментов конфигурации и команд, который зависит от формата репозитория.

1. Нажмите кнопку звено цепи в шапке репозитория.
2. В появившейся карточке прокрутите список сниппетов:
   • каждый сниппет состоит из заголовка (например, settings.xml, .npmrc, pip.conf, docker login), блока кода с подсветкой синтаксиса и краткого описания;
   • набор сниппетов формируется на стороне сервера по формату и типу репозитория. Для Maven обычно показывается фрагмент <mirror> для settings.xml и <repository> для pom.xml; для Docker — docker login и docker pull; для npm — строка для .npmrc; и так далее.
3. Нажмите кнопку копирования справа от нужного сниппета — он скопируется в буфер обмена.
4. Вставьте сниппет в конфигурационный файл клиента или выполните команду в терминале.

#Шаг 4. Опубликуйте и скачайте первый артефакт

Дальше всё происходит уже на стороне клиента — Save принимает стандартные запросы пакетного менеджера. Для hosted-репозитория обычный путь — публикация через mvn deploy, npm publish, twine upload или docker push. Для proxy-репозитория — обычный pull, после которого артефакт окажется в кэше Save. Кнопки загрузки в веб-интерфейсе нет: артефакты попадают в репозиторий только через клиенты и HTTP-запросы.

При первой загрузке может потребоваться аутентификация — см. раздел Подключение клиентов и аутентификация.

После того, как клиент впервые что-то загрузит или скачает, артефакт появится в дереве на странице репозитория.

#Работа с артефактами в репозитории

Страница репозитория состоит из двух колонок: слева — дерево артефактов с поиском и сортировкой, справа — детали выбранного артефакта.

На вкладке Security report в деталях артефакта показаны данные из базы CodeScoring: сведения о пакете (PURL, лицензии, мейнтейнеры, дата выпуска) и найденные в нём уязвимости по источникам (NVD, БДУ ФСТЭК, GitHub и другие). Вкладка доступна для артефактов proxy-репозиториев, кроме Docker и raw. Время кэширования этих данных из сервиса Index настраивается переменной SECURITY_INFO_CACHE_TTL_HOURS.

#Просмотр дерева

Дерево показывает структуру репозитория: папки и файлы с иконками. Файлы со значком «замок» — это «защищённые» (locked/release) артефакты, которые нельзя удалить или перезаписать без дополнительных шагов. Раскрытие папок происходит лениво: дочерние элементы подгружаются по клику.

При клике на файл его детали открываются справа: имя, размер, путь, контрольная сумма, метаданные формата (например, Maven groupId/artifactId/version или Docker tags).

#Поиск, сортировка и фильтры

Над деревом расположено поле Search artifacts: начните вводить подстроку — вместо дерева появится плоский список найденных артефактов (имя и путь). Клик по строке откроет детали соответствующего артефакта.

Рядом с поиском расположены две кнопки.

Кнопка Sort управляет сортировкой дерева:

• Sort by — Name, Date added или Date modified;
• Sort direction — A to Z или Z to A.

Кнопка-фильтр (иконка воронки) для proxy-репозиториев открывает дополнительный переключатель Show uncached artifacts. По умолчанию дерево показывает только то, что уже лежит в локальном кэше. С включённым флагом Save также подгружает в дерево артефакты, известные upstream, но ещё не скачанные — это удобно, чтобы предварительно посмотреть, что доступно в проксируемом источнике, не запуская реальный pull. Это доступно не для всех форматов репозиториев из-за различия протоколов.

#Действия над одним артефактом

После выбора артефакта в шапке правой панели доступны кнопка Download и меню с тремя точками рядом с ней, где находятся Lock artifact и Delete artifact:

• Download — скачивание файла обычной загрузкой браузера. Скачать можно только файл, не папку; для артефакта, который ещё не закэширован, кнопка неактивна;
• Lock artifact — пометить артефакт как release. После lock артефакт нельзя удалить или перезаписать обычным upload — это нужно, чтобы выпущенные версии не могли быть подменены;
• Delete artifact — удалить файл из репозитория (для hosted) или из кэша (для proxy). Для зафиксированного артефакта недоступно.

#Групповые действия

Слева от каждой строки дерева есть чекбокс. Как только отмечен хотя бы один, над деревом появляется панель с числом выбранных элементов, кнопкой Select All и действиями:

• Lock — массово зафиксировать выделенные артефакты;
• Delete — массово удалить.

Оба действия запрашивают подтверждение, а после выполнения уведомление показывает, сколько элементов обработано.

#Подключение клиентов и аутентификация

Save поддерживает несколько способов аутентификации, чтобы покрыть как интерактивные клиенты, так и CI-конвейеры. Конкретный способ выбирается клиентом самостоятельно через заголовок Authorization (или специальные заголовки формата).

Bearer-токен с тремя сегментами через точку классифицируется как JWT, остальные — как opaque npm-токен. Префикс sa$ в Basic Auth — это маркер service-аккаунта (robot).

#Получение JWT администратора

Административные примеры ниже используют заголовок Authorization: Bearer $ADMIN_JWT. Этот токен выдаёт cs-auth в обмен на логин и пароль администратора и живёт по умолчанию 15 минут.

#Шаг 1. Узнайте пароль администратора

Учётная запись admin создаётся автоматически при первом запуске. Источник её пароля зависит от того, как развёрнут сервис:

Сгенерированный пароль выводится отдельным блоком, который легко найти в логах:

************************************************************************
CodeScoring.Save — INITIAL ADMIN CREDENTIALS (shown once)
  username: admin
  password: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
You will be required to change this password on first login.
************************************************************************

# Kubernetes
kubectl logs deploy/cs-auth | grep -A 3 "INITIAL ADMIN CREDENTIALS"

#Шаг 2. Получите access-токен

curl -sS -X POST https://save.example.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "<admin-password>"}'

Ответ:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "a1b2c3d4e5f6...",
  "token_type": "Bearer",
  "expires_in": 900,
  "must_change_password": false,
  "permissions": {
    "uid": 1,
    "usr": "admin",
    "adm": true,
    "g": ["users.create", "users.list", "config.update", "..."]
  }
}

Для удобства сохраните токен в переменную окружения: во всех примерах далее используется именно она:

export ADMIN_JWT=$(curl -sS -X POST https://save.example.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "'"$ADMIN_PASSWORD"'"}' | jq -r .access_token)

#Шаг 3. Смените пароль, если это требуется

Если в ответе must_change_password: true, токен получен, но почти всё закрыто: любой эндпоинт /api/v1/admin/* вернёт 403 с телом {"code": "password_change_required"}. До смены пароля доступны только GET /api/v1/auth/me, PUT /api/v1/auth/me/password и сами эндпоинты входа / обновления / выхода.

curl -sS -X PUT https://save.example.com/api/v1/auth/me/password \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_JWT" \
  -d '{"old_password": "<текущий-пароль>", "new_password": "<новый-пароль>"}'

Минимальная длина нового пароля — 8 символов. Флаг must_change_password зашит в уже выданный токен, поэтому после смены пароля нужно войти заново (шаг 2) — старый токен так и останется ограниченным до истечения срока.

#Шаг 4. Проверьте права

curl -sS https://save.example.com/api/v1/auth/me \
  -H "Authorization: Bearer $ADMIN_JWT"

В ответе должно быть "is_admin": true — администратор проходит все проверки разрешений. Если is_admin: false, у учётной записи нет роли system-admin, и административные вызовы будут возвращать 403.

#Обновление токена

Время жизни access-токена — 900 секунд (настраивается переменной AUTH_JWT_EXPIRY), opaque refresh-токена — 7 суток (AUTH_REFRESH_TOKEN_TTL). Когда access-токен истёк, получите новую пару, не вводя пароль:

curl -sS -X POST https://save.example.com/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "<refresh-token>"}'

Refresh-токен ротируется: предъявленный токен гасится, а в ответе приходит новый — сохраняйте его на каждой итерации. Заголовок Authorization для этого запроса не нужен.

#Robot-аккаунты для CI/CD

Для интеграции с CI/CD не рекомендуется использовать личные пароли — они привязаны к сотруднику и быстро устаревают. Вместо этого создаётся robot-аккаунт — служебная учётная запись с отдельной ролью и долгоживущим API-ключом.

#Создание через веб-интерфейс

1. В боковом меню откройте Settings -> Robot accounts.
2. Нажмите Create robot account в правом верхнем углу.
3. Заполните поля:
   • Login — служебное имя для аутентификации (например, ci-builder). Save сам добавит к введённому значению префикс для service-аккаунта;
   • Name — человеко-читаемое название (например, CI Builder Bot);
   • Description — необязательное описание;
   • Expires in — дата истечения ключа. В окне выбора даты доступны быстрые пресеты Week, Month, Year. Если ключ должен жить вечно, поставьте флаг Never справа от выбора даты — поле выбора даты автоматически блокируется;
   • Global permissions — глобальные разрешения для робота;
   • Scoped permissions — разрешения, ограниченные одним, несколькими (или всеми сразу) проектами или репозиториями. Переключатель Scope выбирает уровень (Projects / Repositories), затем для каждого scope добавляются записи Add project permissions / Add repository permissions.
4. Нажмите Create robot account.

После успешного создания на экране автоматически открывается модальное окно с API-ключом — это пароль для Basic Auth.

#Окно с API-ключом

После нажатия Create robot account Save открывает окно API key created. В нём доступны:

• API key — поле в режиме «только для чтения» с самим значением ключа и кнопкой копирования в буфер обмена.
• Warning — текст с сервера, например Store this API key securely — it cannot be retrieved again.

Под секретом находится кнопка I have copied the key, которая закрывает окно и переводит на страницу редактирования созданного robot-аккаунта.

#Создание через API

Вызов требует токена администратора в переменной ADMIN_JWT (см. Получение JWT администратора).

curl -X POST https://save.example.com/api/v1/admin/robots \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_JWT" \
  -d '{
    "username": "ci-builder",
    "display_name": "CI Builder Bot",
    "description": "Robot account for CI/CD pipelines",
    "permissions": {
      "project": {
        "backend-team": ["project_artifacts.download", "project_artifacts.upload"]
      }
    },
    "key_expires_in_seconds": 7776000
  }'

В ответе вернётся api_key, который выдаётся только один раз при создании — сохраните его в secret-storage CI.

#Использование в клиенте

username = sa$<robot-name>, password = <api-key> — обычный Basic Auth:

curl -u "sa\$ci-builder:<api-key>" https://save.example.com/...

#Анонимный доступ на чтение

Если включён глобальный флаг AllowAnonymousRead, неаутентифицированным запросам выдаётся PermissionSet с правами projects.view, project_repos.view, project_artifacts.view, project_artifacts.download для всех проектов. Для Docker / OCI этот режим всё равно требует цикла 401 → /v2/token → 200, иначе Docker-клиент не сможет работать (см. Работа с OCI / Docker).

Текущее значение флага видно в Settings -> Configuration. Изменение значения выполняется через API. Для всех вызовов ниже нужен токен администратора (см. Получение JWT администратора):

curl -sS -X PUT https://save.example.com/api/v1/admin/config \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_JWT" \
  -d '{"auth.allow_anonymous_read": "true"}'

#Доступ proxy-репозиториев к upstream

#Учётные данные upstream

Если внешний репозиторий требует авторизации (приватный Nexus, Artifactory, GitLab, Private Packagist и т. д.), передайте учётные данные в блоке auth при создании или изменении proxy-репозитория:

curl -X POST https://save.example.com/api/v1/repos \
  -H "Content-Type: application/json" \
  -u "<username>:<password>" \
  -d '{
    "project": "backend-team",
    "name": "nexus-maven-proxy",
    "format": "maven",
    "repository_type": "proxy",
    "remote_url": "https://nexus.example.com/repository/maven-public/",
    "auth": {
      "auth_type": "basic",
      "username": "<upstream-user>",
      "password": "<upstream-password>"
    }
  }'

Пароль и токен работают только на запись: API их не возвращает, вместо них в ответе есть флаги has_password и has_token. Чтобы сменить учётные данные, отправьте новый блок auth в PUT /api/v1/repos/<repository_id>. Если учётные данные не подходят формату (например, apikey не для NuGet), Save пишет в лог предупреждение Configured upstream credential could not be applied; requests proceed anonymously и ходит в upstream без авторизации.

#Куда Save отправляет учётные данные

Save следит, чтобы учётные данные upstream не попали к посторонним:

• Только на хост upstream. Учётные данные получает хост из remote_url и его поддомены. Если upstream перенаправляет загрузку на другой хост (CDN, S3), Save убирает из запроса Authorization и X-NuGet-ApiKey и скачивает файл анонимно. Для Composer архивы с GitHub тоже скачиваются без учётных данных upstream.
• Без перехода с https на http. Если upstream открыт по https и перенаправляет на http, а в запросе ещё есть учётные данные, Save не идёт по такому редиректу. Запрос завершается ошибкой, в логе — refusing to follow redirect from https to ... with upstream credentials attached. Повторных попыток нет: это ошибка настройки upstream.
• Docker: сервис токенов только по https. Если реестр открыт по https, а его сервис токенов (realm из заголовка WWW-Authenticate) — по http, Save не отправит туда пароль. В логе — refusing to send upstream credentials to non-https token realm.
• Upstream по http. Proxy-репозиторий с remote_url на http:// и учётными данными работает, но пароль уходит в открытом виде. Save один раз на хост пишет в лог предупреждение upstream credentials are configured over plain http and are sent unencrypted. По возможности используйте https.

Для Docker-реестров, которые выдают Bearer-токены (Docker Hub, Harbor и т. п.), корректно работает и получение списка образов upstream.

#Сертификаты и корпоративный прокси

• Сертификаты. Save проверяет сертификат upstream по системному хранилищу корневых сертификатов контейнера. Если upstream подписан корпоративным центром сертификации, смонтируйте его сертификат в контейнер (например, в каталог /extra-ca) и задайте переменную SSL_CERT_DIR=/etc/ssl/certs:/extra-ca — так системные сертификаты тоже останутся доверенными. Не используйте для этого SSL_CERT_FILE: он заменяет системное хранилище целиком. Ошибки сертификата (неизвестный центр, истёкший срок, чужое имя хоста) Save не повторяет: клиент сразу получает ошибку, а причина видна в логе backend.
• Корпоративный прокси. Все proxy-репозитории, включая NuGet, учитывают переменные HTTPS_PROXY, HTTP_PROXY и NO_PROXY. Добавьте в NO_PROXY внутренние адреса, к которым Save должен ходить напрямую: сервис cs-auth, S3/MinIO, внутренние upstream.

#Политики очистки

Чтобы хранилище не разрасталось бесконечно, на репозитории привязываются политики очистки — правила автоматического удаления (или удержания) артефактов. Save поддерживает пять типов политик; для большинства задач достаточно простых, для сложных AND/OR-условий используется тип expression.

#Создание политики

1. В боковом меню откройте Cleanup.
2. Нажмите Create policy.
3. Заполните общие поля: Display name, Description, при необходимости — Schedule (cron-выражение из пяти полей: минуты, часы, день, месяц, день недели).
4. Выберите Policy type — определяет основное правило очистки:

5. Укажите Formats, к которым применяется политика. Если оставить пустым, политика будет применяться ко всем форматам.
6. Для типа expression дополнительно соберите дерево критериев — каждый критерий это сочетание type, оператора сравнения (eq, ne, gt, lt, matches, contains) и значения; критерии можно объединять группами с логическим оператором AND или OR.
7. Нажмите Create policy.

#Доступные критерии для expression

Полный список — GET /api/v1/enums/cleanup-criterion-types.

#Привязка политики к репозиторию

Привязка происходит на форме создания или редактирования репозитория (или проекта — тогда политика каскадно применяется ко всем его репозиториям).

1. Откройте репозиторий и нажмите кнопку с карандашом (Edit repository) в шапке.
2. Прокрутите до раздела Cleanup policy.
3. В левой колонке (Available) — все существующие политики, в правой (Applied) — уже привязанные. Отметьте нужные политики и перенесите их стрелкой в Applied; чтобы отвязать политику, удалите её из списка Applied.
4. Сохраните изменения.

#Ручной запуск и предварительный просмотр через API

# Сухой прогон — посмотреть, что было бы удалено, без сохранения политики
curl -X POST https://save.example.com/api/v1/cleanup/preview \
  -H "Content-Type: application/json" \
  -u "<username>:<password>" \
  -d '{
    "repository_id": 42,
    "policy_type": "delete-snapshots-older-than",
    "value": "30"
  }'

# Запуск уже сохранённых политик (с опциональным dry_run)
curl -X POST "https://save.example.com/api/v1/cleanup/execute?project=backend-team" \
  -H "Content-Type: application/json" \
  -u "<username>:<password>" \
  -d '{
    "policies": ["delete-old-snapshots", "keep-latest-5"],
    "dry_run": true
  }'

#Управление доступом

Управление пользователями, ролями и правами на проекты и репозитории выполняется отдельным сервисом cs-auth. API проксируется через Save под префиксами /api/v1/auth/* и /api/v1/admin/*. Способы аутентификации описаны выше в разделе Подключение клиентов и аутентификация.

В веб-интерфейсе нужные разделы находятся в Settings:

• Roles — описания ролей с набором разрешений;
• Users — учётные записи людей;
• Robot accounts — служебные учётные записи (см. выше).

#Уровни доступа

Права в CodeScoring.Save гранулярны, в формате <resource>.<action>. Роли в cs-auth определяются пользователем и представляют собой набор таких разрешений.

На уровне репозитория (артефакты внутри репозитория):

На уровне репозитория (сам репозиторий):

На уровне проекта (cascade-permissions, распространяются на все репозитории и артефакты проекта):

Глобальные (только через global scope роли):

#Привязка пользователя или robot-аккаунта к проекту

Привязка участника к проекту — это назначение конкретной роли конкретному пользователю или robot-аккаунту в рамках одного проекта. Назначенный участник получает все разрешения роли, а в шапке проекта он отображается как member.

#Через веб-интерфейс

#Через API

Все вызовы ниже требуют токена администратора в переменной ADMIN_JWT (см. Получение JWT администратора).

Добавление участника:

curl -X POST https://save.example.com/api/v1/admin/projects/backend-team/members \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_JWT" \
  -d '{
    "user_id": 5,
    "role_id": 2
  }'

Для пользователей role_id обязателен, для robot-аккаунтов (флаг is_service=true) может быть опущен.

Просмотр списка участников:

curl -sS -H "Authorization: Bearer $ADMIN_JWT" \
  "https://save.example.com/api/v1/admin/projects/backend-team/members?limit=50"

Смена роли существующему участнику:

curl -X PUT https://save.example.com/api/v1/admin/projects/backend-team/members/5 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_JWT" \
  -d '{"role_id": 3}'

Удаление участника из проекта:

curl -X DELETE https://save.example.com/api/v1/admin/projects/backend-team/members/5 \
  -H "Authorization: Bearer $ADMIN_JWT"

#Те же действия через API

Каждое действие, описанное выше для интерфейса, доступно и через REST API. Это полезно для скриптов первоначальной настройки, инфраструктуры как кода (Terraform / Ansible) и интеграционных тестов.

#Документация API (Swagger)

Полное описание API открывается в Swagger UI:

https://save.example.com/api/swagger/

В правом верхнем углу переключаются два документа: CodeScoring.Save API (репозитории, артефакты, политики очистки, ключ активации) и CodeScoring.Auth API (пользователи, роли, robot-аккаунты, аудит). Сами спецификации доступны по адресам /api/swagger/doc.json и /api/v1/admin/swagger/doc.json — по ним удобно генерировать клиентов. В веб-интерфейсе Swagger UI открывается кнопкой CS Save API внизу бокового меню. Чтобы вызвать метод прямо из Swagger UI, нажмите Authorize и вставьте Bearer <токен> (см. Получение JWT администратора).

#Создание проекта

curl -X POST https://save.example.com/api/v1/projects \
  -H "Content-Type: application/json" \
  -u "<username>:<password>" \
  -d '{
    "name": "backend-team",
    "display_name": "Backend Team",
    "description": "Backend services and microservices",
    "color": "#4A90D9"
  }'

#Создание Proxy-репозитория

curl -X POST https://save.example.com/api/v1/repos \
  -H "Content-Type: application/json" \
  -u "<username>:<password>" \
  -d '{
    "project": "backend-team",
    "name": "maven-central",
    "display_name": "Maven Central (proxy)",
    "format": "maven",
    "repository_type": "proxy",
    "remote_url": "https://repo1.maven.org/maven2/",
    "cache_ttl": 86400
  }'

#Создание Hosted-репозитория

curl -X POST https://save.example.com/api/v1/repos \
  -H "Content-Type: application/json" \
  -u "<username>:<password>" \
  -d '{
    "project": "backend-team",
    "name": "internal-maven",
    "display_name": "Internal Maven",
    "format": "maven",
    "repository_type": "hosted"
  }'

#Назначение политики очистки

curl -X POST "https://save.example.com/api/v1/cleanup/assignments?project=backend-team" \
  -H "Content-Type: application/json" \
  -u "<username>:<password>" \
  -d '{
    "policies": [
      {"policy_name": "delete-old-snapshots", "priority": 10, "enabled": true}
    ]
  }'

#Создание политики очистки

curl -X POST https://save.example.com/api/v1/cleanup/policies \
  -H "Content-Type: application/json" \
  -u "<username>:<password>" \
  -d '{
    "name": "delete-old-snapshots",
    "display_name": "Delete Old Maven Snapshots",
    "description": "Удалять SNAPSHOT-версии Maven старше 30 дней",
    "policy_type": "delete-snapshots-older-than",
    "value": "30",
    "formats": ["maven"],
    "enabled": true,
    "schedule": "0 2 * * *"
  }'

#Создание политики на основе выражения

curl -X POST https://save.example.com/api/v1/cleanup/policies \
  -H "Content-Type: application/json" \
  -u "<username>:<password>" \
  -d '{
    "name": "clean-old-prereleases",
    "display_name": "Clean Old Pre-releases",
    "policy_type": "expression",
    "formats": ["maven", "npm"],
    "expression": {
      "action": "delete",
      "logical_operator": "and",
      "criteria": [
        {"type": "is_prerelease", "value": "true"},
        {"type": "created_before", "value": "14"}
      ]
    },
    "enabled": true
  }'

#Мониторинг

#Журнал аудита

Журнал аудита фиксирует все изменения в проектах, репозиториях, артефактах, ролях и robot-аккаунтах. В UI он доступен:

• Глобально — Settings -> Audit log;
• По проекту — на странице проекта в шапке справа есть иконка журнала, ведущая на отфильтрованный по проекту журнал.

Каждая запись содержит время события, инициатора, тип ресурса и его идентификатор, тип действия и набор полей с подробностями (имя загруженного артефакта, изменённые параметры репозитория и т.п.). Записи группируются по дням и отображаются в виде таймлайна, а ссылки внутри записи кликабельны (открывается соответствующий проект, репозиторий, политика, пользователь или роль).

Журнал можно выгрузить за период через кнопку Export в шапке (форматы JSON или HTML).

# Аудит-журнал по конкретному репозиторию через API
curl -u "<username>:<password>" \
  "https://save.example.com/api/v1/admin/audit?resource_type=repository&q=maven-central&limit=50"

#Статистика репозитория

Текущие агрегированные показатели по репозиторию доступны через API:

curl https://save.example.com/api/v1/repos/<repository_id>/stats \
  -u "<username>:<password>"

Ответ:

{
  "id": 42,
  "name": "maven-central",
  "project_name": "backend-team",
  "artifact_count": 1523,
  "total_size": 16413032448,
  "cache_hit_ratio": 0.85,
  "last_activity": "2026-03-17T10:30:00Z"
}

#Состояние сервиса

curl https://save.example.com/health

Глобальный health-check сервиса. Отдельных health-эндпоинтов на репозиторий нет: доступность upstream проверяется фоновыми воркерами и отражается через метрики Prometheus.

#Логи

Логи централизованные, в формате JSON. Фильтрация по конкретному репозиторию — через стандартные средства log-aggregator'а.