Привет!

Сегодня мы проведём последний урок курса «Docs-as-code для самых маленьких» и настроим CI для нашего сайта с документацией.

CI — это процесс непрерывной сборки и деплоя программного продукта. Docs-as-code подразумевает использование лучших практик работы с кодом, и потому мы попробуем настроить автоматические сборку и деплой сайта с документацией, которые будет запускаться при каждом обновлении ветки main.

1. Откройте CMD и перейдите в папку проекта с помощью команды cd;
2. Создайте новую рабочую ветку (этот процесс уже описывался в прошлых уроках и должен быть хорошо вам знаком);
3. Откройте папку с проектом через проводник;
4. Создайте новую папку `.github`в корне проекта;
5. Внутри папки .github создайте папку workflows;
6. Внутри папки workflows создайте новый файл ci.yml;
7. Откройте файл ci.yml с помощью VS Code или другого редактора;
8. Скопируйте текст ниже и вставьте его в файл ci.yml:

name: ci
on:
  push:
    branches:
      - main
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: 3.x
      - uses: actions/cache@v2
        with:
          key: ${{ github.ref }}
          path: .cache
      - run: pip install mkdocs-material
      - run: mkdocs gh-deploy --force

9. Сохраните изменения, отправьте их на сервер;
10. Войдите в GitHub, создайте пул-реквест и слейте рабочую ветку с веткой main.
11. Перейдите в раздел Actions → All workflow. В списке workflow появилась новая запись — это и есть наш новый автоматический процесс. Если он завершился успешно (все этапы отмечены зелёными галочками), значит, всё получилось. Для проверки можете внести какие-нибудь изменения в исходные файлы и добавить их в ветку main. После сливания рабочей ветки с веткой main в Actions опять должен запуститься новый workflow. Дождитесь его завершения, перейдите на сайт и убедитесь, что там отобразились ваши изменения.

Получилось? Ура! А теперь давайте поймём, как именно это удалось.

GitHub Actions — это не просто вкладка в вашем репозитории. Это специальный сервис, который позволяет автоматизировать процессы сборки и деплоя вашего проекта. Workflow — это последовательность определенных действий, которые нужно совершить для того, чтобы ваш продукт был опубликован.
Workflow бывают разные. В прошлом уроке мы запускали workflow вручную с помощью специальной команды от MkDocs, а сегодня мы настроили workflow с автоматическим запуском. Как мы это сделали?
Мы создали папку github и подпапку workflows. Именно сюда GitHub Actions будет заходить, чтобы найти, не оставили ли вы ему каких-нибудь готовых workflow. Поэтому мы и положили сюда YAML-файл (gh-actions понимает именно этот формат файлов), внутри которого описали последовательность действий, необходимых для сборки и деплоя нашей доки. По сути, мы расписали работу команды mkdocs gh-deploy, только дополнительно указали, что workflow должен запускаться автоматически при обновлении ветки main:

<…>
on:
  push:
    branches:
      - main
<…>

Теперь после каждого обновления main GitHub Actions выполняет описанные нами в файле ci.yml действия и публикует новую версию сайта.

Конечно, здорово уметь самим писать файлы для workflow, но мы всё-таки на курсе для самых маленьких, поэтому я открою вам секрет: текст для ci.yml я не создал с нуля, а взял из официальной документации MkDocs-materials. Так что вы можете пройти по ссылке и проверить, всё ли правильно я скопировал)

Что ж, программа-минимум выполнена: формальный процесс настроен, инструменты работают. Поздравляю вас с окончанием курса! Рад, что этот месяц мы провели вместе, занимаясь интересным и полезным делом!

Вы также можете оставлять свои вопросы в комментариях к любым постам независимо от того, когда вы читаете эти строки. Я вижу все комменты и буду стараться отвечать, невзирая на сроки давности.

P.S. Это ещё не всё, ведь я приготовил небольшой сюрприз. Тсс! Ставьте рукопожатия, и чуть позже я расскажу подробности 😎

#практика #docsascode