Foundation: Gerência de Configuração

Este documento tem por objetivo documentar toda a estratégia de backup utilizada pela Basis, bem como estabelecer critérios de backup e evidenciar a realização da prática através de relatórios, apontando problemas e correções.

Considera-se no escopo deste documento abordar todas as etapas e procedimentos que são necessários para a construção efetiva de um backup, tal como as configurações e breves explicações sobre o funcionamento de ferramentas envolvidas.

Estão fora do limite definido como escopo deste documento dados de máquinas cujo backup é realizado pelas ferramentas listadas, informações inerentes à configuração e conexão da VPN da Basis, bem como de acesso remoto à máquina do Bacula, ou especificidades desnecessárias ao contexto.

O Director (bacula-dir.conf) é a parte mais complexa do sistema, em que se figura toda a configuração dos trabalhos de backup (job), agendamentos, pools, seleção dos alvos de backup (FileSet), definição do tipo de armazenamento, etc. Em suma, configuram-se os clientes e arquivos que farão parte do backup, além de realizar a comunicação entre os clientes e dispositivos de armazenamento.

File Daemon (bacula-fd.conf). Todos os clientes que possuem esse daemon em execução estabelecem uma comunicação com o Director, que por sua vez gerencia todas as máquinas e redireciona os dados destas para o Storage.

Storage Daemon (bacula-sd.conf) é o arquivo de configuração do Bacula, em que se relacionam os dispositivos de armazenamento, como fitas e discos, de forma a organizar os dados armazenados advindos do Director. Esse agente estabelece a comunicação com tais dispositivos, armazenando ou recuperando os arquivos específicos de cada cliente.

Este documento tem por objetivo documentar toda a estratégia de integração contínua, bem como a verificação por pares e testes de software utilizados pela Basis no desenvolvimento de seus projetos, bem como estabelecer critérios de integração e evidenciar a realização da prática através de relatórios de integração, apontando problemas e correções.

Considera-se no escopo deste documento abordar todas as etapas e procedimentos que são necessários para a verificação por partes dos artefatos elaborados pela Análise e Design dos projetos de desenvolvimento, a construção efetiva de um sistema, através de integração contínua, tal como as configurações de ferramentas envolvidas e breves explicações sobre seus funcionamentos e os procedimentos utilizados para testar o produto nos ambientes de desenvolvimento, integração e pretendido para o uso.

Estão fora do limite definido como escopo deste documento as informações inerentes à configuração e conexão da VPN da Basis, bem como de acesso remoto à máquina do Jenkins e seus slaves, ou suas especificidades desnecessárias ao contexto.

A verificação por pares é executada para identificar defeitos nos requisitos, na arquitetura e no desenvolvimento do produto antes que estes sejam formalizados como código fonte estável, de forma que o custo para resolução seja mais baixo e a solução mais efetiva, garantindo a integridade da informação ao longo do ciclo de vida do software.

A Basis realiza verificações por pares em seus produtos através da técnica de Inspeção, onde um revisor fará uma inspeção com base em critérios, nos produtos selecionados.

São efetuadas inspeções em requisitos, na arquitetura do produto e no código-fonte do mesmo, com base em critérios definidos nas ferramentas SGO e Git. No momento da inspeção, a tarefa deve ser atribuída ao revisor, que deverá então analisar os documentos à luz dos critérios padronizados. Caso problemas sejam identificados, estes poderão ser relatados no texto de observação existente no checklist, bem como em evidências de captura de tela, quando pertinente.

Em todas as revisões por pares o revisor deve se preocupar em:

Executam-se inspeções em requisitos, representados pelas especificações funcionais de Casos de Uso ou Especificações por Exemplo (EPEs), de acordo com a opção do projeto. As inspeções são feitas com base em critérios definidos na ferramenta SGO, para cada tarefa de implementação.

As mesmas poderão ser efetuadas por amostragem, quando a quantidade de Casos de Uso ou EPEs for grande (maior que 10). Nestes casos, poderá se optar por realizar apenas a revisão de parte das especificações funcionais, ficando a cargo do revisor essa decisão. Recomenda-se que nestes casos a escolha leve em consideração:

Executam-se inspeções na arquitetura do produto, na qual o revisor é um par do elaborador das especificações. As inspeções são feitas com base em critérios definidos na ferramenta SGO, para cada ordem de serviço.

Executam-se inspeções no código-fonte a ser integrado à branch principal do repositório Git do sistema em questão. As inspeções são feitas com base na checklist de validação de Merge Request, evidenciada na própria criação do Merge Request no repositório, e definida na seção Qualidade.

A Integração Contínua é uma prática recente na engenharia de software, que consiste, resumidamente, em unificar todas as cópias de trabalho de cada desenvolvedor, várias vezes ao dia, em um ambiente centralizado e compartilhado. Ela ganhou grande importância na comunidade de desenvolvimento de software devido ao grande impacto causado pelas metodologias ágeis, sendo ela um dos pilares de tal agilidade e garantindo que todo o sistema funcione de forma correta em cada nova construção (build), mesmo que a equipe envolvida seja grande e diversas partes do código estejam sendo alteradas ao mesmo tempo.

