Статья также доступна на украинском (перейти к просмотру).
Оглавление
- Принципы функционирования сервиса Composer и его возможности
- Создание и настройка репозитория на сервере Gitlab
- Создание группы и проекта
- Настройка параметров учетной записи пользователя – участника группы
- Настройка параметров репозитория для переориентации на работу с Composer
- Добавление токена личного доступа в качестве маскированной переменной CI
- Включение реестра пакетов
- Настройка автоматической публикации версий
- Как использовать частные репозитории Gitlab для Composer
Рассматривается создание и использование частного репозитория Composer на базе платформы Gitlab, что может значительно повысить качество работы прежде всего разработчиков веб-приложений на языке PHP. В отличие от своих аналогов, менеджер зависимостей Composer способен обеспечить автоматическую загрузку библиотек функций в директорию отдельного проекта, то есть локально, что позволяет организовать параллельную работу над проектами, поддерживающими различные версии библиотек. У Сервиса есть и другие возможности, которые мы рассмотрим в статье.
Принципы функционирования сервиса Composer и его возможности
Основной целью создания сервиса является обеспечение автоматической загрузки необходимых ресурсов и контроля зависимостей для выполняемых проектов. Это реализуется путем использования различных типов репозиториев, которые могут быть как частными, так и публичными. Репозиторий, используемый по умолчанию, находится на сайте разработчиков сервиса - packagist.org. Именно здесь Composer будет искать ресурсы, если другие адреса репозиториев не указаны. Адреса репозиториев, названия ресурсов и другие метаданные указываются в специальном файле с названием composer.json, который всегда находится в корне директории проекта. Записи файла должны соответствовать формату JSON. Все данные, загружаемые в репозиторий, должны быть оформлены в виде так называемых Composer-пакетов.
Ближайшим аналогом сервиса является устаревший PEAR, но в отличие от Composer он не позволяет загружать необходимые ресурсы отдельно для каждого проекта, а лишь глобально, что исключает возможность параллельной работы над проектами и, соответственно, тормозит процесс разработки.
Перечислим основные возможности сервиса:
- Загрузка пакетов и их зависимостей;
- Работа посредством API с репозиториями типа git, svn и hg, которые могут находиться по любому адресу в сети;
- Возможность использования репозиториев указанных типов без оформления данных в виде Composer-пакетов;
- Возможность для каждого из проектов работать с разными версиями библиотечных ресурсов, поскольку пакеты загружаются в текущую директорию проекта;
- Быстрое развертывание среды в случае сбоев или на других мощностях благодаря наличию служебного файла composer.lock, который фиксирует конфигурацию текущей среды проекта;
- Возможность подключения в самом коде установленных библиотек благодаря автоматическому генерированию файла автозагрузки ресурсов autoload.php.
Создание и настройка репозитория на сервере Gitlab
GitLab относится к категории сервисов, позволяющих обеспечить разветвленное контролирование версий программного обеспечения, равно как svn и некоторые другие сервисы. Для его использования необходимо зарегистрироваться на сайте сервиса – https://gitlab.com, и получить аккаунт. Сервис поддерживает создание как публичных, так и частных репозиториев, которые могут размещаться как на сайте сервиса, так и в любом другом месте сети. Более того, с сайта GitLab можно скачать программное обеспечение сервиса и развернуть его на сервере компании. Виртуальный сервер с установленным GitLab можно заказать на нашем сервисе https://freehost.com.ua/vps-hosting/pr/gitlab/ и локально использовать для нужд компании.
Начиная с версии GitLab 13.2 сервис поддерживает создание и использование частных репозиториев Composer, что значительно расширяет его возможности. Однако следует отметить, что работа над проектом еще не завершена и поэтому в рабочей среде работа с Composer пока функционально ограничена. Для личных бесплатных аккаунтов существует ограничение в 500 Mb для реестров пакетов. Например, сервис GitHub, хотя и предоставляет функцию реестра пакетов, однако она вообще не поддерживает сервис Composer, в отличие от GitLab.
Для возможности работы с репозиториями Composer необходимо, чтобы проект созданный на GitLab использовал пространство имен группы, а не пользователя. Это является обязательным условием. Кроме того, GitLab обеспечивает наличие API, посредством которого Composer может работать с сервисом, только в этом случае возможно автоматическое размещение пакетов Composer в репозитории GitLab. Управление размещением (публикацией) пакетов может производиться с помощью терминала. Но просмотр загруженных пакетов на сервере GitLab возможен с помощью пользовательского веб-интерфейса. Сервис поддерживает несколько путей загрузки пакетов Composer в зависимости от способа управления процессом, о чем мы поговорим позже.
Для создания и подготовки к работе частного репозитория Composer на сайте GitLab необходимо выполнить следующий набор действий:
- Создание группы и проекта;
- Настройка параметров аккаунта пользователя – участника группы;
- Настройка параметров репозитория для переориентации на работу с Composer.
Выполним вышеуказанные действия на сервере GitLab и продемонстрируем процесс создания репозитория.
Создание группы и проекта
После регистрации на сервисе и авторизации сразу становится доступным создание групп, проектов и осуществление их настроек. Нижеследующие скриншоты показывают процесс создания группы.
В окне создания группы необходимо ввести ее название, http-адрес размещения сервиса GitLab и включить опцию Private, которая активизирует возможность работы с группой и всеми ее проектами только для ее участников.
После нажатия на кнопку Create group создается группа с названием ukraine, которой присваивается идентификатор ID=2. Идентификатор группы является важным элементом управления процессами размещения пакетов из терминала.
Для создания проекта нажимаем кнопку New project и, соответственно, переходим к окну создания проектов. Здесь требуется ввести его имя, выбрать группу и включить опцию Private, что обеспечит доступ к нему всем членам группы.
После нажатия на кнопку Create group создается группа с названием ukraine, которой присваивается идентификатор ID=2. Идентификатор группы является важным элементом управления процессами размещения пакетов из терминала.
Следует отметить, что сразу же после создания проекта становится доступен его репозиторий, с которым уже можно работать. Воспользовавшись кнопкой Clone, его можно скопировать на локальное устройство. Это также можно сделать с помощью соответствующей команды терминала, синтаксис команд предоставляет сервис GitLab в своей справочной системе.
Настройка параметров учетной записи пользователя – участника группы
Сервис предоставляет возможность устанавливать для пользователей разные уровни привилегий и ключи доступа при работе с репозиторием. Это реализуется в настройках аккаунта пользователя, его можно открыть в правом верхнем углу любого окна сервиса. В данном случае нас интересует возможность установить персональный токен доступа, необходимый для использования в сервисах, работающих с GitLab через API. Именно таким сервисом есть Composer. Кроме того, персональный токен может потребоваться для аутентификации Git по протоколу http.
С помощью команды меню User Settings -> Access Tokens откроем окно настроек персонального токена, показанное ниже. Среди обязательных параметров необходимо ввести имя приложения и установить права доступа к репозиторию в разделе Scopes. Включим опцию API, это предоставит полный доступ для чтения и записи API, включающей все группы, проекты и реестры пакетов и контейнеров.
После нажатия на кнопку Create personal access token, персональный токен доступа будет создан и в появившемся окне появится его значение, оно состоит из 20-ти символов. Это значение необходимо записать.
Настройка параметров репозитория для переориентации на работу с Composer
Перед настройкой соответствующих параметров сначала сформируем ключ типа DEPLOY_TOKEN (токен развертывания), который нам понадобится в дальнейшем для управления доступом к репозиторию. Для этого на странице настроек нашего проекта выберите команду Settings -> Repository и в разделе Deploy Tokens введем имя токена, значение нашего Username и включим опцию read_repository в разделе Scopes, устанавливающую уровень доступа «для чтения». После этого нажмем кнопку Create deploy token.
Токен будет создан и будет выведено его значение - MxPyjx3Qcn7YpaBMyCn3, которое необходимо записать. Его потом можно будет использовать как пароль.
Теперь установим необходимые настройки для репозитория.
Добавление токена личного доступа в качестве маскированной переменной CI
Для создания новой переменной на странице проекта выберем команду Settings -> CI/CD и в разделе Variables введем в качестве значений параметров key и value имя созданного нами токена развертывания и его значение соответственно. А также включим опцию Masked, это скроет токен в журналах CI. После этого нажмем кнопку Save variables. Сменная создана. В дальнейшем она будет использоваться GitLab CI для автоматической публикации пакета Composer.
Включение реестра пакетов
На странице настроек проекта выберите команду Settings -> General и в разделе Repository включим функции Pipelines (конвейеры) и Packages (пакеты). Это позволит использовать модуль GitLab Packages для публикации пакетов. Сохраним внесенные изменения с помощью кнопки Save Changes.
Настройка автоматической публикации версий
Функция GitLab Packages не позволяет в автоматическом режиме публиковать теги Git версии. Кроме того, отсутствует пользовательский интерфейс для создания версий совместимых с Composer. Однако сервис предоставляет конечный API, который можно вызвать для публикации пакета с определенной версией или веткой. Также предоставляется бесплатный сервис CI/CD, который можно использовать для публикации новых версий пакета в реестре Package Registry.
Для возможности работы с репозиторием создадим файл в корне репозитория с именем .gitlab-ci.yml и введем в нем следующие команды:
stages: - test - deploy test: stage: test image: phpwatch/docker-php:latest before_script: - php -v - composer install --prefer-dist -q --no-progress script: - ./vendor/bin/phpunit -v --coverage-text --colors=never --stderr deploy_composer: only: - tags stage: deploy script: - curl -sS --show-error --fail --data tag=${CI_COMMIT_TAG} "https://__token__:${DEPLOY_TOKEN}@gitlab.com/api/v4/projects/${CI_PROJECT_ID}/packages/composer"
Естественно, в приведенный код нужно будет подставить значение характеристик для собственного репозитория.
На этапе развертывания мы отправляем вызов curl для POST в пакетах API для публикации созданного тега, что гарантирует, что этот API не будет вызываться для других случаев, таких, например, push-сообщения и другие запросы. Если будет присутствовать действительный файл composer.json, GitLab создаст новую версию пакета и вернет ответ 201. Если же используется вышеприведенный код, задача CI будет выполнена только в случае, если GitLab примет новый тег.
Как использовать частные репозитории Gitlab для Composer
Подключение репозитория
Для подключения в качестве приватного репозитория Composer необходимо указать на него в корневом файле composer.json. Пример:
{ "repositories": [ { "type": "composer", "url": "https://gitlab.com/api/v4/group/<GROUP_ID>/-/packages/composer/composer.json " } ] }
Параметр <GROUP_ID> является идентификатором группы, к которой относится проект, имеющий в нашем случае значение 2. Адрес сервера GitLab для параметра URL должен быть соответствующим, в зависимости от того, где сервер развернут – на сайте компании GitLab или на локальном сервере собственной компании . Адрес нашего сервера: https://178.20.159.96/. Таким образом, для нашего проекта код файла будет выглядеть следующим образом:
{ "repositories": [ { "type": "composer", "url": "https://178.20.159.96/api/v4/group/2/-/packages/composer/ composer.json" } ] }
Значения URL всегда можно просмотреть в свойствах уже опубликованных пакетов на сервере GitLab.
Аутентификация репозитория
Перед использованием уже подключенного к Composer частного репозитория его необходимо аутентифицировать. Это можно сделать с помощью средств, поддерживаемых сервисом Composer. Для этого используем токен личного доступа, созданный ранее. Введем нижеприведенный код в локальный файл auth.json, который нужно добавить в .gitignore, чтобы он игнорировался системой Git:
{ "http-basic": { "178.20.159.96": { "username": "___token___", "password": "MxPyjx3Qcn7YpaBMyCn3" } } }
Значение <___token___> является специальным пользовательским именем, которое используется GitLab в вызовах API. Для параметра <password> вводится значение токена личного доступа.
Указанные настройки можно также установить из терминала с помощью команды:
$ composer config http-basic.gitlab.com ___token___ <ACCESS_TOKEN>
После подставки своих значений, для нашего проекта команда будет выглядеть следующим образом:
$ composer config http-basic. 178.20.159.96 ___token___ MxPyjx3Qcn7YpaBMyCn3
Публикация пакетов
Публикация пакетов в реестре пакетов Package Registry сервиса GitLab может быть выполнена несколькими способами, в зависимости от типа применяемой технологии:
- Непосредственная регистрация и размещение с использованием команд git;
- Публикация с использованием API;
- Публикация с помощью сервиса CI/CD.
Первый тип публикации является самым простым и менее защищенным. Кроме того, он не позволяет публиковать пакеты Composer в автоматическом режиме. Токен личного доступа здесь не нужен.
Публикация с использованием API более защищена и требует использования токена личного доступа. Технология позволяет организовать автоматическое размещение пакетов в репозитории.
Публикация с помощью сервиса CI/CD является наиболее перспективной и качественной. Здесь также необходимо использование токена личного доступа. Технология позволяет использовать CI/CD-шабоны, что также повышает уровень работы с пакетами Composer.
Например, рассмотрим создание и публикацию пакета первым, самым простым способом.
Перед публикацией пакетов следует убедиться, что сервис Composer установлен в системе. Для этого достаточно ввести в терминале команду:
$ composer
В случае его наличия в терминале будет выведен экран, вроде следующего:
Если сервис не установлен, то его нужно установить. Порядок его установки зависит от типа установленной операционной системы.
Процесс публикации пакетов Composer с помощью git-команд состоит из нескольких шагов. Перечислим их:
- Создание директории для пакета Composer;
- Переход к созданной директории и инициализация сервиса Composer;
- Регистрация пакета в Git и отправка в репозиторий GitLab.
Создание директории для пакета Composer. Введем в терминале:
$ mkdir one-composer-package
Переход в созданную директорию и инициализация сервиса Composer. Введем ответные команды:
$ cd one-composer-package $ composer init
После запуска последней команды в терминале будет выведен ряд вопросов, касающихся настроек, необходимых для регистрации пакета, в частности, это данные учетной записи GitLab, такие, как имя пользователя или имя группы, необходимые для обозначения пространства имен для Composer . После ответов на них в корне директории в автоматическом режиме будет сформирован файл composer.json, содержимое которого будет следующим:
{ "name": "ukraine", "description": "Library PHP one", "type": "library", "license": "GPL-3.0", "authors": [ { "name": "Alexander Rovnik", "email": "work@meta.ua" } ], "require": {} }
Для обозначения пространства имен нами было указано имя группы проектов, которую мы создали на GitLab.
Регистрация пакета в Git и отправка в репозиторий GitLab. Запустим в терминале следующие команды:
git init git add composer.json git commit -m 'Composer test one' git tag v1.0.0 git remote add origin git@gitlab.meta.ua:ukraine/test-composer-repo.git git push --set-upstream origin main git push origin v1.0.0
Пакет успешно зарегистрирован и отправлен в репозиторий! В коде мы указали имя нашего проекта (репозитория): test-composer-repo, созданного на GitLab. Именно туда попал наш пакет. После этого любой из участников группы ukraine будет иметь к нему доступ.
Подписывайтесь на наш телеграм-канал t.me/freehostua, чтобы быть в курсе новых полезных материалов. Смотрите наш канал YouTube на youtube.com/freehostua.
Мы в чем ошиблись, или что-то пропустили?
Напишите Об этом в комментариях, мы с удовольствием ответим и обсуждаем Ваши замечания и предложения.
Дата: 28.09.2022 Автор: Евгений
|
|
Авторам статьи важно Ваше мнение. Будем рады его обсудить с Вами:
comments powered by Disqus