Особенности национального Workflow: Github Actions и OneScript

Эта статья - не мегапрофессиональный разбор всех тонкостей устройства Github Actions (GA), но обзор базовых моментов работы с ним, а также тех вопросов, с которыми лично мне пришлось столкнуться в процессе использования. Так как даже подобной, довольно дилетантской, статьи про данный механизм в сфере 1С я не нашел, думаю, будет не лишним поделиться своим опытом.

В первую очередь, стоит определиться с понятиями.

Рабочий процесс 

Он же workflow. Определение в названии: это совокупность действий, которые необходимо выполнить для приведения всех частей проекта/системы в надлежащее состояние.

Если вы выгружаете и обновляете базы, запускаете батники или выполняете тестирование - это тоже workflow, просто разной степени автоматизированности. Как правило, различные этапы этих процессов однотипны изо дня в день, а это значит, что их можно автоматизировать. Для чего и нужен Github Actions (собственно как и любые другие подобные инструменты)

Вкладка Actions репозитория GitHub

Описание процесса

Любой автоматизированный процесс должен быть описан. В GA это осуществляется посредством yml файлов следующего вида:

# Имя процесса
name: CI 

# Раздел описания событий срабатывания
on:
  push:
    branches: [ "main" ]    # На пуш в ветку main
  pull_request:
    branches: [ "main" ]    # На запрос слияния в ветке main

  
  workflow_dispatch:        # На ручной запус через вкладку Actions


# Описание отдельных работ - блоков рабочего процесса
jobs:

  # Имя первой работы - может быть любое
  build:
    
    # Запуск на Ubuntu
    runs-on: ubuntu-latest

    # Шаги текущей работы
    steps:
      
      # Внешний шаг, один из стандартных: дает доступ к папке репозитория.
      - uses: actions/checkout@v3

      # Запуск команды терминала Ubuntu (однострочный)
      - name: Run a one-line script
        run: echo Hello, world!

      # Запуск команды терминала Ubuntu (многострочный)
      - name: Run a multi-line script
        run: |
          echo Add other actions to build,
          echo test, and deploy your project.

Это - стандартный шаблон простого рабочего процесса. Разберем его основные элементы

• Начинается файл с name. Это просто имя процесса - оно будет отображаться в панели Actions
  
  
  
   
• Далее идет блок on. Данный блок отвечает за события, при которых процесс будет запускаться автоматически. Полный список можно найти в доках GitHub - их довольно много.
  
  В данном случае указаны события на push и на pull request, а также признак возможности запуска руками - workflow_dispatch. 
  
  
  
   
• После on идет jobs. Соответствуя говорящему названию, отвечает за список работ.
   
• И тут же непосредственно сами работы.
  
  Что такое "работа" (job)? Остановимся на этом подробнее, так как здесь и начинается самое интересное
  
  Работа в примере определена как build. На самом деле, build не build, а это - просто название. Вы можете указать тут любое, влияет это лишь на именование блока на схеме процесса.
  
  
  
  Далее идет строка - runs-on: ubuntu-latest. Данная строка отвечает за вариант системы, на которой мы будем выполнять свою работу. Это крайне важно, так как по сути Github Actions дает нам доступ к терминалу отдельной виртуальной машины, на которой мы можем творить все, что нашей душе угодно (в пределах доступных нам ресурсов, конечно).
  
  От выбранной системы же зависит, будем мы работать с CMD (Windows) или же с Bash (Linux)
  
  То есть, наш yml файл - этакий прокаченный BAT/Shell файл, который, помимо своих стандартных функций а) позволяет выбирать операционную систему б) может сам запускаться по событиям в) позволяет объединять несколько независимых окружений в один процесс г) крутится где-то там, в облаке
  
  В общем-то, после написания оснастки, все и сводится к тому, что мы выполняем команды терминала/командной строки. Они могут быть написанны внутри yml файла, лежать отдельным файлом (тем же .bat или .sh, например) или же быть подключенными со стороны
   
• Все, что идет далее после steps - как раз и есть эти выполняемые команды. run - выполнение команды терминала, а uses - использование стороннего обработчика, как правило предлагающего настройку через удобные, заложенные разработчиком параметры. Найти подобные обработчики можно на Github Marketplace - там есть инструменты на все случаи жизник
  
  Так, например, выглядит подключение (uses) стороннего решения по сохранению изменений в репозиторий от некого stefanzweifel внутри yml файла процесса.
   

  - uses: stefanzweifel/git-auto-commit-action@v5 
          with:
            commit_user_name: Vitaly the Alpaca (bot) 
            commit_user_email: vitaly.the.alpaca@gmail.com
            commit_author: Vitaly the Alpaca <vitaly.the.alpaca@gmail.com>
            commit_message: Преобразование OPI -> OInt (workflow)

  
  Устанавливать ничего не надо. Просто в своем файле пишется названия подключаемого решения, а после - with, которое отвечает за внесение параметров. Их описание, как правило, есть в Readme, так как все подобные внешние инструменты - такие же репозиторий, как и обычные проекты на GitHub
  
  
  
  Тут же можно глянуть и состав того решения, которое мы вызываем
   

