Створення приватного репозиторія для Composer packages in the Package Registry

Ми впевнені, що серед наших клієнтів є багато професіоналів IT, які працюють над цікавими проектами. Якщо у Вас виникає бажання розповісти про них, Ви можете розмістити статтю у нашому блозі. А щоб було цікавіше, ми зробили конкурс статей, щомісяця три переможці отримуватимуть призи.

Категорії

Стаття також доступна російською (перейти до перегляду).

Створення приватного репозиторію Composer за допомогою Gitlab.

Вступ

Розглядається створення та використання приватного репозиторію 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/ukr/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 та продемонструємо процес створення репозиторію.

Створення групи та проекту

Після реєстрації на сервісі та авторизації одразу ж стає доступним створення груп, проектів та здійснення їх налаштувань. Наведені нижче скриншоти демонструють процес створення групи.

Стартова странінка GitLab

У вікні створення групи необхідно ввести її назву, http-адресу розміщення сервісу GitLab та включити опцію Private, що активізує можливість роботи з групою та всіма її проектами лише для її учасників.

Стрінка створення нової групи в GitLab

Після натискання на кнопку Create group створюється група з назвою ukraine, котрій присвоюється ідентифікатор ID = 2. Ідентифікатор групи є важливим елементом керування процесами розміщення пакетів з терміналу.

Створена група ukraine

Для створення проекту натискаємо на кнопку New project і, відповідно, переходимо до вікна створення проектів. Тут вимагається ввести його ім`я, обрати групу та включити опцію Private, що забезпечить надання доступу до нього усім членам групи.

Стрінка створення проекту

Після натискання на кнопку Create project, проект з назвою test-composer-repo створюється і, відповідно з`являється його вікно. Проекту присвоюється ідентифікатор ID = 1, який у подальшому може бути використаний при формуванні відповідних команд з терміналу.

Створений проект test-composer-repo

Треба зазначити, що одразу ж після створення проекту стає доступний його репозиторій, з яким вже можна працювати. Скориставшись кнопкою 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"

Звісно, у наведений код необхідно буде підставити значення параметрів для свого репозиторію.

Створення файлу .gitlab-ci.yml для работи з репозиторієм.

На етапі розгортання ми відправляємо виклик 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 працює.

Якщо ж сервіс не встановлений, то його треба встановити. Порядок його встановлення залежить від типу операційної системи, котра встановлена.

Процес публікації пакетів 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.

Ми у чомусь помилилися, чи щось пропустили?

Напишіть Про це у коментарях, ми з задоволенням відповімо та обговорюємо Ваші зауваження та пропозиції.

Як створити приватний репозиторій для Composer за допомогою Gitlab