Recentemente em um dos projetos que atuei, precisávamos realizar a migração de todos os work items do backlog do produto entre contas do Azure DevOps. Não conseguimos encontrar uma ferramenta desenvolvida e mantida pela Microsoft que realizasse esta migração de forma automatizada. A Microsoft possui esta ferramenta, que faz a migração do serviço OnPrimisses para nuvem, mas não era o cenário que precisávamos.

Para fazer a migração do backlog entre contas do Azure DevOps nós utilizamos o Azure DevOps Migration Tools. Esta ferramenta é open source e está disponível no GitHub. Vamos ver mais sobre ela no decorrer no post.

Neste post vou explicar como fizemos a migração passo a passo. 

Azure DevOps 

O Azure DevOps é um ferramenta da Microsoft para gerenciamento de todo o ciclo de vida da sua aplicação e projeto. Ela conta com diversas ferramentas para gestão de código fonte, integração contínua, entrega contínua, entre outros. 

Talvez você conheça alguma das versões “antecessoras” do Azure DevOps, como Team Foundation Services (TFS) ou Visual Studio Team System (VSTS)

Caso você não conheça o Azure DevOps, você pode ler mais sobre ele neste endereço.

Azure DevOps Migration Tools

Uma das maneiras que encontramos para realizar a migração dos itens do backlog (user storys, tasks, bugs, etc) foi o Azure DevOps Migration Tools. 

O Azure DevOps Migration Tools é uma ferramenta desenvolvida pela naked Agility Limited’s DevOps & Agility, ela é open source e está disponível no GitHub com licença MIT. 

Esta ferramenta surgiu para migrar dados do TFS para VSTS (citados anteriormente no post) e hoje, com a evolução do produto, ela tem funcionado bem também com o Azure DevOps. Ela é capaz de migrar user storys, tasks, bugs, repositórios, test plans e etc. 

A instalação da ferramenta pode ser feita utilizando o chocolatey ou baixando a release diretamente pelo GitHub. Uma das limitações que você pode encontrar ao utilizar a ferramenta é que ela não é cross platform. A ferramenta é desenvolvida com .NET, roda por linha de comando no PowerShell através de um arquivo .exe

Toda a configuração da ferramenta é feita através de um arquivo JSON, que será lido pelo arquivo .exe. 

Vale lembrar que a ferramenta NÃO é mantida pela Microsoft, então qualquer problema de versão, abra uma issue no repositório da ferramenta no GitHub.

 

O que migrar, o que não migrar e o que não será migrado?

O Azure DevOps Migration Tools é muito útil para automatizar a migração de items backlog, facilitando nossa vida e evitando o famoso CTRL + C e o CTRL + V de cada dia.. 

Um ponto bem interessante para te convencer a usar a ferramenta e não fazer ctrl + c e ctrl + v manualmente, é que a migração dos work items irá levar junto todo o histórico de alterações dos arquivos do código fonte que estiverem vinculados a eles, inclusive as alterações feitas por Pull Requests. 

Além disto ela também possui a opção de migrar os repositórios de forma automatizada. Entretanto, como repositórios possuem configurações bastante específicas e, em um cenário em que muitas pessoas estão comitando, é mais seguro e mais controlado fazer a migração manualmente com o auxilio do GIT.

Outro ponto é que ela não irá migrar suas definições de build e release. O próprio Azure DevOps possui uma opção de exportar/importador bastante simples para isto. 

Mesmo a ferramenta sendo voltada para migração de work items, algumas coisas não serão migradas automaticamente, como personalização de cores, states das user storys, e toda a personalização que você realizou no seu Azure DevOps raiz. 

Usuário e permissões também não serão migrados de forma automática, bem como variáveis secretas.

Configurando o Azure DevOps para a migração

Antes de usarmos o Azure DevOps Migration Tools, vamos precisar fazer algumas configurações no projeto do Azure DevOps atual e no Azure DevOps que irá receber os itens. 