• 
  
  Т.е. в основе - это тоже yml файл, который мы просто подключаем внутри своего. Очень удобно.

Начало работы и OneScript

Как создать свой wokrflow? Для начала необходимо иметь репозиторий на Github. Далее, на странице репозитория, необходимо выбрать вкладку Actions и нажать New Workflow

Тут нам дается возможность выбрать один из готовых шаблонов, как, например, шаблон из самого первого примера статьи - Simple Workflow, или же создать просто пустой файл для дальнейшего описания

После чего в открывшемся редакторе можно приступать к работе



Как уже было рассмотрено, непосредственно работа с репозиторием через workflow - это перечень команд терминала, а значит сюда возможно накатить OneScript. Сделать это можно двумя способами:
 

• Дуболомным - использовав wget и dpkg с ссылкой к файлу со страницы загрузки oscript.io. По ссылке будет загружен файл пакета, распакован и установлен. 
   

        - name: Установка OneScript
          run: |
            TEMP_DEB="$(mktemp)" &&
            wget -O "$TEMP_DEB" 'https://oscript.io/downloads/latest/x64/onescript-engine_1.9.0_all.deb' &&
            sudo dpkg -i "$TEMP_DEB"
            rm -f "$TEMP_DEB"
            

• Цивилизованным, через внешний Action от otymko. Из Marketplace, опять же 
   

        - uses: otymko/setup-onescript@v1.4
          with:
            version: 1.9.0 

Второй вариант предпочтительнее - тут и версию выбрать можно

Помимо этого, нам необходим 
 

- uses: actions/checkout@v2 

Для доступа к файлам репозитория. 

Останется лишь создать и запустить .os скрипт. Напишем в нем классическое приветствие:



И добавим вызов в workflow. Сразу выложу yml файл процесса целиком.
 

name: Test
on:
  workflow_dispatch:
jobs:
  RunOneScript:
    runs-on: ubuntu-latest  
    steps:

      - uses: actions/checkout@v3
      - uses: otymko/setup-onescript@v1.4
        with:
          version: 1.9.0 
          
      - name: Запускаем OneScript
        run: oscript ./workflow.os

Довольно несложный. Для запуска возвращаемся на вкладку Actions, выбираем наш workflow и нажимаем Run workflow:

Нажав на новый пункт в таблице запусков, мы попадаем на страницу схемы выполнения




Тут описаны работы и их взаимодействия между собой. У нас работа только одна - на неё и нажмем
 

Тут уже описаны конкретные шаги (steps), которые мы реализовывали:

• Set up job - стандартное начало работы, поднятие окружения
• Run actions/checkout@v3 - стандартный action для доступа к файлом репозитория. Нам он нужен для вызова os скрипта, который там лежит
• Run otymko/setup-onescript@v1.4 - установка OneScript
• Запускаем OneScript - выполнение нашей команды oscript ./workflow.os
• Завершение работы checkout и процесса в целом
   

Все эти шаги можно развернуть и посмотреть вывод - буквально тоже самое, что мы увидели бы, выполнив подобные действия в терминале настоящей машины под Ubuntu

А что же наш скрипт?

Все работает - приветствие выводится.

Собственно, на этом моменте нам становится доступен весь функционал языка 1С для работы с файлами, каталогами, JSON, XML и другими замечательными вещами, которые мы можем применить к файлам в нашем репозитории. В проекте Открытого пакета интеграций, например, таким образом описан процесс конвертации EDT проекта в проект пакета OneScript - копируются файлы 1С в структуру каталогов для OneScript, попутно убирая комментарий с чисто OneScript-овских строк через СтрЗаменить()
 

