Что такое github actions
Автоматизация ручных действий с GitHub Actions
GitHub Actions — инструмент для автоматизации рутинных действий с вашего пакета на GitHub.
Из личного опыта расскажу, как без опыта и знаний о настройке CI, я научился автоматизировать рутину в своем Open Source проекте всего за день и что на самом деле это действительно не так страшно и сложно, как многие думают.
GitHub предоставляет действительно удобные и рабочие инструменты для этого.
План действий
настроим CI в GitHub Actions для небольшого проекта на PHP
научимся запускать тесты в матрице с покрытием (зачем это нужно также расскажу)
создадим ботов, которые будут назначать ревьюющих / исполнителей, выставлять метки для PR-s (на основе измененных файлов), а по окончании ревью и проверок в Check Suite будут автоматом мержить наши PR, а сами ветки будут удаляться автоматически.
подключим бота, который будет создавать релизы, которые автоматически будут пушиться в packagist.
В общем, мы постараемся минимизировать ручной труд так, чтобы от вас, как от автора вашего Open-Source пакета, оставалось только писать код, ревьюить и апрувить пулл-реквесты, а все остальное за вас делали боты. А если вы умеете делегировать, то и ревью и написание кода можно также возложить на плечи ваших соратников, проект будет и развиваться без вашего участия.
Настройка CI
Сильно углубляться в тонкости настройки CI для запуска тестов я не буду, на хабре достаточно постов об этом, но для небольшого проекта на PHP с базой данных Postgres примера моего CI вполне хватит. Лишнее можно удалить, названия и ключи можно менять на ваш вкус.
Создайте файл примерно с таким содержимым:
Расскажу лишь в кратце, в этом конфиге 3 основных шага (lint, tests и coverage)
Если код не соответствует code style проекта, джобка падает и CI дальше не запускается. В данном примере, я использую линтер с правилами от umbrellio/code-style-php, а сами скрипты запуска описаны так (первый для проверки, второй для авто фиксов для локального использования):
В целом тут тоже ничего нет сложного, разве что два момента:
опция experimental (к слову назвать опцию можно как угодно) для матрицы нужна для того, чтобы падающие джобки в экспериментальном окружении не фейлили CI, например, когда вы добавляете поддержку новой версии PHP, и не ставите самоцелью решать упавшие тесты или покрытие прям щас. Такие джобки игнорируются (если падают).
Но т.к. я перфекционист и мне нужен badge:100% coverage, в моем случае используется матрица покрытия и затем, отправленные отчеты о покрытии, мержатся в один. Например, coveralls.io поддерживает обьединенный кавераж.
Теперь когда у нас есть CI, мы попробуем подключить ботов для автоматизации нашей рутины.
Авто-назначение меток (labels)
Для подключения бота создайте два файла (конфиг и скрипт):
Тут по сути мы описываем маппинг меток к файлам и директориям вашего пакета, в зависимости от того, какие файлы будут изменены в рамках вашего PR, такие метки будут автоматически выставлены к PR.
Метки нужны для того, чтобы в последствии мы могли на их основании генерировать Summary для наших релизов и определять степень важности PR (будет ли это patch, minor или major). Вообще говоря, метки помогают визуально категоризировать пулл-реквесты, что очень удобно, когда их (pull-реквестов) много.
Авто-назначение ревьюеров и исполнителей
Для подключения бота создайте два файла (конфиг и скрипт):
Тут мы по сути описываем, кто и в каком кол-ве будет назначаться в качестве ревьюеров, и просто перечисляем логины пользователей с GitHub.
Авто-мержирование проверенных PR
Для подключения бота создайте файл скрипта с содержимым:
Из важного тут только то, что мержится будут только те PR, у которых будет выставлена метка approved, а также если все проверки в CheckSuite будут пройдены.
Мержить будем через Squash, чтобы была красивая история коммитов.
Авто-апрув отревьюенных PR
Когда ревьюющий ставит аппрув в PR, будем автоматом проставлять метку approved, создайте файл скрипта с содержимым:
Авто-выпуск релизов с ченджлогом
Для подключения бота создайте два файла (конфиг и скрипт) с содержимым:
В зависимости от меток, бот будет увеличивать либо MAJOR, либо MINOR, либо версию PATCH
Теперь нужно провести некоторые настройки в GitHub Settings вашего проекта
Настройка Check Suite в GitHub
По умолчанию ветки в GitHub никак не ограничены, и пушить в них может каждый, кто имеет доступ на запись, но если вы хотите, чтобы код был красивый, чтобы код был покрыт на 100%, и у вас есть прочие хотелки, необходимо поставить ограничения и настроить Check Suite.
Пример, где настраиваются ограничения веток
Выберите основную ветку и создайте правило. Из того, на что следует обратить внимание, это следующие моменты:
Настройка approvals
По сути, тут мы настраиваем кол-во людей, которые должны посмотреть PR, будут ли сбрасываться апрувы, после появления новых коммитов, а также необходимо ли участие Code Owners в ревью.
Пример, как настраиваются approvalls
Настройка обязательных проверок для Check Suite
Все наши проверки (в CI это джобки, в основном, но и другие интеграции тоже, например, Coveralls / Scrutinizer, и прочие анализаторы кода), могут быть как обязательными или необязательными.
Если проверка обязательная, то мержирование PR будет заблокировано пока все проверки не будут пройдены.
Пример, как настроить Check Suite для ветки
Автоматически удаляем ветки после мержа
Чтобы у нас была красивая история коммитов, а также чтобы не удалять вручную ветки после мержа, в Settings => Options нужно разрешить только Squash, если вы хотите красивую историю коммитов и включить опцию «Automatically delete head branches«
Пример настройки тут
Настройка веб-хука для packagist.org
Тут все стандартно, на сайте packagist есть инструкция, но для полноты поста выложу тоже.
Пример, как настроить webhook packagist
Секретный ключ можно взять на packagist в настройках вашего профиля (Show Api Token).
Таким образом, если вы поддерживаете достаточное кол-во OpenSource проектов, и в каждом из них есть некоторое количество активных Contributor-ов (с правами записи), вы можете настроить CI так, что сообщество будет само писать код, а ваши доверенные лица будут ревьюить, общий workflow будет соблюден.
Вы даже можете в coveralls / scrutinizer настроить правила, чтобы Check Suite падал если % покрытия кода меньше 100%, а в Readme напичкать баджиками для красоты, например так:
Буду рад, если мой туториал будет кому-то полезен, т.к. перед написанием данного поста я впервые столкнулся с GitHub Actions, я не DevOps и настройкой CI не занимаюсь, самому пришлось прогуглить не один сайт, чтобы настроить такой workflow, который был нужен мне.
Github actions: базовые понятия
Что это такое и как удаленно прогонять тесты на каждый пуш при помощи одного крошечного конфига
Jul 13, 2020 · 6 min read
Что такое github actions вообще?
Это указание гитхабу запускать какой-то код каждый раз когда случается н екое событие. Push, создание PR, таймер, внешнее событие, а также всякие другие.
Где запускается этот код? На виртуальных машинах гитхаба(но при желании можно и на своих гонять). Удобно, можно ничего не настраивать.
Что он делает? Да что угодно, насколько хватит фантазии, главное — позволяет автоматизировать какие-то действия, нужные для вашего процесса разработки: гонять тесты, собирать и деплоить продукты, собирать статистику, оповещать людей.
Таким образом github предоставляет возможность не только прикрутить неплохой бесплатный CI/CD(как раньше умел только gitlab, о котором у меня тоже была статья), но и создать очень гибкую и легко конфигурируемую систему поддержки разработки.
Тут все восхитительно просто.
Для начала нужно придумать, что же хочется сделать. Потом найти готовый экшен/несколько, которые позволят это сделать. Их проще всего искать в github marketplace — по сути это просто список репозиториев, которые подали заявку, чтобы быть там. На самом деле вы будете ссылаться на конкретный репозиторий конкретного пользователя.
Если подходящие готовые не находятся, всегда можно написать свой. Это очень просто. Я, например, написала экшен, чтобы интегрировать jira в пулл-реквесты:
A lightweight solution to integrate GitHub with JIRA for project management. 🔎 To make jira-description-action a part…
Пока что давайте разберем самый простой пример — пусть на каждый пуш в любой ветке гоняются тесты(пример будет про js-разработку)
контент у него будет такой:
Тогда в интерфейсе гитхаба прогоны будут выглядеть вот так:
Разберемся, что делает каждая строчка. Этот пример покрывает далеко не все возможные опции, у гитхаба есть чудесная документация на английском, где описано все-все-все
Steps
Посмотрим еще раз на конфиг, тут видно, что у нас 4 шага, только у них почему-то разный набор параметров, как это работает?
После того, как этот файл добавлен и запушен в master, на каждый дальнейший пуш будет прогоняться наш скрипт с тестами.
Если это был просто пуш, результат можно будет увидеть в списке коммитов. Если пулл-реквест — в саммари внизу
Вот и все, разобрали маленький пример, ура, можно дерзать!
Чтобы было проще, собрала список вещей, которые узнала, когда дерзала сама
Более сложные вопросы:
Как передать какой-нибудь токен, нигде его не публикуя? Или что такое secrets в конфигах?
Прикольные вещи:
1. Один раз создав и сохранив секрет, посмотреть его значение будет уже нельзя, только обновить
2. Если попытаться вывести значение секрета в логах или внутри кода экшена, выведется ***
3. Однако лучше не логгировать секреты вообще, так как любую защиту такого рода все же можно обойти
Как добавить secrets.GITHUB_TOKEN, который нужен в конфиге?
Все секреты с именами, начинающимися на GITHUB — служебные и подставляются гитхабом автоматически. Можно не переживать, просто напишите << secrets.GITHUB_TOKEN >> и все будет работать
Как сделать так, чтобы нельзя было замержить пулл-реквест если тесты упали?
Нужно пойти в настройки репозитория и у становить там правила для мержа в master, выбрав галочкой workflow, содержащий важные тесты
Как передать результат работы одного шага в другой шаг?
Это очень классная фича! При помощи кода ниже я проверяю, есть ли измененные файлы после билда в папке lib и, если есть, делаю коммит с обновленной сборкой. Переменные, добавленные в шаге, доступны в любом следующем шаге этого же job
Как передать результат работы между джобами?
Тут немного веселее!
Если информации в этой статье не хватило для того, чтобы реализовать то, что вам нужно, возможно, пришло время написать собственный экшен:
GitHub Actions: что это и как использовать
Процесс разработки кода может быть утомительным. Но что если бы вы могли снять часть этой работы с ваших плеч? В этом поможет GitHub Actions.
Github Actions – функция, введенная недавно в Github, позволяющая автоматизировать рабочий процесс. Теперь GitHub может заботиться о ряде процессов, которые могут быть вызваны различными событиями: пушинг кода, создание релиза или issues.
Примечание: GitHub Actions в настоящее время находится в бета-версии, поэтому придется зарегистрироваться тут, чтобы получить доступ.
Что можно сделать при помощи Github Actions? Возможности безграничны:
Это делается с помощью экшенов, которые могут быть определены в вашем или любом публичном репозитории Github или в образе Docker.
После того как вы залогинитесь, у вас появляется доступ к workflows и actions для создания собственных экшенов.
Вы можете легко получить доступ к редактору GUI через вкладку Actions, которая будет добавлена к вашим репозиториям, как только будут выданы такие права.
Как работает GitHub Actions?
Github Actions работают с помощью настроенного workflow, который содержит экшены, их отношения и зависимости.
Workflow
Этот параметр определяет, как экшены должны работать, и порядок их выполнения.
При создании нового workflow начните с main. файла, который найдете в .github/ каталоге репозитория.
Файл main.workflow содержит любое количество блоков workflow и actions в установленном порядке, и вы можете работать с ними в этом файле. Ниже приведен пример workflow с одним блоком workflow и тремя блоками actions:
Выше описана такая последовательность:
Именно по этой причине экшены выполняются в следующем порядке:
Экшен инициализируется только после успешного выполнения всех необходимых условий. Если атрибут resolves представлен массивом экшенов, они будут выполняться параллельно, как показано ниже:
Интерфейс workflows
Есть возможность создать workflow с помощью графического интерфейса GitHub, щелкнув вкладку Actions и нажав кнопку «Create a new workflow«. Откроется визуальный редактор, в котором можно задать параметры рабочего процесса.
Клик по пункту «Edit» откроет вкладку конфигурации, где можно определить имя рабочего процесса, а также события, которые его инициируют.
События-инициализаторы определяются в раскрывающемся списке «Run«:
Как только вы закончите настройку, нажмите Done, и ваш рабочий процесс будет готов к работе. Следующий шаг – добавление экшенов в рабочий процесс. Но сначала давайте посмотрим, как функционируют actions.
Actions
В действиях мы определяем, какие команды будут выполняться. Они могут храниться в образе docker, доступ к которому можно получить с помощью атрибута uses. Мы также можем попросить выполнить определенную команду в образе Docker с помощью атрибута runs, если это не предусмотрено – выполнится инструкция Dockerfile ENTRYPOINT. Если нужна определенная последовательность действий, используется атрибут needs, как показано в примере выше.
Переменные окружения
В actions мы можем применять любые переменные среды через атрибут env. Секретные переменные, такие как токены, предоставляются в атрибуте secrets. Они должны быть установлены в GUI рабочего процесса во вкладке «Settings». Мы также можем передавать аргументы экшенам в виде строки или массива, разделенного запятыми с помощью атрибута args.
При инициализации action рекомендуется указать версию данного action, использовав тег SHA или Docker. Это предотвратит нарушение работы workflow в случае публикации владельцем «корявого» обновления.
Настройка actions с помощью GUI-редактора еще проще – перетащите вниз синюю точку-коннектор в workflow.
Добавьте имя экшена в разделе Choose Action и нажмите кнопку Use. Вы можете добавить другие параметры конфигурации, как показано ниже, и нажать в конце Done.
Повторите эти шаги, если хотите добавить дополнительные действия в workflow и связать их по своему усмотрению. По завершении редактирования workflow в правом верхнем углу нажмите кнопку Start commit.
Введите комментарий коммита, укажите адрес электронной почты, выберите ветку и нажмите Propose new file.
Коммит workflow делает его доступным для вашей ветки. Чтобы включить workflow для всего проекта, создайте Pull Request для master и объедините его. Чтобы убедиться в правильной работе workflow, перед слиянием откройте вкладку Checks.
Чтобы узнать больше о том, как настроить свой workflow, а также какие события GitHub поддерживаются экшенами, ознакомьтесь с официальными инструкциями здесь.
Ограничения для workflow
Важно отметить, что в настоящее время GitHub накладывает следующие ограничения на все workflow:
Заключение
Github Actions определенно стоит внимания. Это упростит процесс разработки и сэкономит время. Если вы не хотите ковыряться во всех ваших конфигах, то Github предоставляет графический интерфейс, где вы можете все это быстро выполнить. Настройте свои экшены для любого ЯП, при помощи множества библиотек с открытым исходным кодом.
GitHub Actions: начало
В одной из последних статей я делала обзор GitHub Actions и показывала, как использовать существующий экшен для развертывания сайта Gatsby на GitHub Pages. В этой же статье я хочу углубиться в изучение экшенов GitHub, чтобы подробнее раскрыть их основную идею, показать и пояснить архитектуру, а также рассмотреть этапы их построения.
Но прежде чем переходить к особенностям этого инструмента GitHub, давайте уточним, какую он вообще несет пользу. Для этого мы рассмотрим события GitHub и то, как этот ресурс поддерживал их обработку ранее.
События GitHub
GitHub предоставляет хостинг проектов ПО и контроль версий через Git. Обеспечивая возможность сотрудничества между командами (зачастую распределенными), ревью кода и управление проектами, этот ресурс сформировал ядро жизненного цикла разработки ПО.
События GitHub играют важную роль в успешном функционировании GitHub, одновременно предоставляя точки возможного расширения путем интеграции с другими инструментами, применяемыми при разработке ПО. Вы можете использовать GitHub для совместной работы над исходным кодом, JIRA для управления проектами и Confluence для обработки документации. События GitHub помогают расширять спектр типичных выполняемых на GitHub действий и привязываться к другим инструментам, которые вы уже используете.
“Каждое событие соответствует конкретному набору действий, которые могут осуществляться в вашей организации и/или репозитории. Например, если вы подпишитесь на событие issues , то будете получать подробную информацию при каждом открытии issue , его закрытии, отметке и т.д.” — документация GitHub
Например, при отправке пул-реквеста на GitHub вам может понадобиться обновить статус соответствующего тикета в Jira.
На какие события GitHub можно реагировать?
В GitHub по части событий есть обширная документация. Вы можете подключаться к огромному спектру рабочих процессов и расширять их согласно нуждам команды или бизнеса.
Возможности в этом плане безграничны — можно автоматически находить и исправлять в коде проблемы стиля при каждом слиянии, отправлять сообщение Telegram при каждом неудачном развертывании или автоматически отмечать каждый новый пул-реквест в репозитории.
Как это было до появления GitHub Actions
Как же осуществляется прослушивание событий GitHub и реагирование на них? До появления GitHub Actions для получения событий GitHub рекомендовалось использовать веб-хуки.
Слушателем событий в данном случае является веб-сервис, выражающий конечную точку HTTP. Нужно лишь настроить в репозитории веб-хук, используя эту конечную точку в качестве цели доставки событий.
После этого при возникновении активности в репозитории GitHub будет выполнен POST события на эту конечную точку. При этом веб-хук может расширять активность, выполняя в ответ на событие пользовательский код.
Самый большой недостаток веб-хуков в необходимости существовать в качестве внешнего сервиса. Это подразумевает написание нового сервиса, его развертывание и дальнейшее обслуживание.
Знакомство с GitHub Actions
GitHub Actions вместо независимо развернутого веб-хука предоставляют способ реагирования на события GitHub в рамках самой этой платформы.
“GitHub Actions — это ваш рабочий процесс, создаваемый вами, выполняемый нами.” — блог GitHub
GitHub Actions обеспечивает ряд преимуществ:
Структура — рабочие процессы, задачи, этапы, экшены и исполнители
Событие GitHub запускает рабочий процесс:
Типы экшенов GitHub
Будучи наименьшим самостоятельным компонентом рабочего процесса, экшен включает в себя код, необходимый для выполнения одного логического задания — проверить репозиторий, настроить Node или развернуть статический сайт.
Как мы видели выше, эти логические задания могут комбинироваться для выполнения более общей задачи.
Написать экшен можно одним из двух способов:
JavaScript
В этом случае вы пишите код для экшена на JavaScript. Данный код выполняется с помощью версии Node, указанной вами в файле метаданных action.yml (подробнее об этом позже).
У этого подхода есть ряд недостатков:
Контейнеры Docker
Контейнеры Docker объединяют среду и код экшена GitHub вместе, что делает их более надежным способом упаковки.
Это значит, что получателю экшена не нужно беспокоиться об инструментах или зависимостях, используемых в данном экшене. Например, если он был определен в Node 12, но запускается в нестандартном исполнителе на Node 10, то это не вызовет проблем, поскольку экшен Docker выполняется в собственном контейнере, имеющем подходящую для данного экшена версию Node.
Создание экшена на Javascript
В одной из давних статей я описывала настройку веб-хука GitHub для отправки комментариев к пул реквестам, открываемым новыми участниками в репозитории. Сейчас я хочу воссоздать это поведение при помощи экшена.
Инициализация репозитория
Описание экшена
Мы указываем, что этот экшен выполняется на node12 и устанавливаем в качестве точки входа src/index.js (где располагается код для экшена).
Добавление зависимостей toolkit
GitHub предоставляет для экшенов toolkit (инструментарий), содержащий основные утилиты, которые могут потребоваться любому экшену. Мы будем использовать эти утилиты для чтения полезной нагрузки событий, создания клиента API GitHub и других тонкостей, которые не хотим реализовывать вручную.
Написание кода экшена
Коммит кода
Весь итоговый код для этого экшена можете найти в моем репозитории.
Экшен в рабочем процессе репозитория
Добавление токена доступа
Тестирование экшена
Пора его опробовать! Протестируйте свой новый рабочий процесс, создав пул реквест в собственный репозиторий. Если это будет первый пул реквест, то вы должны получить приветственное сообщение от дружелюбного экшена.