Сведения о пользовательских преобразователях
GitHub Actions Importer предоставляет возможность расширения встроенного сопоставления путем создания пользовательских преобразователей. Пользовательские преобразователи можно использовать для:
- Преобразование элементов, которые GitHub Actions Importer не преобразует автоматически, или изменяет способ преобразования элементов. Дополнительные сведения см. в разделе Создание пользовательских преобразователей для элементов.
- Преобразуйте ссылки в средства выполнения, чтобы использовать различные метки средств выполнения. Дополнительные сведения см. в разделе Создание пользовательских преобразователей для средств выполнения.
- Преобразуйте значения переменных среды из существующих конвейеров в рабочие процессы GitHub Actions. Дополнительные сведения см. в разделе Создание пользовательских преобразователей для переменных среды.
Использование пользовательских преобразователей с GitHub Actions Importer
Пользовательский преобразователь содержит логику сопоставления, которую GitHub Actions Importer может использовать для преобразования подключаемых модулей, задач, меток средств выполнения или переменных среды для работы с GitHub Actions. Пользовательские преобразователи написаны на языке DSL, созданном на основе Ruby, и определяются в файле с расширением .rb
файла.
С помощью --custom-transformers
параметра CLI можно указать, какие файлы пользовательского audit
преобразователя следует использовать с командами , dry-run
и migrate
.
Например, если пользовательские преобразователи определены в файле с именем transformers.rb
, можно использовать следующую команду, чтобы использовать их с GitHub Actions Importer:
gh actions-importer ... --custom-transformers transformers.rb
Кроме того, можно использовать синтаксис шаблона glob, чтобы указать несколько пользовательских файлов преобразователя. Например, если несколько пользовательских файлов преобразователя находятся в каталоге с именем 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
Приведенный выше пример приводит к следующему шагу рабочего процесса 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
метод, который преобразует одну метку средства выполнения в одну метку GitHub Actions в результирующем рабочем процессе.
runner "linux", "ubuntu-latest"
Метод также можно использовать для runner
преобразования одной метки средства выполнения в несколько меток GitHub Actions в итоговом рабочем процессе.
runner "big-agent", ["self-hosted", "xl", "linux"]
GitHub Actions Importer пытается сопоставить метку средства выполнения, как это возможно. В случаях, когда это невозможно, ubuntu-latest
метка средства выполнения тестов используется в качестве значения по умолчанию. Для управления этим значением по умолчанию можно использовать специальное ключевое runner
слово с методом . Например, следующий пользовательский преобразователь указывает GitHub Actions Importer использовать macos-latest
в качестве средства выполнения по умолчанию вместо ubuntu-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"
Можно также удалить все экземпляры определенной переменной среды, чтобы они не преобразовылись в рабочий процесс GitHub Actions. В следующем примере удаляются все переменные среды с именем
MONA_LISA
.Ruby env "MONA_LISA", nil
-
Вы также можете сопоставить существующие переменные среды с секретами. Например, следующий
env
метод сопоставляет переменную среды с именемMONALISA
с секретом с именемOCTOCAT
.Ruby env "MONALISA", secret("OCTOCAT")
При этом будет настроена ссылка на секрет с именем
OCTOCAT
в преобразованном рабочем процессе. Чтобы секрет работал, необходимо создать секрет в репозитории GitHub. Дополнительные сведения см. в разделе Зашифрованные секреты. -
Можно также использовать регулярные выражения для одновременного обновления значений нескольких переменных среды. Например, следующий пользовательский преобразователь удаляет все переменные среды из преобразованного рабочего процесса:
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.