Uma grande vantagem da integração contínua é a repercussão instantânea. A cada commit no repositório, a build é automaticamente realizada, executando testes e detectando falhas. Se o código de algum commit não compilar ou não passar em algum dos testes, a equipe envolvida toma conhecimento instantaneamente através de um E-mail, por exemplo, que aponta as falhas detectadas e o commit que contém o código defeituoso, possibilitando assim uma correção imediata.

O processo de integração envolve três equipes principais, todos com responsabilidades, objetivos e procedimentos bem definidos:

O Jenkins é uma ferramenta de Integração Contínua projetada para realizar builds automáticas de múltiplos projetos (definidos em configurações individuais nomeadas Jobs), a partir de gatilhos pré-definidos; periódicos, específicos ou a cada novo commit no repositório associado. Baseado em Java, ele permite restringir o acesso de usuários às Jobs, e possui vários plugins instaláveis para melhor atender às necessidades específicas de projetos. Sua construção garante que apenas builds de sucesso sejam publicadas em produção.

No ambiente Basis, o Jenkins, acessível pelo endereço https://cje-master1.basis.com.br/, possui uma estrutura padronizada de acesso a jobs de clientes. As pastas de acesso consistem em "Cliente/Sistema/Ambiente", e possuem acesso restrito aos grupos de recursos Basis associados àqueles clientes específicos.

A ação da construção de fato é dividida em agents, também conhecidos como slaves, que são máquinas individuais, executando construções em paralelo. Todos os agents são gerenciados no servidor central, Jenkins Master, responsável por configurar os jobs, atribuindo-lhes opções específicas de inicialização, e por direcionar as builds, disponibilizando-as em agents livres. Os agents, bem como certas ferramentas comuns do Jenkins como versões de Java e Maven, são configurados em uma instância de controle de Jenkins Masters, o Jenkins Operation Center, acessível em https://joc.basis.com.br/.

Versões mais recentes do Jenkins aplicam o conceito de Pipeline às jobs. Uma pipeline de entrega contínua no Jenkins consiste em um processo complexo de construção do software de maneira confiável e repetida, normalmente separada em estágios para melhor controle. Tais pipelines são elaboradas via código, utilizando uma sintaxe específica conhecida como Domain-specific Language (DSL), e podem ser colocadas ou em um arquivo Jenkinsfile dentro do próprio repositório de código, ou na configuração da job no Jenkins, ou em um Job Template.

Um Job Template no Jenkins consiste em uma configuração fixa e padronizada de jobs, de tal forma que qualquer job que seja criada a partir desse template só necessita de alguns parâmetros a configurar, em vez de uma configuração completa. Os templates do Jenkins Basis aplicam parâmetros específicos em pipelines, de forma a manter as jobs uniformemente configuradas.

Os templates do ambiente Basis possuem também uma funcionalidade associada ao SonarQube, de modo a realizar avaliações de qualidade de código toda vez que uma nova build é executada. Se o código sendo construído ficar aquém de um limite fixo de qualidade de código, o chamado Quality Gate, a construção é interrompida, exigindo a revisão do código pelos desenvolvedores de forma a eliminar os problemas de qualidade recém surgidos.

Apache Maven, ou simplesmente Maven, é uma ferramenta de automação de compilação utilizada primariamente em projetos Java. O Maven utiliza um arquivo XML (POM) para descrever o projeto de software em construção, bem como suas dependências de módulos e componentes externos, ordem de compilação dos mesmos, diretórios e plugins necessários. Ele possui objetivos pré-definidos para realizar tarefas específicas, como compilação e empacotamento de código.

O Maven adquire bibliotecas Java e seus plugins dinamicamente de um ou mais repositórios, como o próprio repositório central Maven ou o Nexus Basis, e armazena-os em uma área de cache local. Esse cache pode também ser atualizado com artefatos criados por projetos locais.

O Jenkins utiliza o Maven como concentrador de comandos e variáveis para integração contínua. O arquivo POM é lido para ajustar os deploys da integração a partir do plugin Cargo, bem como a migração do banco de dados a partir do Liquibase ou Flyway.

Docker é uma plataforma Open Source, que facilita a criação e administração de ambientes isolados. O Docker possibilita o empacotamento de uma aplicação ou ambiente inteiro dentro de um container, e a partir desse momento o ambiente inteiro torna-se portável para qualquer outro Host que contenha o Docker instalado. Isso reduz drasticamente o tempo de deploy de alguma infraestrutura ou até mesmo aplicação, pois não há necessidade de ajustes de ambiente para o correto funcionamento do serviço, o ambiente é sempre o mesmo, configurado uma vez e replicado quantas vezes quiser.

O backend padrão do Docker é o LXC. Com isso é possível definir limitações de recursos por container (memória, cpu, I/O, etc.)

Vantagens:

As construções do Jenkins que utilizem um template relativo a Docker criam imagens a partir dos códigos-fonte e enviam para repositórios internos no Nexus, para que sejam utilizadas em suas máquinas respectivas. Nossas máquinas Docker, ou Docker Hosts, são separadas por cliente, mantidas e organizadas via Rancher.

O Rancher consiste numa plataforma de operação do Docker, provendo uma interface gráfica intuitiva e várias funcionalidades que facilitam a manutenção de hosts e containers. Entre elas, o gerenciamento de redes e balanceamento de carga entre hosts, criação e manutenção de volumes de armazenamento, facilitação de uso de recursos do próprio Docker, elaboração de catálogos contendo pilhas de serviços Docker para execução direta, visualização de logs, execução de comandos, entre outros.