Функция ПолучитьСопоставлениеФайлов()

	Сопоставление = Новый Соответствие();
	Сопоставление.Вставить("./OPI/src/CommonModules/OPI_GoogleCalendar/Module.bsl"			, "./OInt/core/Modules/OPI_GoogleCalendar.os");
	Сопоставление.Вставить("./OPI/src/CommonModules/OPI_GoogleDrive/Module.bsl"			, "./OInt/core/Modules/OPI_GoogleDrive.os");
	Сопоставление.Вставить("./OPI/src/CommonModules/OPI_GoogleWorkspace/Module.bsl"			, "./OInt/core/Modules/OPI_GoogleWorkspace.os");
	Сопоставление.Вставить("./OPI/src/CommonModules/OPI_Notion/Module.bsl"				, "./OInt/core/Modules/OPI_Notion.os");
	Сопоставление.Вставить("./OPI/src/CommonModules/OPI_Telegram/Module.bsl"			, "./OInt/core/Modules/OPI_Telegram.os");
	Сопоставление.Вставить("./OPI/src/CommonModules/OPI_Twitter/Module.bsl"				, "./OInt/core/Modules/OPI_Twitter.os");
	Сопоставление.Вставить("./OPI/src/CommonModules/OPI_Viber/Module.bsl"				, "./OInt/core/Modules/OPI_Viber.os");
	Сопоставление.Вставить("./OPI/src/CommonModules/OPI_VK/Module.bsl"				, "./OInt/core/Modules/OPI_VK.os");
	Сопоставление.Вставить("./OPI/src/CommonModules/OPI_YandexDisk/Module.bsl"			, "./OInt/core/Modules/OPI_YandexDisk.os");
	Сопоставление.Вставить("./OPI/src/CommonModules/OPI_YandexID/Module.bsl"			, "./OInt/core/Modules/OPI_YandexID.os");
	Сопоставление.Вставить("./OPI/src/CommonModules/OPI_Тесты/Module.bsl"			    	, "./OInt/tests/Modules/internal/OPI_Тесты.os");
	Сопоставление.Вставить("./OPI/src/CommonModules/OPI_ПолучениеДанныхТестов/Module.bsl"	        , "./OInt/tools/Modules/OPI_ПолучениеДанныхТестов.os");
	Сопоставление.Вставить("./OPI/src/CommonModules/OPI_Инструменты/Module.bsl"			, "./OInt/tools/Modules/internal/Modules/OPI_Инструменты.os");
	Сопоставление.Вставить("./OPI/src/CommonModules/OPI_Криптография/Module.bsl"			, "./OInt/tools/Modules/internal/Modules/OPI_Криптография.os");
	
	Возврат Сопоставление;
КонецФункции 

Функция ПолучитьСоответствиеЗамен()

	СоответствиеЗамен = Новый Соответствие();
	СоответствиеЗамен.Вставить("// #Использовать"					, "#Использовать");
	СоответствиеЗамен.Вставить("//#Использовать" 					, "#Использовать");
	СоответствиеЗамен.Вставить("УстановитьБезопасныйРежим(Истина);"			, "");
	СоответствиеЗамен.Вставить("УстановитьБезопасныйРежим(Ложь);"			, "");
	СоответствиеЗамен.Вставить("// !OInt "						, "");

	Возврат СоответствиеЗамен;

КонецФункции

Процедура ВыполнитьОбработку()

	Сообщить("Начало конвертации OPI -> OInt");
	Сообщить("------------------------------");
	
	Начало = ТекущаяДата();

	СоответствиеМодулей = ПолучитьСопоставлениеФайлов();

	Для Каждого ПараМодулей Из СоответствиеМодулей Цикл

		Сообщить(Символы.ПС);
		ПортироватьФайл(ПараМодулей.Ключ, ПараМодулей.Значение);

	КонецЦикла;

	Сообщить("------------------------------");
	Сообщить("Обработка завершена! Длительность - " + Строка(ТекущаяДата() - Начало));

КонецПроцедуры

#Область СлужебныеПроцедурыИФункции

Процедура ПортироватьФайл(Знач Файл1С, Знач ФайлОС)
	
	ФайлМодуля = Новый Файл(Файл1С);

	МодульОС   = Новый Файл(ФайлОС);
	ИмяМодуля  = МодульОС.Имя;

	Если ФайлМодуля.Существует() Тогда
		ВыводСообщенияПроцесса(ИмяМодуля, "Начало обработки файла");
	Иначе
		ВыводСообщенияПроцесса(ИмяМодуля, "Файл не существует. Пропускаем");
		Возврат;
	КонецЕсли;

	Модуль = ПрочитатьМодуль(Файл1С, ИмяМодуля);

	Если СтрДлина(Модуль) = 0 Тогда
		ВыводСообщенияПроцесса(ИмяМодуля, "Модуль пустой. Пропускаем");
		Возврат;
	КонецЕсли;

	ОбработатьЗаменыМодуля(ИмяМодуля, Модуль);
	ЗаписатьМодуль(ФайлОС, Модуль, ИмяМодуля);
	
КонецПроцедуры

Функция ПрочитатьМодуль(Знач ФайлМодуля, Знач ИмяМодуля)

	ВыводСообщенияПроцесса(ИмяМодуля, "Начало чтения текста модуля");

	ЧтениеТекста = Новый ЧтениеТекста(ФайлМодуля);
	Модуль       = ЧтениеТекста.Прочитать();
	ЧтениеТекста.Закрыть();
	
	ВыводСообщенияПроцесса(ИмяМодуля, "Модуль прочитан. Длина - " + Строка(СтрДлина(Модуль)));
	
	Возврат Модуль;

