Sobre transformadores personalizados
GitHub Actions Importer oferece a capacidade de estender seu mapeamento interno criando transformadores personalizados. Os transformadores personalizados podem ser usados para:
- Converta itens que GitHub Actions Importer não convertem automaticamente ou modificam como os itens são convertidos. Para obter mais informações, confira "Como criar transformadores personalizados para itens".
- Converta referências em executores para usar rótulos de executores diferentes. Para obter mais informações, confira "Como criar transformadores personalizados para executores".
- Converta valores de variáveis de ambiente de seus pipelines existentes em fluxos de trabalho de GitHub Actions. Para obter mais informações, confira "Como criar transformadores personalizados para variáveis de ambiente".
Usando transformadores personalizados com GitHub Actions Importer
Um transformador personalizado contém a lógica de mapeamento que GitHub Actions Importer pode usar para transformar seus plug-ins, tarefas, rótulos de executor ou variáveis de ambiente para trabalhar com GitHub Actions. Os transformadores personalizados são gravados com uma DSL (linguagem específica de domínio) criada com base no Ruby e são definidos em um arquivo com a extensão de arquivo .rb
.
Você pode usar a opção da CLI --custom-transformers
para especificar quais arquivos de transformador personalizados usar com os comandos audit
, dry-run
e migrate
.
Por exemplo, se os transformadores personalizados forem definidos em um arquivo chamado transformers.rb
, você poderá usar o seguinte comando para usá-los com GitHub Actions Importer:
gh actions-importer ... --custom-transformers transformers.rb
Como alternativa, você pode usar a sintaxe de padrão glob para especificar vários arquivos de transformador personalizados. Por exemplo, se vários arquivos de transformador personalizados estiverem dentro de um diretório chamado transformers
, você poderá fornecê-los a GitHub Actions Importer com o seguinte comando:
gh actions-importer ... --custom-transformers transformers/*.rb
Observação: quando você usa transformadores personalizados, os arquivos de transformador personalizados devem residir no mesmo diretório ou em subdiretórios, no local no qual o comando gh actions-importer
é executado.
Criar transformadores personalizados para itens
Você pode criar transformadores personalizados que o GitHub Actions Importer usará ao converter etapas de compilação ou gatilhos existentes no seu equivalente em GitHub Actions. Isso é especialmente útil quando:
- GitHub Actions Importer não converte automaticamente um item.
- Você deseja alterar como um item é convertido por GitHub Actions Importer.
- Os pipelines existentes usam extensões personalizadas ou proprietárias, como bibliotecas compartilhadas no Jenkins, e você precisa definir como essas etapas devem funcionar em GitHub Actions.
GitHub Actions Importer usa transformadores personalizados definidos usando uma DSL criada com base no Ruby. Para criar transformadores personalizados para etapas de compilação e gatilhos:
- Cada arquivo de transformador personalizado deve conter pelo menos um método
transform
. - Cada método
transform
deve retornar umHash
, uma matriz deHash
ounil
. Esse valor retornado corresponderá a uma ação definida no YAML. Para obter mais informações sobre ações, confira "Entendendo o GitHub Actions".
Exemplo de transformador personalizado para uma etapa de compilação
O seguinte exemplo converte uma etapa de compilação que usa o identificador "buildJavaScriptApp" para executar vários comandos 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
O exemplo acima resulta na etapa de fluxo de trabalho a seguir do GitHub Actions. Ele é composto por etapas de compilação convertidas que tinham um identificador buildJavaScriptApp
:
- name: build javascript app
run: |
npm run build
npm run package
npm run deploy
O método transform
usa o identificador da etapa de compilação da instância de CI/CD de origem em um argumento. Neste exemplo, o identificador é buildJavaScriptLibrary
. Você também pode usar valores separados por vírgulas para passar vários identificadores para o método transform
. Por exemplo, transform "buildJavaScriptApp", "buildTypeScriptApp" { |item| ... }
.
Observação: a estrutura de dados de item
será diferente dependendo da plataforma de CI/CD e do tipo de item que está sendo convertido.
Criar transformadores personalizados para executores
Você pode personalizar o mapeamento entre executores em sua instância de CI/CD de origem e seus executores equivalentes de GitHub Actions.
GitHub Actions Importer usa transformadores personalizados definidos usando uma DSL criada com base no Ruby. Para criar transformadores personalizados para executores:
- O arquivo de transformador personalizado deve ter pelo menos um método
runner
. - O método
runner
aceita dois parâmetros. O primeiro parâmetro é o rótulo do executor da instância de CI/CD de origem e o segundo parâmetro é o rótulo do executor correspondente GitHub Actions. Para obter mais informações sobre executores do GitHub Actions, consulte "Usar executores hospedados no GitHub".
Exemplo de transformadores personalizados para executores
O exemplo a seguir mostra um método runner
que converte um rótulo de executor em um rótulo de executor GitHub Actions no fluxo de trabalho resultante.
runner "linux", "ubuntu-latest"
runner "linux", "ubuntu-latest"
Você também pode usar o método runner
para converter um rótulo de executor em vários rótulos de executores GitHub Actions no fluxo de trabalho resultante.
runner "big-agent", ["self-hosted", "xl", "linux"]
runner "big-agent", ["self-hosted", "xl", "linux"]
GitHub Actions Importer tenta mapear o rótulo do executor da melhor maneira possível. Nos casos em que ele não pode fazer isso, o rótulo do executor ubuntu-latest
é usado como padrão. Você pode usar uma palavra-chave especial com o método runner
para controlar esse valor padrão. Por exemplo, o transformador personalizado a seguir instrui GitHub Actions Importer a usar macos-latest
como o executor padrão em vez de ubuntu-latest
.
runner :default, "macos-latest"
runner :default, "macos-latest"
Criar transformadores personalizados para variáveis de ambiente
Você pode personalizar o mapeamento entre as variáveis de ambiente dos pipelines de CI/CD de origem para os valores em GitHub Actions.
GitHub Actions Importer usa transformadores personalizados definidos usando uma DSL criada com base no Ruby. Para criar transformadores personalizados para variáveis de ambiente:
- O arquivo de transformador personalizado deve ter pelo menos um método
env
. - O método
env
aceita dois parâmetros. O primeiro parâmetro é o nome da variável de ambiente no pipeline original e o segundo parâmetro é o valor atualizado da variável de ambiente para GitHub Actions. Para mais informações sobre as variáveis de ambiente de GitHub Actions, confira "Variáveis".
Exemplo de transformadores personalizados para variáveis de ambiente
Há várias maneiras de configurar os transformadores personalizados para mapear suas variáveis de ambiente.
-
O exemplo a seguir define o valor de qualquer variável de ambiente existente chamada
OCTO
, comoCAT
ao transformar um pipeline.Ruby env "OCTO", "CAT"
env "OCTO", "CAT"
Você também pode remover todas as instâncias de uma variável de ambiente específica para que elas não sejam transformadas em um fluxo de trabalho de GitHub Actions. O exemplo a seguir remove todas as variáveis de ambiente com o nome
MONA_LISA
.Ruby env "MONA_LISA", nil
env "MONA_LISA", nil
-
Você também pode mapear suas variáveis de ambiente existentes para segredos. Por exemplo, o método
env
a seguir mapeia uma variável de ambiente chamadaMONALISA
para um segredo chamadoOCTOCAT
.Ruby env "MONALISA", secret("OCTOCAT")
env "MONALISA", secret("OCTOCAT")
Isso configurará uma referência a um segredo chamado
OCTOCAT
no fluxo de trabalho transformado. Para que o segredo funcione, você precisará criar o segredo no repositório GitHub. Para obter mais informações, confira "Usar segredos em ações do GitHub". -
Você também pode usar expressões regulares para atualizar os valores de diversas variáveis de ambiente ao mesmo tempo. Por exemplo, o seguinte transformador personalizado remove todas as variáveis de ambiente do fluxo de trabalho convertido:
Ruby env /.*/, nil
env /.*/, nil
O exemplo a seguir usa um grupo de correspondência de expressão regular para transformar os valores de variáveis de ambiente em segredos gerados dinamicamente.
Ruby env /^(.+)_SSH_KEY/, secret("%s_SSH_KEY)
env /^(.+)_SSH_KEY/, secret("%s_SSH_KEY)
Observação: a ordem na qual os métodos
env
são definidos importa ao usar expressões regulares. O primeiro transformadorenv
que corresponde a um nome de variável de ambiente tem precedência sobre métodosenv
subsequentes. Você deve definir primeiro os transformadores de variáveis de ambiente mais específicos.
Aviso legal
Partes foram adaptadas do https://github.com/github/gh-actions-importer/ de acordo com a licença 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.