Сведения о пользовательских преобразователях
GitHub Actions Importer предоставляет возможность расширения встроенного сопоставления путем создания пользовательских преобразователей. Пользовательские преобразователи можно использовать для:
- Преобразование элементов, которые GitHub Actions Importer не преобразуются автоматически или изменяют способ преобразования элементов. Дополнительные сведения см. в разделе "Создание пользовательских преобразователей для элементов".
- Преобразуйте ссылки на средства выполнения, чтобы использовать разные метки runner. Дополнительные сведения см. в разделе "Создание настраиваемых преобразователей для бегуней".
- Преобразуйте значения переменных среды из существующих конвейеров в рабочие процессы GitHub Actions. Дополнительные сведения см. в разделе "Создание настраиваемых преобразователей для переменных среды".
Использование пользовательских преобразователей с 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
команд:
transform "buildJavaScriptApp" do |item| command = ["build", "package", "deploy"].map do |script| "npm run #{script}" end { name: "build javascript app", run: command.join("\n") } end
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 в результирующем рабочем процессе.
runner "linux", "ubuntu-latest"
runner "linux", "ubuntu-latest"
Кроме того, runner
можно использовать метод для преобразования одной метки runner в несколько меток runner GitHub Actions меток runner в результирующем рабочем процессе.
runner "big-agent", ["self-hosted", "xl", "linux"]
runner "big-agent", ["self-hosted", "xl", "linux"]
GitHub Actions Importer пытается сопоставить метку runner как можно лучше. В случаях, когда это не удается сделать, ubuntu-latest
метка runner используется в качестве значения по умолчанию. Для управления этим значением по умолчанию можно использовать специальное ключевое слово с методом runner
. Например, следующий настраиваемый преобразователь указывает GitHub Actions Importer использовать macos-latest
в качестве средства выполнения по умолчанию вместо ubuntu-latest
.
runner :default, "macos-latest"
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"
env "OCTO", "CAT"
Можно также удалить все экземпляры определенной переменной среды, чтобы они не преобразовывалися в рабочий процесс GitHub Actions. В следующем примере удаляются все переменные среды с именем
MONA_LISA
.Ruby env "MONA_LISA", nil
env "MONA_LISA", nil
-
Вы также можете сопоставить существующие переменные среды с секретами. Например, следующий
env
метод сопоставляет переменную среды сMONALISA
именемOCTOCAT
секрета.Ruby env "MONALISA", secret("OCTOCAT")
env "MONALISA", secret("OCTOCAT")
При этом будет настроена ссылка на секрет, именованный
OCTOCAT
в преобразованном рабочем процессе. Чтобы секрет работал, необходимо создать секрет в репозитории GitHub. Дополнительные сведения см. в разделе Использование секретов в GitHub Actions. -
Вы также можете использовать регулярные выражения для одновременного обновления значений нескольких переменных среды. Например, следующий настраиваемый преобразователь удаляет все переменные среды из преобразованного рабочего процесса:
Ruby env /.*/, nil
env /.*/, nil
В следующем примере используется группа сопоставления регулярных выражений для преобразования значений переменных среды в динамически созданные секреты.
Ruby env /^(.+)_SSH_KEY/, secret("%s_SSH_KEY)
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.