КонецФункции

Процедура ЗаписатьМодуль(Знач ФайлМодуля, Знач Модуль, Знач ИмяМодуля)

	ВыводСообщенияПроцесса(ИмяМодуля, "Начало записи модуля");

	ТекстовыйДокумент = Новый ТекстовыйДокумент();
	ТекстовыйДокумент.УстановитьТекст(Модуль);
	ТекстовыйДокумент.Записать(ФайлМодуля);

	ВыводСообщенияПроцесса(ИмяМодуля, "Модуль записан");

КонецПроцедуры

Процедура ВыводСообщенияПроцесса(Знач ИмяФайла, Знач Действие)

	Длина = 30;

	Пока СтрДлина(ИмяФайла) < Длина Цикл
		ИмяФайла = ИмяФайла + " ";
	КонецЦикла;

	Сообщить("Конвертация | " + ИмяФайла + " | " + Действие);

КонецПроцедуры

Процедура ОбработатьЗаменыМодуля(Знач ИмяМодуля, Модуль)

	ВыводСообщенияПроцесса(ИмяМодуля, "Начало произведения замен");

	СоответствиеЗамен = ПолучитьСоответствиеЗамен();

	Для Каждого Замена Из СоответствиеЗамен Цикл
		Модуль = СтрЗаменить(Модуль, Замена.Ключ, Замена.Значение);
	КонецЦикла;

	ВыводСообщенияПроцесса(ИмяМодуля, "Окончание произведения замен");

КонецПроцедуры

#КонецОбласти

ВыполнитьОбработку();

name: Конвертация OPI -> OInt

# Controls when the workflow will run
on:
  workflow_dispatch:

jobs:

  Convert:
    runs-on: ubuntu-latest
    permissions:
        contents: write
     
    steps:
    
      - uses: actions/checkout@v2             
      - uses: otymko/setup-onescript@v1.4
        with:
          version: 1.9.0 

      - name: Выполнить скрипт преобразования OPI -> OInt
        run: oscript ./.github/workflows/convert.os

      - uses: stefanzweifel/git-auto-commit-action@v5 
        with:
          commit_user_name: Vitaly the Alpaca (bot) 
          commit_user_email: vitaly.the.alpaca@gmail.com
          commit_author: Vitaly the Alpaca <vitaly.the.alpaca@gmail.com>
          commit_message: Преобразование OPI -> OInt (workflow)

К тому же, вы можете использовать любые готовые библиотеки для OneScript - их немало. Ну и конечно же - все, что вы можете достать через менеджеры пакетов для дистрибутивов, вроде apt, также здесь доступно

В заключение
 

Эта статья - вводная. Тут мы рассмотрели в целом что такое Github Actions, но много чего интересного пока осталось за кадром и, чтобы не смешивать таблицу умножения с интегралами, будет рассказано в следующей статье. Если на момент вашего прочтения она уже вышла - ссылку будет ниже.
 

UPD: Вот и она
Особенности национального Workflow: Секреты, кэш и артефакты в Github Actions
Вторая часть обзора функционала Github Actions

Бонус - yml процесса сканирования для SonarQube

Ниже приведен код yml файла для обновления данных в SonarQube. Он, в целом, основан на официальном action из Marketplace от SonarSource, за тем исключением, что по умолчанию там не используется checkout, из-за чего возникают проблемы с определением пути к каталогу проекта и, по понятным причинам, нет отбора по файлам расширения bsl
 

name: SonarQube analysis

on:
  workflow_dispatch:

permissions:
  pull-requests: read
  
jobs:
  Analysis:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Анализ проекта
        uses: SonarSource/sonarqube-scan-action@7295e71c9583053f5bf40e9d4068a0c974603ec8
        env:
          GITHUB_TOKEN: ${{ secrets.TOKEN }}  
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}  
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }} 
          LC_ALL: "ru_RU.UTF-8"
        with:
          projectBaseDir: ${{ github.workspace }} # Можно написать путь к папке через /. Например ${{ github.workspace }}/MyProject
          args:
            -Dsonar.projectKey=                   # Введите тут ключ проекта
            -Dsonar.sourceEncoding=UTF-8 
            -Dsonar.inclusions=**/*.bsl

В нем используется 3 секрета (Репозиторий -> Settings -> Secrets and variables -> Actions)

• TOKEN - GitHub токен
• SONAR_TOKEN - токен SonarQube
• SONAR_HOST_URL - URL размещения вашего SQ

Спасибо за внимание!

 

 Мой GitHub:     https://gitub.com/Bayselonarrend 
 Лицензия MIT:   https://mit-license.org