Расширение GitHub Actions Importer с помощью пользовательских преобразователей

GitHub Actions Importer предоставляет возможность расширения встроенного сопоставления.

В этой статье

Юридическое уведомление

Сведения о пользовательских преобразователях

GitHub Actions Importer предоставляет возможность расширения встроенного сопоставления путем создания пользовательских преобразователей. Пользовательские преобразователи можно использовать для:

Использование пользовательских преобразователей с GitHub Actions Importer

Настраиваемый преобразователь содержит логику сопоставления, которую GitHub Actions Importer может использовать для преобразования подключаемых модулей, задач, меток runner или переменных среды для работы с GitHub Actions. Пользовательские преобразователи записываются с помощью языка DSL, созданного на основе Ruby, и определяются в файле с расширением .rb файла.

Вы можете использовать параметр CLI, чтобы указать, какие пользовательские файлы преобразователя следует использовать --custom-transformers с audit``dry-runкомандами и migrate командами.

Например, если пользовательские преобразователи определены в файле с именем transformers.rb, можно использовать следующую команду, чтобы использовать их с GitHub Actions Importer:

gh actions-importer ... --custom-transformers transformers.rb

Кроме того, можно использовать синтаксис шаблона глоба для указания нескольких пользовательских файлов преобразователя. Например, если несколько пользовательских файлов преобразователя находятся в каталоге с именем transformers, можно предоставить им все данные GitHub Actions Importer с помощью следующей команды:

gh actions-importer ... --custom-transformers transformers/*.rb

Примечание. При использовании пользовательских преобразователей файлы настраиваемых преобразователей должны находиться в том же каталоге или в подкаталогах, откуда gh actions-importer выполняется команда.

Создание пользовательских преобразователей для элементов

Вы можете создать пользовательские преобразователи, которые GitHub Actions Importer будут использоваться при преобразовании существующих шагов сборки или триггеров в эквивалент GitHub Actions. Это особенно полезно, когда:

  • GitHub Actions Importer не преобразует элемент автоматически.
  • Вы хотите изменить способ преобразования элемента с помощью GitHub Actions Importer.
  • Существующие конвейеры используют пользовательские или собственные расширения, такие как общие библиотеки в Jenkins, и необходимо определить, как эти шаги должны функционировать в GitHub Actions.

GitHub Actions Importer использует пользовательские преобразователи, определенные с помощью DSL, созданного на основе Ruby. Чтобы создать настраиваемые преобразователи для шагов и триггеров сборки:

  • Каждый пользовательский файл преобразователя должен содержать по крайней мере один transform метод.
  • Каждый transform метод должен возвращать Hash, массив Hash''' или nil. Это возвращаемое значение будет соответствовать действию, определенному в YAML. Дополнительные сведения о действиях см. в разделе "Общие сведения о GitHub Actions".

Пример пользовательского преобразователя для шага сборки

В следующем примере выполняется преобразование шага сборки, использующего идентификатор buildJavaScriptApp для выполнения различных npm команд:

Ruby
transform "buildJavaScriptApp" do |item|
  command = ["build", "package", "deploy"].map do |script|
    "npm run #{script}"
  end

  {
    name: "build javascript app",
    run: command.join("\n")
  }
end

Приведенный выше пример приводит к следующему шагу рабочего процесса GitHub Actions. Он состоит из преобразованных шагов сборки с идентификатором buildJavaScriptApp :

- name: build javascript app
  run: |
    npm run build
    npm run package
    npm run deploy

Метод transform использует идентификатор шага сборки из исходного экземпляра CI/CD в аргументе. В этом примере идентификатор имеет значение buildJavaScriptLibrary. Можно также использовать разделенные запятыми значения для передачи в метод нескольких идентификаторов transform . Например, transform "buildJavaScriptApp", "buildTypeScriptApp" { |item| ... }.

Примечание. Структура item данных будет отличаться в зависимости от платформы CI/CD и типа преобразованного элемента.

Создание пользовательских преобразователей для бегуна

Вы можете настроить сопоставление между модулями выполнения в исходном экземпляре CI/CD и их эквивалентными GitHub Actions.

GitHub Actions Importer использует пользовательские преобразователи, определенные с помощью DSL, созданного на основе Ruby. Чтобы создать настраиваемые преобразователи для бегуников, выполните следующую команду:

  • Пользовательский файл преобразователя должен иметь по крайней мере один runner метод.
  • Метод runner принимает два параметра. Первый параметр — это метка запуска исходного экземпляра CI/CD, а второй параметр — соответствующая метка запуска GitHub Actions. Дополнительные сведения о параметрах выполнения GitHub Actions см. в разделе "Использование средств выполнения, размещенных в GitHub".

Пример пользовательских преобразователей для бегуна

В следующем примере показан runner метод, который преобразует одну метку runner в одну метку GitHub Actions в результирующем рабочем процессе.

Ruby
runner "linux", "ubuntu-latest"

Кроме того, runner можно использовать метод для преобразования одной метки runner в несколько меток runner GitHub Actions меток runner в результирующем рабочем процессе.

Ruby
runner "big-agent", ["self-hosted", "xl", "linux"]

GitHub Actions Importer пытается сопоставить метку runner как можно лучше. В случаях, когда это не удается сделать, ubuntu-latest метка runner используется в качестве значения по умолчанию. Для управления этим значением по умолчанию можно использовать специальное ключевое слово с методом runner . Например, следующий настраиваемый преобразователь указывает GitHub Actions Importer использовать macos-latest в качестве средства выполнения по умолчанию вместо ubuntu-latest.

Ruby
runner :default, "macos-latest"

Создание пользовательских преобразователей для переменных среды

Вы можете настроить сопоставление между переменными среды в исходных конвейерах CI/CD с их значениями в GitHub Actions.

GitHub Actions Importer использует пользовательские преобразователи, определенные с помощью DSL, созданного на основе Ruby. Чтобы создать настраиваемые преобразователи для переменных среды, выполните следующие действия.

  • Пользовательский файл преобразователя должен иметь по крайней мере один env метод.
  • Метод env принимает два параметра. Первый параметр — это имя переменной среды в исходном конвейере, а второй параметр — обновленное значение переменной среды для GitHub Actions. Дополнительные сведения о переменных среды GitHub Actions см. в разделе "Хранение сведений в переменных".

Пример пользовательских преобразователей для переменных среды

Существует несколько способов настройки пользовательских преобразователей для сопоставления переменных среды.

  • В следующем примере устанавливается значение всех существующих переменных среды с именем OCTO, равным CAT при преобразовании конвейера.

    Ruby
    env "OCTO", "CAT"

    Можно также удалить все экземпляры определенной переменной среды, чтобы они не преобразовывалися в рабочий процесс GitHub Actions. В следующем примере удаляются все переменные среды с именем MONA_LISA.

    Ruby
    env "MONA_LISA", nil

  • Вы также можете сопоставить существующие переменные среды с секретами. Например, следующий env метод сопоставляет переменную среды с MONALISA именем OCTOCATсекрета.

    Ruby
    env "MONALISA", secret("OCTOCAT")

    При этом будет настроена ссылка на секрет, именованный OCTOCAT в преобразованном рабочем процессе. Чтобы секрет работал, необходимо создать секрет в репозитории GitHub. Дополнительные сведения см. в разделе Использование секретов в GitHub Actions.

  • Вы также можете использовать регулярные выражения для одновременного обновления значений нескольких переменных среды. Например, следующий настраиваемый преобразователь удаляет все переменные среды из преобразованного рабочего процесса:

    Ruby
    env /.*/, nil

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

    Ruby
    env /^(.+)_SSH_KEY/, secret("%s_SSH_KEY)

    Примечание. Порядок env определения методов при использовании регулярных выражений. Первый env преобразователь, соответствующий имени переменной среды, имеет приоритет над последующими env методами. Сначала следует определить наиболее конкретные преобразователи переменных среды.

Части были адаптированы в соответствии с https://github.com/github/gh-actions-importer/ лицензией MIT:

MIT License

Copyright (c) 2022 GitHub

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.