Uma pilha de serviços no Rancher normalmente comprime tudo o que é necessário para a execução de um sistema. É composta por um ou mais containers Docker, que se comunicam entre si através de redes internas estabelecidas pelo próprio Rancher.

As construções do Jenkins que utilizem um template relativo a Docker fazem a atualização dos serviços específicos relativos aos seus sistemas diretamente no Rancher, através de um plugin desenvolvido internamente. Portanto, não há necessidade de interação com o Rancher uma vez que os serviços estejam corretamente configurados, o próprio Jenkins se encarrega dos demais processos de atualização.

O SonarQube, anteriormente conhecido simplesmente como Sonar, é uma plataforma aberta de gerenciamento de qualidade de código. Abrangendo várias linguagens e métodos, o SonarQube provê estatísticas relativas à codificação de cada sistema, apresentando resultados de testes unitários e de integração, avaliação de código duplicado, documentação, complexidade, e apontando diversos problemas encontrados no código ao longo do tempo.

A integração do SonarQube com o Jenkins é direta, feita através de um plugin que adiciona um passo de pós-build à job desejada, bastando também adicionar testes e referências no POM relativo ao projeto. O sucesso em uma build configurada desta forma já coloca o código no ambiente do SonarQube, para posterior avaliação dos resultados.

Em nosso ambiente padrão de qualidade de código, acessível pelo endereço https://codequality.basis.com.br/, o SonarQube possui um Quality Gate, um “limite de qualidade” específico para cada tipo de avaliação. A BASIS define um limite de qualidade minimo padrão para seus projetos. Esses limites podem ser alterados de acordo com os níveis acordados em contrato, sendo necessária intervenção no código caso fique abaixo de tal. Este nível de qualidade deve ser garantido pelos responsáveis pelo desenvolvimento e será verificado no momento da geração das baselines de código-fonte.

Existe também um ambiente separado para verificação de qualidade imediata em builds do Jenkins. Acessível via https://codequality-build.basis.com.br/, esta instância do SonarQube possui um Quality Gate voltado especificamente para verificação de novos problemas que tenham surgido em cada uma das construções realizadas no Jenkins, bloqueando a continuidade das mesmas enquanto o problema não for resolvido.