O primeiro passo é criar um tipo de processo personalizado para os dos projeto do Azure DevOps (raiz e destino). Para isto acesse as configurações da organização e clique em Process, selecione a opção do processo desejado (no post utilizaremos Agile) e selecione Create inherited process e nomeie o novo processo. Aqui chamaremos de agile customizado:

Se você tiver dificuldades para alterar/criar o processo customizado, veja este post.

Após isto, vamos precisar criar um campo em cada work item que será responsável por armazenar o estado da migração do work item. Isto será útil para saber qual foi a fonte e em caso de atualização verificar se o work item já foi migrado ou não, isto irá evitar duplicidade. Por padrão, é indicado criar o campo com o nome ReflectedWorkItemId. Para criar o campo acesse Organization Settings > Process  e selecione o agile customizado, que é processo que criamos. 

Após fazer isto você verá uma lista com todos os tipos de work items. O campo ReflectedWorkItemId será criado em cada um deles que você deseja que seja migrado. No post, vamos criar o campo em Bug, Task e User Story. Clique em cada um deles e selecione New Field:

Após adicionar uma vez, basta selecionar o campo já existente para as demais:

OBS: É importante fazer  isto nos dois projetos 

Configurando o Azure DevOps Migration Tools 

Feita a configuração nos projetos do Azure DevOps, agora é hora de configurar o Azure DevOps Migration Tools.

Vamos iniciar instalando a ferramenta pelo chocolatey:

choco install vsts-sync-migrator --version=8.3.0;

Por padrão o Azure DevOps Migration Tools será instalado em C:\tools\VSTSSyncMigration. Acesse a pasta pelo Powershell com o comando:

cd C:\tools\VSTSSyncMigration

Nesta pasta iremos iniciar a ferramenta criando um arquivo JSON de configuração com o comando abaixo  

.\migration.exe init

Toda a migração será guiada pelo arquivo configuration.json que foi gerado pelo comando acima. Neste arquivo iremos informar o endereço do Azure DevOps atual e do que irá receber a os work items, o que iremos migrar, se vamos ou não migrar anexos e etc. 

Vamos configurar a nossa migração! Abra o arquivo configuration.json que está na pasta C:\tools\VSTSSyncMigration no seu editor de texto preferido.

O primeiro passo é configurar quem é nosso Source, ou seja, qual Azure DevOps será a nossa fonte de dados para a migração. Em Collection, preencha com o endereço do seu Azure DevOps de raiz. O campo name é referente ao nome do projeto. No nosso caso, será Raiz. O campo ReflectedWorkItemIDFieldName será o campo responsável por armazenar o status da migração do work item, este é o campo que adicionamos anteriormente neste post. 

Após configurar o Source, iremos configurar também o Target. A forma de configuar é a mesma que fizemos com o Source, mudando que iremos preencher com os dados do Azure DevOps de destino da migração, ou seja, o que irá receber os work items.

Note que a propriedade GitRepoMapping está nula. Isto significa que não iremos migrar os repositórios com esta ferramenta.

Após configurar o Source e o Target, vamos configurar os Processors da ferramenta. São os processors que irão realizar a migração dos itens do Azure DevOps. 

O primeiro processors que temos é o NodeStructuresMigrationConfig. Ele é o processor responsável por migrar as Sprints e as Areas que foram adicionadas ao longo do projeto no Azure DevOps raiz. Para que ele seja executado durante a migração, altere o Enabled para true.

O próximo processor é WorkItemMigrationConfig, ele e o processor responsável por migrar os itens do backlog, como user storys, tasks, bugs, entre outros. Ele possui propriedades bem úteis para a migração, vamos detalhar as principais:

• ReplayRevision: É um propriedade boolena (verdadeiro ou falso) que irá informar para o migrator se você deseja atualizar as revisões do itens ou não;
• UpdateCreatedDate: Nesta propriedade você pode optar por atualizar a data de criação dos work items para a data da mgração ou manter a antiga;
• UpdateCreatedBy: Informe se você deseja atualizar o nome do usuário que criou os itens para o usuário que está realizando a migração;
• QueryBit: Este campo é obrigatório, mesmo que você não queria excluir nenhum item da migração, você deverá preencher este campo de alguma forma. No exemplo do post, iremos excluir os item do tipo Test Suit e Test Plan;
• OrderBit: Campo obrigatório que irá informar para o migrator como devem ser classificados os work items durante a migração;
• Enabled: Este campo irá informar para o migrator se ele deve fazer a migração ou não. Quando tudo estiver configurado corretamnete, vamos atualizar este campo para true;
• AttachmentMigration: Infome se você deseja ou não migrar os anexos dos work items;
• AttachmentWorkingPath: Local onde os anexos dos work items serão salvos temporariamente;

Existem outras popriedades e você pode ver mais sobre cada uma delas no video oficial da ferramenta neste endereço

Após a configuração de cada item, meu JSON ficou da seguinte maneira:

{
  "Version": "8.3",
  "TelemetryEnableTrace": false,
  "workaroundForQuerySOAPBugEnabled": false,
  "Source": {
    "Collection": "https://meuazuredevops.visualstudio.com/",
    "Name": "Raiz",
    "ReflectedWorkItemIDFieldName": "Custom.ReflectedWorkItemId"
  },
  "Target": {
    "Collection": "https://meuazuredevops.visualstudio.com/",
    "Name": "Destino",
    "ReflectedWorkItemIDFieldName": "Custom.ReflectedWorkItemId"
  },
  "FieldMaps": [],
  "WorkItemTypeDefinition": {
    "sourceWorkItemTypeName": "targetWorkItemTypeName"
  },
  "GitRepoMapping": null,
  "Processors": [
    {
      "ObjectType": "VstsSyncMigrator.Engine.Configuration.Processing.NodeStructuresMigrationConfig",
      "PrefixProjectToNodes": false,
      "Enabled": false,
      "BasePaths": []
    },
    {
      "ObjectType": "VstsSyncMigrator.Engine.Configuration.Processing.WorkItemMigrationConfig",
      "ReplayRevisions": false,
      "PrefixProjectToNodes": false,
      "UpdateCreatedDate": false,
      "UpdateCreatedBy": false,
      "UpdateSourceReflectedId": true,
      "BuildFieldTable": false,
      "AppendMigrationToolSignatureFooter": false,
      "QueryBit": "AND [System.WorkItemType] NOT IN ('Test Suite', 'Test Plan')",
      "OrderBit": "[System.ChangedDate] desc",
      "Enabled": true,
      "LinkMigration": true,
      "AttachmentMigration": true,
      "AttachmentWorkingPath": "c:\\temp\\WorkItemAttachmentWorkingFolder\\",
      "FixHtmlAttachmentLinks": false,
      "WorkItemCreateRetryLimit": 5,
      "FilterWorkItemsThatAlreadyExistInTarget": true,
      "PauseAfterEachWorkItem": false
    }
  ]
}

Executando a migração 

Após terminarmos de editar o arquivo configuration.json, e alterarmos para true a propriedade Enabled e cada processor que desejamos que seja executado durante a migração, estamos prontos para iniciar o Azure DevOps Migration Tools.

Acesse a pasta da ferramenta pelo PowerShell e execute da seguinte maneira:

.\migration.exe execute -c configuration.json

O processo de migração irá demorar algumas horas dependendo do tamanho do seu backlog, tenha em mente que quanto maior o backlog, mais tempo a migração irá levar. Mantenha seu nootebook ligado a fonte de energia e a internet para que não ocorra nenhum problema na migração.

Conclusão 

O Azure DevOps Migration Tools apesar de não ser uma ferramenta oficial da Microsoft resolve bem o cenário de mgiração de backlogs. No post optamos por migrar os repositórios manualmente por julgarmos mais seguro. Atente-se com a versão da Azure DevOps Migration Tools que você instalou. Qualquer problema encontrado, abra uma issue no repositório da ferramenta clicando aqui.

—

#Ubuntu