Existem dois tipos de repositórios utilizados na configuração dos projetos de integração: os repositórios de código-fonte de cada sistema (Git – http://gitlab.basis.com.br) e o repositório interno referente às bibliotecas a serem utilizadas pelo Maven, NPM, Bower, bem como às imagens Docker (Nexus – http://element.basis.com.br). No Git, utilizado como ferramenta de controle de versão, armazenam-se a documentação e o código-fonte de cada sistema. Código este em que se encontra o pom.xml, responsável por fornecer os parâmetros do Maven. O Nexus é responsável pelas bibliotecas do Maven, a partir das quais os comandos de construção são executados, bem como por Docker Registries privados, onde se armazenam imagens Docker construídas e utilizadas pelo Jenkins para uso nos ambientes Basis.

Cargo é um empacotador que permite a manipulação de diversos tipos de servidores de aplicações, como Java EE, de maneira padronizada. No Maven, ele funciona como um plugin para configurar, iniciar, parar ou implantar aplicativos em seus devidos servidores. Para chamá-lo no Jenkins, utiliza-se a opção cargo:redeploy, e seus parâmetros serão lidos do pom.xml. O Cargo é normalmente utilizado em projetos de arquitetura antiga, onde não se utiliza o Docker.

Para sistemas construídos pela Basis que necessitem de banco de dados, utilizamos ferramentas que possibilitem uma migração automatizada e controlada de forma simples. Tais ferramentas de migração de banco de dados são integradas ao Maven como um plugin, e podem ser executadas tanto em cada construção do sistema quanto na inicialização do mesmo. Funcionam com scripts SQL padrão ou no formato XML, e são compatíveis com os principais bancos de dados.

Tal abordagem tem como motivações:

A depender do projeto, escolhe-se uma das duas ferramentas abaixo: Liquibase ou Flyway.

A preparação determina um planejamento para a sequência de integração, o estabelecimento do ambiente de integração, os itens de software a serem integrados, bem como procedimentos e critérios para a integração do produto. A definição da estratégia e das ferramentas que serão utilizadas no projeto é registrada e aprovada no Documento de Arquitetura de Software dos projetos.

A compatibilidade entre interfaces é garantida através da execução e manutenção de práticas como a revisão das descrições de interfaces internas e externas, evidenciando quaisquer alterações por rastreamento.

Executa-se, por fim, o planejamento de integração elaborado inicialmente, de forma a evidenciar por fim a disponibilidade dos componentes do produto para integração.

Para que a integração possa ocorrer de maneira completa, há três ambientes que devem estar preparados previamente:

Acessível pelos projetos específicos listados no site https://gitlab.basis.com.br/, necessita minimamente de arquivos base para inicialização das builds, como um POM, e de scripts de banco para execução do Liquibase ou Flyway. Acessos são restritos à equipe de cada sistema.

Configurado pela equipe de banco e acessível também à equipe de configuração, deve ter suas configurações de acesso e especificidades colocadas no código e nos próprios ambientes de desenvolvimento. O tipo de banco varia de acordo com o projeto.

Criados pela equipe de configuração a partir de uma tarefa repassada pelo gestor, logo após a aprovação da proposta de trabalho relativa ao sistema. Consistem em containers Docker empilhados no Rancher, ou máquinas virtuais que possuem os requisitos de hardware e software mínimos para aplicação do código e associação com o banco de dados.

Faz-se necessário, por fim, a configuração de uma job no Jenkins propriamente dito, realizada pela equipe de configuração. Acessando o endereço apontado na sessão Jenkins, com nome e senha específicos de usuário, temos a tela inicial do ambiente:

A partir desta tela, a equipe de configuração seleciona um projeto do cliente desejado dentre os já existentes, organizados em pastas. Caso não haja ainda uma pasta do cliente específico, uma nova pode ser criada no botão Novo job, ou New Item, e selecionando o tipo Folder.

Na configuração que segue, por padrão, se estabelece o nome do cliente, possivelmente um nome de exibição com mais detalhamento, e uma variável de ambiente DOCKER_REGISTRY, para direcionamento das jobs ao repositório Docker associado ao mesmo.

Uma vez dentro da pasta do cliente, seguem-se procedimentos semelhantes para criação das pastas do sistema propriamente dito, e das instâncias separadas de DES/TST/HOM que forem necessárias. O destaque a ser feito para este ponto do processo é que, da mesma forma que a pasta do cliente possui uma variável de ambiente DOCKER_REGISTRY para direcionamento das imagens do Docker, as pastas de cada sistema devem ter também uma variável, GRUPO, para que as imagens tenham um subgrupo específico do sistema em questão.

Dentro da pasta final, por padrão seguindo a estrutura Cliente/Sistema/Ambiente, podem ser criadas as jobs de construção de fato. Para tal, clica-se em New Item, seleciona-se o nome e o tipo ou template de job a ser configurada. Supondo uma construção de um container Docker para o backend de um sistema, por exemplo, seleciona-se o Template Docker Backend.

Na tela que segue, toda a configuração acerca do sistema em questão é realizada, incluindo, entre os detalhes mais importantes, a definição do repositório a usar-se para o código, utilizando endereço de acesso SSH com as credenciais estabelecidas na configuração do próprio Jenkins, a automatização de construções baseada em frequência de atualizações do repositório, os parâmetros do Maven utilizados na build, como escolha de um profile do POM. Os parâmetros de configuração da job possuem um ícone de ajuda para maior esclarecimento sobre a utilidade de cada parâmetro.

Diferentes sistemas podem exigir diferentes configurações ou templates, incluindo jobs mais abertas que não utilizem templates propriamente. O padrão para todos, independente das configurações individuais de sistema, é utilizar os repositórios Git corretos, selecionando a branch master por padrão, e ativar a consulta periódica do SCM para ambientes de desenvolvimento. Dessa forma, sempre que houver um novo commit no repositório de código do sistema, uma build será automaticamente executada.

No caso de jobs específicas para verificação de qualidade, deve ser utilizado o Template Sonar. A job em questão terá seu foco em testes que estejam configurados para aquele cliente/sistema, para atestar qualidade e erros de código. Vale constar que existem dois Templates Sonar principais, sendo o segundo o Template Sonar Branch. Este possui como diferencial a parametrização da branch do repositório que será usada na execução manual da job, sendo que o primeiro foca numa única branch, definida na configuração, e roda automaticamente e periodicamente.

Configurados e salvos os detalhes da job, as construções do sistema podem ser realizadas. Na tela padrão da job, clicando em Construir agora, uma nova build é iniciada. Todos os usuários com acesso ao Jenkins e às pastas específicas dos clientes, requisitado pelo gestor, podem executar builds e visualizar os detalhes da execução.

Na seção “Histórico de builds”, clicando nos detalhes da build em execução, ou mesmo em alguma previamente executada, é exibida a tela de detalhes da build em questão, incluindo detalhes da alteração no repositório que iniciou sua execução.

Ainda dentro da tela da build, selecionando Saída do console, ou a partir de outra tela que exiba o progresso atual das builds do Jenkins, ao clicar na barra de progressão das mesmas, é possível ver o log de execução da construção em tempo real.

Se a build finalizar em vermelho, houve algum problema em sua execução, e o log deve ser examinado para determinar a solução. Nesse caso, o sistema não é construído e fica inacessível em sua versão mais recente.

Se finalizar em azul, o sistema foi corretamente construído de acordo com os parâmetros de configuração anteriormente especificados e deve estar acessível por seu link ao ambiente específico.

Se a build finalizar em amarelo, a construção terminou de modo instável. Isso indica que algo na construção não saiu como esperado e pode acarretar em problemas no sistema. Também cabe investigar os logs para determinar se a situação necessita de reparo.

Independente do resultado das builds, quando esta é finalizada, as equipes de configuração e gestão são informadas por e-mail e por chat, de acordo com a configuração da própria job. O e-mail inclui o resultado da build e a saída de log da build em questão.

Para solucionar o problema apontado na build, o executor da mesma inicialmente examina o log. Se o erro apontado for algo relativo a seu próprio trabalho, ele mesmo faz as devidas alterações, seja em código ou ambiente, e realiza uma nova build. Caso o erro não faça parte da sua própria jurisdição, ele deve abrir uma ocorrência no SGO para direcionar o erro à equipe responsável por tal departamento.

Os commits deverão obdecer a seguinte regra:

Onde:

Somente os membros da equipe de gestão de configuração podem alterar meta-dados (propriedades no sistema de controle de versão) dos artefatos. No GIT deve-se informar a OS que esta trabalhando para a alteração do documento ao fazer o commit/push.

Os itens de Melhoria são armazenados em um repositório próprio: Projeto de Melhoria

A pasta de Estatísticas é dividida por Baselines, sendo que cada nova Baseline terá uma pasta específica associada.

A partir da Baseline BASIS_BL_ORG_06, a Biblioteca é inteiramente elaborada em AsciiDoc e publicada no site http://foundation.basis.com.br.

Todos os itens da Biblioteca de Ativos têm controle formal e são obrigatórios.

O software TortoiseGit é uma de várias possíveis interfaces gráficas para Git no Windows. Ele pode ser baixado em sua versão mais recente no site: https://tortoisegit.org/download/. Para que o TortoiseGit funcione corretamente, faz-se necessária a instalação do Git for Windows, no site: http://git-scm.com/download/win. Apenas após a instalação do mesmo, o TortoiseGit deve ser instalado. Atenção à versão baixada (32-bit ou 64-bit), que deve obedecer às especificações da sua máquina para as duas instalações.

Usando o Windows Explorer, na pasta onde se deseja manter o repositório local, clica-se com o botão direito. No menu de contexto, a opção "Git Clone" deve ser selecionada.

Na janela que segue, no campo URL, deve ser colado o link de clone copiado da página de repositório do Gitlab. Se o link já estiver previamente copiado, deve aparecer automaticamente no campo.

Da primeira vez que se faz qualquer operação num repositório, o TortoiseGit exige informações de usuário. Basta colocar o nome de usuário e e-mail Basis, e clicar em OK.

O nome de usuário e a senha da rede devem ser digitados para validar o clone.

Os mesmos ficarão salvos no Gerenciador de Credenciais do Windows, caso precisem ser alterados.

Após a confirmação da senha, uma tela será exibida informando o progresso do clone.

Ao concluir, o repositório já estará localmente replicado na máquina do usuário.

O Git oferece a opção de clone dos repositórios via HTTPS, como já foi apresentado, ou via SSH. O SSH costuma ser mais prático e menos limitado que o HTTPS, mas necessita de várias configurações locais e remotas para funcionar devidamente.

Inicialmente, deve ser gerada uma chave SSH localmente na sua máquina. Para tanto, vamos usar a interface padrão de console do Git for Windows, que também serve como alternativa ao próprio TortoiseGit, se for mais interessante usar comandos de linha diretamente em vez de uma interface gráfica.

Na máquina local, buscar, no menu Iniciar ou na barra de buscas do Windows, o programa Git Bash. A janela inicial será um console em preto:

Digitar o seguinte, e pressionar Enter:

O console vai pedir, na ordem:

Acessando o caminho da chave no Windows, devem haver dois arquivos: id_rsa e id_rsa.pub. O segundo deve ser aberto em qualquer editor de texto, para que se possa copiar a chave.

Com a chave em mãos, entrar no Gitlab, e adentrar a seção "Configurações", no menu do canto superior direito.

Ali dentro, selecionar no menu esquerdo "Chaves SSH". Na seção que se abrir, colar a chave do id_rsa.pub, dar um título para identificar a chave, então clicar no botão "Adicionar Chave" abaixo.

Feita a adição com sucesso, a última coisa que precisa ser feita é uma alteração local do programa utilizado para SSH no TortoiseGit. No menu iniciar ou de busca, procurar por Settings, um programa que tenha o ícone do TortoiseGit. Entrando no mesmo, selecionar o item Network no menu esquerdo. Ali dentro em SSH, basta colocar o caminho do executável SSH do Git for Windows (por padrão, C:\Program Files\Git\usr\bin\ssh.exe, variando o início do caminho de acordo com a sua pasta de instalação) e clicar em OK.

Feito isso, operações de repositório já podem ser realizadas usando SSH. Basta fazer o clone do repositório utilizando o link SSH que o mesmo fornece na página do repositório.

Dentro da página no Gitlab do repositório que se deseja copiar, clicar em Fork, no canto superior direito.

Selecionar como namespace o próprio nome de usuário, apresentado por padrão na página.

O repositório será criado e toda a estrutura de commits passará por uma importação. Uma vez finalizada, o repositório apresentará a mesma exata estrutura que o original. Desse ponto em diante, as ações de clone e push seguirão os mesmos princípios já apresentados.

Para que o código atualizado no fork seja replicado no repositório original, é necessário que seja aberto um merge request a partir do fork, apontando para a branch do repositório original. Esse merge request precisa ser aberto por um usuário que tenha acesso de escrita no repositório original, e é necessário que haja mais de um commit para o merge, pois será realizado um git squash. Caso seja aberto pelo próprio dono do Fork, que possui acesso somente leitura ao original, ou caso possua apenas um único commit, será fechado imediatamente pelo próprio sistema.

Na tela do repositório fork, no menu esquerdo, clicar em "Merge Requests".

Dentro da tela, haverá um botão "Novo Merge Request". Selecionando o mesmo, será aberta uma nova tela para seleção de quais branches e repositórios servirão como origem e destino. Para origem ("Source Branch"), selecionar o seu fork e a branch onde se trabalhou. Para destino, selecionar o repositório original, e a branch do mesmo onde o merge deverá ser feito. Clicar em "Compare branches and continue".

Na tela que se segue, escrever um título para o seu merge request, preferencialmente incluindo a ocorrência relativa aos commits em questão para que esteja na mensagem de squash. Adicionar também uma descrição, que será unida ao template de MR da Basis, quando aplicável. No campo Assignee, apontar um usuário responsável pela aprovação do MR, caso necessário. A opção "Delete source branch when merge request is accepted" apagará a branch original do fork assim que houver o merge de fato. E a opção "Squash commits when merge request is accepted" será marcada automaticamente, mesmo que seja desmarcada nesta tela.

Uma vez criado, o merge request será listado no menu de Merge Requests do repositório original.

Também será criado um link para acessar o merge request na ocorrência do SGO mencionada pelo mesmo.

Quando aprovado e selecionada a opção Merge, será realizado um commit de squash combinando os commits do repositório de fork, mais um commit de merge mesclando os dois repositórios. O código então será disponibilizado na branch do repositório original. Se houver algum problema no merge ou na criação do próprio merge request, o próprio sistema informará em mensagem.

Quando o fork se encontra atrasado em relação ao repositório original, é possível atualizá-lo em seu repositório fork clonado localmente. Para isso, é necessário inicialmente adicionar o repositório original como um novo remote caso não exista, executando no seu repositório local o seguinte comando:

Atualiza-se então esse remote "upstream" usando um fetch:

Para sincronizar de fato seus arquivos locais com os do repositório original, realiza-se um merge do seu repositório local, usando como base a branch requisitada do original (por padrão, "master"; alterar de acordo):

Por fim, para atualizar o repositório no Gitlab, realiza-se o push padrão:

Verifique, antes de tudo, se seu repositório local está atualizado. Diferente do SVN, não basta que apenas a pasta específica em que se está editando esteja devidamente atualizada; o repositório inteiro deve estar em dia. Realize sempre um Pull antes de fazer quaisquer modificações.

Se o repositório não estava atualizado, mas o commit foi feito ainda assim, realize um Pull de todo modo. Pode ser que não haja conflitos de arquivos modificados. Se for o caso, o Pull não retornará erros, não haverá ícones de conflito nas pastas, e o seu Push pode ser realizado diretamente em seguida (sem o commit, nesse caso, pois este já havia sido feito).

Entretanto, se houver conflitos, cabe verificar com a sua equipe se os arquivos em questão foram modificados. O próprio Log do Git deve retornar informações sobre quais foram as últimas modificações sobre o determinado arquivo, o que pode ser verificado clicando sobre o mesmo com o botão direito e selecionando, sob o menu do TortoiseGit, Show Log.

A janela seguinte terá informações de quais foram os últimos commits, e quem os realizou, para devida informação e discussão.

Uma vez que se tenha certeza que o arquivo existente no seu repositório local é o mais atualizado, deve-se selecionar, no menu do TortoiseGit na pasta, a opção "Resolve".

Marca-se então os arquivos atualizados, confirma, e então o Commit/Push pode ser realizado novamente com maior segurança.

Se ainda houver erro, experimente executar um Clean up, opção logo acima também representada. Execute também um novo Pull em seguida, para poder realizar o commit depois com segurança, e certifique-se de que todos os arquivos estão presentes no repositório local.

Para corrigir essa situação, é necessário emendar à mensagem do commit uma ocorrência válida do SGO. Se apenas um commit errôneo foi realizado, basta selecionar Git Commit novamente no repositório em questão e selecionar a opção Ammend Last Commit na caixa logo abaixo da entrada de mensagem:

Em seguida, clicar em Ok e seguir com o mesmo modelo de Commit/Push apresentado mais acima.

Se houver mais de um commit na fila, no entanto, e até mesmo em outros casos de erro recorrente, será necessário fazer um Rebase, ou refazer os commits do zero antes de realizar o Push.

Quando um commit é feito no Git, ele se mantém na fila para subir ao repositório remoto num Push. Outros commits em cima do mesmo apenas se acumulam na fila. Ou seja, se o primeiro commit está errado, ele permanecerá sem enviar para o sistema até que seja removido ou editado na fila. Nesse caso, como existem vários commits errados na fila, a procedência possível seria editar ou eliminar a mesma.

Para o primeiro caso, o chamado Rebase, clicar com o botão direito na pasta do repositório com os commits problemáticos, e dentro do menu do TortoiseGit, selecionar a opção Rebase.

Na janela que segue, marcar inicialmente a opção Force Rebase, para que o sistema leve em conta todos os commits diferentes entre o repositório local e o remoto. Em seguida, clicar com o botão direito no commit que está com problemas (pode ser mais de um), e selecionar a opção Edit. Feito isso, iniciar o Rebase através do botão Start Rebase no rodapé da janela.

Uma vez iniciado, se configurado corretamente, ele vai parar para edição da mensagem do(s) commit(s) em questão. Adicionar a ocorrência faltante, e clicar em Ammend, e em seguida em Done.

Terminado o processo de Rebase, o Push já pode ser feito sem a necessidade de fazer um novo commit.

Para o caso de refazer a fila de commits do zero, primeiramente, é interessante fazer um backup dos arquivos alterados em tais commits, pois serão apagados ou substituídos pelas versões atualmente presentes no repositório remoto. Com o backup feito, selecionar na pasta raiz do repositório: TortoiseGit > Switch/Checkout. Na janela aberta, deixar exatamente como está na imagem abaixo, com todas as marcações (ênfase na branch remote/origin/master do primeiro menu, não é a master originalmente selecionada).

Após clicar em OK, o repositório retornará ao seu estado anterior aos commits errôneos, exatamente igual ao repositório online. Com isso, os arquivos no backup podem ser copiados de volta para a pasta do repositório, e o commit pode ser refeito.

Se houver mais erros, entre em contato com a gerência de configuração.

É possível que o repositório em questão tenha nomes de arquivos ou caminhos muito grandes e, quando se realiza um Clone do mesmo num sistema Windows, ele não consiga abranger todo o caminho, retornando erros de Filename too long. Se for esse o caso, experimente realizar o Clone em outra pasta do seu sistema, preferencialmente alguma num caminho bem curto, como C:\git.

Outro erro possível teria a seguinte mensagem: error:14094410:SSL routines:ssl3_read_bytes:sslv3 alert handshake failure. Nesse caso, é necessário atualizar os protocolos de conexão SSL na configuração do Git para uma versão mais segura. Execute o seguinte comando no Git Bash (para seu uso, consultar a seção de SSH):

Após essa alteração, o Clone/Pull deve funcionar corretamente. Caso contrário, ou se o comando retornar algum erro, é recomendável reinstalar o Git numa versão mais recente.

Se tais soluções não funcionarem, ou se o erro for diferente, entre em contato com a gerência de configuração.

Este documento objetiva apresentar todos os passos necessários para que os interessados em realizar a criação de um novo repositório sejam capazes de, seguindo as instruções, chegarem ao resultado esperado, de uma forma correta e padronizada.

Considera-se no escopo deste documento abordar todas as etapas e procedimentos, que são necessários para a criação efetiva de um repositório remoto, englobando desde a conexão com a máquina até o commit inicial com a estrutura de pastas padrão de novos projetos da empresa.

Está fora do limite definido como escopo deste tutorial as informações inerentes à configuração e conexão da VPN da Basis, bem como de acesso remoto aos servidores internos.

A princípio, nenhum repositório de sistema deve ser criado sem uma ocorrência do tipo Tarefa com essa requisição, encaminhada para o departamento de Configuração. Para iniciar a criação, basta entrar nessa ocorrência, e na aba Dados do Sistema, clicar na ocorrência repassada em "Ocorrências do Sistema".

Dentro da ocorrência do sistema, nas transições de fluxo de trabalho, selecionar a transição "Criar Repositórios".

Uma janela pop-up deve aparecer na ocorrência, com os dados do sistema e campos para especificar quais repositórios serão criados. Caso nada seja escrito, por padrão, e seguindo o Guia de Gerência de Configuração, são criados os repositórios "codigo_fonte", "documentacao" e "gravacoes". O nome do sistema é preposto ao nome de cada repositório, ou seja, caso se escreva "backend", o nome do repositório será "sistema_backend".

Os repositórios por padrão são criados usando a estrutura padrão estabelecida para cada tipo de repositório, tendo um commit inicial apropriado. Entretanto, caso o repositório precise ser migrado de algum cliente e o projeto precise ser criado vazio, basta marcar o campo "Repositórios Migrados do Cliente". Todos serão criados sem qualquer commit, ficando a responsabilidade de popular o repositório para quem for importar o projeto do cliente.

A transição desencadeará as seguintes ações via webhook:

Finalizada a transição, os repositórios serão listados ao fundo aba Cadastro do Sistema, juntamente ao grupo relacionado no AD.

Caso também exista, requisitado via tarefa no SGO, um pedido para associar usuários específicos aos repositórios, é necessário realizar outra transição. Dentro da ocorrência do sistema, nas transições de fluxo de trabalho, selecionar a transição "Associar Usuários a Repos".

A janela da transição apresentará dois campos para preenchimento, sendo um para usuários que terão acesso de escrita e outro que terá usuários cujo acesso será de somente leitura. Preencher com o nome de usuário de cada um, separado com vírgulas (o próprio sistema auxilia auto-completando nomes), e realizar a transição.

Realizado este passo, os usuários serão associados ao grupo relativo ao sistema no AD Basis. Um serviço periódico de sincronização de usuários, executando em paralelo ao Gitlab, será responsável por associar esses usuários também aos repositórios do próprio Gitlab. O acesso, portanto, não é imediato, mas deve ser atualizado em menos de uma hora. A lista de usuários com acesso pode ser visualizada na seção Pessoas, à direita da ocorrência do sistema, no campo "Equipe Git".

Adicionalmente, existem grupos no AD cujos membros possuem acesso a todos os repositórios do cliente (“nomecliente_all” para escrita e “nomecliente_all_ro” para leitura). Caso haja requisição no SGO para acesso a todos os repositórios de determinado cliente, o acesso precisa ser dado diretamente nesses grupos, a partir do gerenciamento de usuários do próprio SGO ou do AD.

Na tela do Sistema de Gestão de Ocorrências (SGO) da Basis, acessar o menu no topo esquerdo da tela, e selecionar "Repositório Git", ou acessar diretamente o link https://gitlab.basis.com.br/. Se o login já estiver realizado via SSO no próprio SGO, o acesso será automático. Do contrário, a tela de login será apresentada. As credenciais de acesso são as mesmas do SGO.

Na página inicial após o login, clicar em "Grupos" para visualizar os clientes disponíveis e selecionar o desejado que receberá o novo repositório. Caso seja um novo cliente, clicar no botão "Novo Grupo" acima dos existentes.

Entrar com a chave do cliente, atribuir um avatar e editar a URL se necessário. Vale constar que a chave por padrão é a mesma usada na alocação do contrato no SGO, e não pode conter espaços ou caracteres especiais. Além disso, o nível de visibilidade deve ser marcado como Privado.

Na tela do grupo, no canto direito da tela, clicar em "Novo projeto".

Entre com o nome que o repositório receberá, seguindo o padrão:

Vale constar que o nome não pode conter espaços ou caracteres especiais.

Uma vez criado, o projeto terá as configurações padrão do sistema aplicados a si. Salvo exceções especificadas pelos próprios gestores e clientes, não é necessário alterá-las. Contudo, essas mesmas configurações impedem que equipes possam fazer alterações nos repositórios se não houver uma branch inicial, portanto faz-se necessário criar um primeiro commit.

Dentro do próprio Gitlab, é possível já criar um único arquivo de commit para base do repositório. No projeto vazio, clicar em Novo Arquivo.

Preencher o caminho do arquivo com o seguinte nome:

Preencher o conteúdo do arquivo com o seguinte texto:

Por fim, preencher o campo de mensagem de commit, substituindo a chave de ocorrência pela chave relativa à Tarefa de criação do repositório, ou sistema associado:

Estando tudo de acordo, como na imagem, clicar em Commit abaixo. O arquivo estará então aplicado ao código, permitindo commits da equipe e merge requests seguindo o padrão Basis.

A partir do Gitlab, clonar o novo repositório de documentação seguindo as instruções de como efetuar o Clone do Manual de Git.

Dentro da pasta local clonada do repositório vazio, colar e executar o arquivo: mkdirsgit.bat (ou mkdirsgit.sh caso o sistema seja Linux).

Se o script rodou corretamente, a pasta agora possui oito novas pastas na sua raiz. Apagar ou mover para fora o arquivo mkdirsgit.bat ou mkdirsgit.sh.

Clicar com o botão direito na pasta raiz do repositório e selecionar "Git commit → master…​".

Se surgir uma mensagem informando que o nome de usuário e E-mail precisam ser setados, clicar em Yes, preencher o formulário seguinte com seu nome de usuário e E-mail Basis, selecionar "Save as Global" e clicar em Ok.

Marcar todos os arquivos da lista (vários .gitignore para manutenção das pastas), comentar e executar o commit.

Mensagem de commit sugerida:

Quando finalizar o commit, clicar em Push logo abaixo.

Clicar em OK, digitar sua senha e aguardar a finalização.

Ao terminar de enviar o push, o repositório estará configurado e já poderá receber os documentos do sistema.

Caso um commit ou push dê errado, faz-se necessário realizar um Pull para manter o repositório local atualizado e estável. Clicar com o botão direito na pasta raiz do repositório e selecionar "Git Sync…​".

Na janela resultante, selecionar Pull. Entrar com sua senha e aguardar a finalização.

Nessa janela, também é possível realizar commits e pushes, se for conveniente. Lembrando que, após o pull, o push deve ser executado novamente. Um novo commit não é necessário, a não ser que haja conflitos em arquivos do repositório que precisem ser resolvidos.

Conforme a figura acima, no Windows, clique com o botão direito em Computador, e selecione Propriedades.

Ao entrar, clique em “Alterar Configurações”.

Na tela de Propriedades do Sistema que surgir, selecione “Alterar”. Na janela seguinte, em que se lê “Nome do Computador”, coloque seu usuário BASIS como indicado acima. Clique em OK e reinicie o computador para que as configurações tenham efeito.

O software OCSinventory deve ser baixado em sua versão específica 2.0.5, seguindo o link: https://launchpad.net/ocsinventory-windows-agent/2.x/2.0.5/+download/OCSNG-Windows-Agent-2.0.5.zip.

Ao fim do download, extraia o arquivo OCSNG-Windows-Agent-2.0.5.zip, e clique duas vezes no arquivo OCS-NG-Windows-Agent-Setup.exe para abrir o instalador.

Prossiga com a instalação, avançando para as próximas páginas:

Na tela de configuração com o servidor, em Server URL, coloque o endereço https://inventario.basis.com.br/ocsinventory. Mantenha em branco todos os outros campos, desmarcando inclusive a checkbox “Validate certificates”.

Não há a necessidade de adicionar nada nas configurações de proxy. Na tela seguinte, em “Setup options…​”, marque a última checkbox “Immediately launch inventory (=/NOW)”.

Ao concluir, os dados de sua máquina já estarão disponíveis para consulta no inventário.