Software Público Brasileiro

\chapter{Gitlab}
\label{cap:gitlab}

O GitLab é um software livre de colaboração de código online que utiliza o sistema de controle de versão Git (explicado mais detalhadamente no capítulo \ref{cap:git}). O GitLab disponibiliza uma interface para o gerenciamento de códigos, rastreamento e estado de problemas (issue tracker), uma wiki interna, ferramentas para gerenciamento de grupos, de revisão de código (code review) e mescla de código (merge requests), que auxilia em especial, os projetos com muitos integrantes.

Ele ainda proporciona ainda diversas outras ferramentas para manter seus usuários sempre atentos aos eventos relacionados aos seus projetos, através de \textit{feeds} e formas bem diretas de se observar mudanças em códigos de uma versão para outra. Há também uma forma de se observar graficamente, as atividades dos membros dos projetos e os estados das diversas ramificações (\textit{branches}) que o Git permite criar. Abaixo é apresentado a lista das principais funcionalidades que o Gitlab possui:

\begin{itemize}
	\item Editor web.
	\item Notificações globais e por projeto.
	\item \textit{Branches} (ramificações) e gráficos de \textit{branches}.
	\item Pesquisa no código.
	\item \textit{Feeds} de atividades por projeto.
	\item Administração de membros e projetos.
	\item Rastreamento de problemas (\textit{issue tracker}).
	\item \textit{Merge Request}.
	\item Merge automático.
	\item \textit{Wiki}.
	\item Revisão de código.
	\item Acesso ao código fonte.
	\item Mural do projeto.
\end{itemize}

Atualmente existe uma versão do Gitlab no novo portal do Software Público, que é utilizado pelos desenvolvedores para criação/divulgação do seu software no portal.

\section{Trabalhando com o Gitlab}
\subsection{Configuração do Gitlab}

O Gitlab utiliza a chave pública SSH da máquina para realizar a autenticação sem a necessidade da utilização de senhas. Através da configuração dessa chave é possível utilizar todas as funções que o Gitlab oferece, para realizar a configuração deve:

	\begin{itemize}
		\item Gerar a chave SSH pública e colocá-la no Gitlab. 
		\item Disponibilizar a chave no Gitlab.
	\end{itemize}

Para gerar a chave pública SSH, existe um tutorial disponível no site oficial do git, ou até mesmo no próprio SPB. Esses links estão disponiveis em

	\begin{itemize}
		\item Git: \url{https://git-scm.com/book/pt-br/v1/Git-no-Servidor-Gerando-Sua-Chave-P\%C3\%BAblica-SSH};
		\item SPB: \url{https://softwarepublico.gov.br/social/spb/como-faco-pra-utilizar-o-ambiente-colaborativo}
	\end{itemize}
	
Logo após gerar essa chave pública, o usuário deve adicioná-la no Gitlab do novo Software Público Brasileiro. Para isso o usuário deve logar no portal SPB.	 

Em seguida, o usuário deve acessar o Menu superior > Desenvolvimento > Perfil. A tela ilustrada pela Figura \ref{fig:perfil_gitlab} será apresentada. Nessa tela, é possível alterar todas as informações relativas ao ambiente do gitlab, inclusive nome, avatar, skype, linkedin, entre outros.

\graphicspath{{figuras/}}
\begin{figure}[H]
	\centering
	\includegraphics[width=.95\textwidth]{perfil_gitlab.png}
	\caption{Tela de alteração do perfil do gitlab.}
	\label{fig:perfil_gitlab}
\end{figure}

Logo após o usuário, deve selecionar a opção "SSH Keys" no menu superior, de acordo com a Figura \ref{fig:menusup_gitlab}.

\graphicspath{{figuras/}}
\begin{figure}[H]
	\centering
	\includegraphics[width=.95\textwidth]{menusup_gitlab.png}
	\caption{Menu superior do gitlab com a opção "SSH keys" logo a direita.}
	\label{fig:menusup_gitlab}
\end{figure}

Depois de selecionar a opção "SSH Keys", o usuário vera a tela ilustrada pela Figura X. Nessa tela possui todos as chaves SSH cadastradas pelos usuários, isto é, cada chave pode ou não representar cada computador utilizado pelo desenvolvedor. Para adicionar uma nova chave, o usuário deve clicar na opção \includegraphics[width=2.2cm]{figuras/botao_sshkeys.png}(Add SSH Key).

\graphicspath{{figuras/}}
\begin{figure}[H]
	\centering
	\includegraphics[width=.75\textwidth]{tela_sshkeys.png}
	\caption{Menu superior do gitlab com a opção "SSH keys" logo a direita.}
	\label{fig:menusup_gitlab}
\end{figure}

No momento de adição da chave SSH, o usuário deve preencher um formulário com 2 (dois) campos, que contém: 
	\begin{itemize}	
		\item \textbf{Title} - Nome que identifica o computador do desenvolvedor. (Ex: Computador do Trabalho)
		\item \textbf{Key} - Campo da Chave SSH gerada e que deve ser copiada para o campo.
	\end{itemize}
	
Após isso, será necessário somente a configuração do Git no ambiente de desenvolvimento do usuário, que será apresentada na seção \ref{cap:git} . 

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Projetos}

Projetos são repositórios que abrigam os artefatos de um software, sendo eles documentos, códigos, modelos, entre outros. Normalmente cada software possui seu próprio projeto, caso existam módulos ou outras partes do projeto é recomendado que se crie um grupo (a parte de grupos será explicado na seção \ref{sub:grupos}).

No link \url{https://softwarepublico.gov.br/gitlab/explore/projects}, possui todos os repositórios e softwares públicos disponíveis.

\label{sub:gitlab_projeto}
\subsubsection{Criando um novo Projeto}

Caso esteja começando um novo projeto de software, é necessário que faça a criação de um novo projeto no Gitlab. Para realizar isso, o usuário deve acessar no menu superior a opção de "Desenvolvimento" e logo após "Novo Projeto", após isso, é apresentada a tela ilustrada pela Figura \ref{fig:criacao_projeto}.

\graphicspath{{figuras/}}
\begin{figure}[H]
	\centering
	\includegraphics[width=.85\textwidth]{criacao_projeto.png}
	\caption{Tela de criação de projetos no Gitlab.}
	\label{fig:criacao_projeto}
\end{figure}

Na tela da criação do projeto serão requisitados alguns dados como:

\begin{itemize}
	\item \textbf{Project Name:} Nome do Software;
	\item \textbf{Namespace:} Pessoa ou grupo que terá a permissão no projeto;
	\item \textbf{Description:} Descrição sucinta e clara do Software; 
	\item \textbf{Visibility:} Privacidade do Projeto\footnote{O Gitlab permite que os projetos possam ser configurados de acordo com a necessidade do desenvolvedor}
		\begin{itemize}
			\item \textbf{Private} - O projeto só pode ser acessado pelos membros do mesmo. Além disso, ele fica oculto para todos os usuários.
			\item \textbf{Internal} - O projeto fica aberto para os usuários, no entanto, só podem ser clonado apenas por usuários logados.
			\item \textbf{Public} - Qualquer usuário independente de estar logado, consegue visualizar e clonar o projeto.
		\end{itemize}
\end{itemize}


\begin{tcolorbox}[colback=red!5,colframe=red!40!black,title=\textbf{Observação}]
Para acessar o projeto criado, além de outros projetos e/ou grupos que o usuário faça parte, deve acessar o seguinte endereço:
https://softwarepublico.gov.br/gitlab/
\end{tcolorbox}

\subsubsection{Acessando a página inicial do Projeto}

Logo após a criação do repositório ou acessando um repositório já criado, o usuário será apresentado a uma mesma tela, que segue um padrão ilustrado pela Figura \ref{fig:criacao_projetogitlab}.

\graphicspath{{figuras/}}
\begin{figure}[H]
	\centering
	\includegraphics[width=.95\textwidth]{tela_projetogitlab.png}
	\caption{Tela de criação de projetos no Gitlab.}
	\label{fig:criacao_projeto}
\end{figure}

Conforme visto na Figura temos:

\begin{enumerate}
	\item Menu superior, contendo acesso as funções principais que o gitlab oferece a um projeto;
	\item Descrição sucinta e clara do projeto;
	\item Link para os protocolos de acesso git\footnote{Maiores informações em: https://git-scm.com/book/tr/v2/Git-on-the-Server-The-Protocols};
	\item Timeline contendo as principais atividades realizadas no projeto recentemente;
	\item Link para download do repositório no formato compactado (.zip); 
	\item Links rápidos para criação de issues, adição de membros, tags, entre outras opções
	\item Informações básicas contendo o número de branchs, tags, commits,  tamanho do projeto, data de criação e dono do projeto;
\end{enumerate}

\subsubsection{Transferindo Projeto}

Caso não seja possível continuar com o projeto, é possível realizar a transferência para um grupo ou para membros de um mesmo projeto. 

Para realizar a transferência, o usuário deve acessar a página principal do repositório, no menu superior do Gitlab deve encontrar a opção "Settings". Logo abaixo o usuário irá encontrar a opção "Transfer Project", que é visualizado na Figura X.

\graphicspath{{figuras/}}
\begin{figure}[H]
	\centering
	\includegraphics[width=.95\textwidth]{transfer_project.png}
	\caption{Caixa com a opção de transferência de projeto.}
	\label{fig:transfer_project}
\end{figure}


Nessa caixa, dentro da opção "Namespace" o usuário deve escolher o novo dono do projeto, que pode ser um membro do projeto, ou um grupo o qual o usuário seja dono. 

Logo que selecionar o novo dono, basta clicar no botão "Transfer" e será aberta uma popup. Nessa popup é necessário fornecer uma confirmação, que é o nome do projeto (de acordo com o link), conforme está destacado na Figura \ref{fig:confirm_transfer}. Após a confirmação, o projeto será repassado para o dono informado.


\graphicspath{{figuras/}}
\begin{figure}[H]
	\centering
	\includegraphics[width=.75\textwidth]{confirm_transfer.png}
	\caption{Caixa com a confirmação de transferência do projeto.}
	\label{fig:confirm_transfer}
\end{figure}

\subsubsection{Excluíndo o Projeto}

Para excluir um projeto, o usuário deve acessar a página inicial do projeto e entrar nas configurações, escolhendo a opção "Settings", que está localizada na barra superior do Gitlab.

Na tela de configuração, o usuário deve localizar a opção "Remove project", conforme Figura \ref{fig:remove_project}. Depois deve selecionar o botão chamado de \includegraphics[width=2.65cm]{figuras/botao_removeproject.png} (Remove project).

\graphicspath{{figuras/}}
\begin{figure}[H]
	\centering
	\includegraphics[width=1\textwidth]{remove_project.png}
	\caption{Caixa com a opção de exclusão do projeto.}
	\label{fig:remove_project}
\end{figure}

Será aberta uma popup pedindo para confirmação da exclusão do projeto, para isso, é necessário digitar o nome do projeto de acordo com o destacado pela Figura \ref{fig:confirm_remove} (geralmente o nome do projeto  é de acordo com o link). Feito esses passos, o projeto já está excluído:

\graphicspath{{figuras/}}
\begin{figure}[htb!]
	\centering
	\includegraphics[width=.9\textwidth]{tela_exclusaoprojeto.png}
	\caption{Caixa com a confirmação de exclusão do projeto.}
	\label{fig:confirm_remove}
\end{figure}

\begin{tcolorbox}[colback=red!5,colframe=red!40!black,title=\textbf{Observação}]
É importante ressaltar que uma vez que o projeto é excluído, não será possível recuperá-lo, então utilize essa opção se tiver certeza que deseja excluir.
\end{tcolorbox}

\subsubsection{Adicionando membros aos projetos}

É possível que um projeto tenha mais de um membro trabalhando simultaneamente. Isso permite que uma equipe possa trabalhar dentro de um projeto, sem a necessidade de cada um ter o seu próprio repositório.

Para adicionar membros no projeto, o usuário deve acessar o menu superior e selecionar a opção "Settings". Após, em um menu localizado na esquerda deve acessar a opção \includegraphics[width=2.65cm]{figuras/botao_members.png}(Members).

Na tela ilustrada pela Figura X, é apresentado todos os membros que fazem parte do projeto, assim como as permissões associadas\footnote{O gitlab permite que o dono do repositório atribua papéis para cada membro que vai fazer parte do projeto, mais informações são disponibilizadas em: https://softwarepublico.gov.br/gitlab/help/permissions/permissions}. Para adicionar um novo membro, basta acessar a opção \includegraphics[width=2.95cm]{figuras/botao_newmember.png}(New Project Member). Caso queira importar uma lista de outro projeto, selecione a opção \includegraphics[width=2.65cm]{figuras/botao_importmembers.png}(Import Member).

\graphicspath{{figuras/}}
\begin{figure}[htb!]
	\centering
	\includegraphics[width=1\textwidth]{tela_members.png}
	\caption{Tela com relação de membros que fazem parte do projeto.}
	\label{fig:tela_members}
\end{figure}

Na tela apresentada pela Figura \ref{fig:add_members}, o usuário deve informar o \textbf{nome do usuário} utilizado no SPB, assim como a permissão o qual ele vai ter no repositório. Depois disso, o usuário de salvar na opção \includegraphics[width=2.35cm]{figuras/botao_adduser.png} (Add users) e a pessoa irá fazer parte do projeto.

\graphicspath{{figuras/}}
\begin{figure}[htb!]
	\centering
	\includegraphics[width=1.1\textwidth]{add_members.png}
	\caption{Adição de membros no projeto.}
	\label{fig:add_members}
\end{figure}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Grupos}
\label{sub:grupos}

O Gitlab permite a criação de grupos para trabalho conjunto entre os usuários. O grupo permite a criação de uma coleção de projetos relacionados. 

\subsubsection{Criação do grupo}

Para criar um grupo, o usuário deve localizar a opção "Desenvolvimento" no menu superior, logo após deve acessar a opção "Grupos", a Figura \ref{fig:tela_grupos.png} representa os grupos o qual o usuário faz parte.

\graphicspath{{figuras/}}
\begin{figure}[H]
	\centering
	\includegraphics[width=1\textwidth]{tela_grupos.png}
	\caption{Listagem de grupos que o usuário participa.}
	\label{fig:tela_grupos.png}
\end{figure}

Após acessar o menu de Grupos, o usuário deve selecionar a opção \includegraphics[width=2.35cm]{figuras/botao_newgroup.png}(New Group), que é mostrado pela Figura \ref{tela_grupos.png}.

\graphicspath{{figuras/}}
\begin{figure}[htb!]
	\centering
	\includegraphics[width=1.1\textwidth]{create_group.png}
	\caption{Tela para criação de membros no Gitlab.}
	\label{tela_grupos.png}
\end{figure}

O usuário deve preencher três campos, que são:

\begin{itemize}
	\item \textbf{Group name -} O nome que identificará o grupo;
	\item \textbf{Details -} Detalhes sobre o grupo, projetos que estão; e relacionados, entre outros
	\item \textbf{Group avatar -} Imagem de avatar do grupo.
\end{itemize}

Após isso o grupo já está criado, e podem ser colocados projetos e membros para trabalho. O link para acesso o grupo será:

\begin{lstlisting}[caption={Link de disponibilização do grupo}, label=link:gitlab_grupo]
	https://softwarepublico.gov.br/gitlab/groups/NOMEDOGRUPO
\end{lstlisting}

Observação: Ao criar o grupo do software a equipe de administração do portal colocará os administradores com a permissão de administração no grupo do projeto. O administrador receberá um e-mail com orientações.

\subsubsection{Adicionando membros e permissões}

Após criar e acessar o grupo, o usuário deve localizar no menu superior direito (abaixo do cabeçalho do SPB), a opção "Members". A Figura \ref{tela_groupmembers.png} ilustra a página com os membros de um grupo.

\graphicspath{{figuras/}}
\begin{figure}[htb!]
	\centering
	\includegraphics[width=1\textwidth]{tela_groupmembers.png}
	\caption{Listagem de membros de um projeto.}
	\label{tela_groupmembers.png}
\end{figure}

Logo após, o usuário deve acessar a opção \includegraphics[width=2.9cm]{figuras/botao_addmember.png}(Add members). Como visto na Figura \ref{fig:tela_cadastromember.png}, é necessário preencher o campo com o nome do usuário que deseja adicionar (ou mesmo alterar a permissão de um membro no projeto), além disso, o dono do grupo deve adicionar o tipo de permissão que o usuário terá dentro do grupo. 

\graphicspath{{figuras/}}
\begin{figure}[htb!]
	\centering
	\includegraphics[width=1\textwidth]{tela_cadastromember.png}
	\caption{Tela para criação de membros no Gitlab.}
	\label{fig:tela_cadastromember.png}
\end{figure}

\begin{tcolorbox}[colback=red!5,colframe=red!40!black,title=\textbf{Observação}]
As permissões para cada tipo de usuário estão disponíveis (em inglês) nesse \href{http://doc.gitlab.com/ce/ci/permissions/README.html}{link}.
\end{tcolorbox}
 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Issue Tracker}
\label{sub:issue_tracker}
O Gitlab possui um sistema para controle de problemas, requisições, demandas, bugs, entre outros. Esse sistema que chamado de "\textit{issue tracker}", facilita o controle do desenvolvimento do projeto.

Para acessar a páginas de \textit{issue} do seu projeto, o usuário deve acessar a página inicial do projeto e localizar a opção \textit{"Issues"} no menu superior do Gitlab. Será disponibilizada uma tela semelhante a ilustrada pela Figura \ref{fig:issue_tracker.png}.

\graphicspath{{figuras/}}
\begin{figure}[htb!]
	\centering
	\includegraphics[width=1.05\textwidth]{issue_tracker.png}
	\caption{Listagem de \textit{issues} de um projeto.}
	\label{fig:issue_tracker.png}
\end{figure}

\subsubsection{Cadastrando/Alterando uma nova issue}

Acessando a tela principal de controle das issues, logo ao lado do campo de pesquisa de issues, existe uma opção chamada \includegraphics[width=2.9cm]{figuras/botao_newissue.png}(New Issue). Após selecionar a opção, uma tela de cadastro semelhante a ilustrada pela Figura \ref{fig:tela_cadastroissue.png} será apresentada.

\graphicspath{{figuras/}}
\begin{figure}[H]
	\centering
	\includegraphics[width=.8\textwidth]{tela_cadastroissue.png}
	\caption{Cadastro de \textit{issue} no projeto.}
	\label{fig:tela_cadastroissue.png}
\end{figure}

Nessa tela de cadastro o usuário deve informar \textit{(i)} o título problema/sugestão encontrada e \textit{(ii)} descrição do problema\footnote{nesse caso pode ser: passos para encontrar o problema, histórias de usuários, printscreens, fluxos de dados, imagens, entre outros conteúdos que possam ajudar o desenvolvedor visualizar o problema/sugestão}. 

Também é possível responsabilizar um membro do projeto através do campo \includegraphics[width=2.4cm]{figuras/label_assignto.png}(Assign to), que será a dona da issue. Essa pessoa receberá todas as notificações sobre a issue, além de poder filtrar as issues de acordo com o seu nome.

\subsubsection{Labels}

O Gitlab permite a categorização das demandas de acordo com Labels, isto é, uma issue quando aberta pode ser categorizada de acordo com o seu tipo, ferramenta, release que será ajustada, entre outros filtros. Essas tags podem ser definidos pelos desenvolvedores ou donos de repositórios.

Para criar Labels, o usuário deve acessar o \hyperref[sub:issue_tracker]{Issue Tracker}. Existem duas formas de realizar o cadastro de labels, entre elas:

\begin{itemize}
	\item No menu de abas do issue tracker, há uma aba chamada Labels (conforme pode ser visto na Figura \ref{fig:menulateral_issues.png})
	\item No menu lateral há uma seção Labels. O botão \includegraphics[width=.3cm]{figuras/botao_labels.png}, pode ser utilizado para realizar a alterações nas labels.
\end{itemize}

\graphicspath{{figuras/}}
\begin{figure}[H]
	\centering
	\includegraphics[width=.3\textwidth]{menulateral_issues.png}
	\caption{Menu lateral contendo a seção labels.}
	\label{fig:menulateral_issues.png}
\end{figure}

\subsubsection{Milestones}

Milestones são marcos do projeto, ou seja, são objetivos que devem estar prontos em uma determinada data. Esses marcos podem ser um conjunto de várias issues, merge requests e participantes (equipe) que estão associados naquele marco.

Para criação de Milestones o usuário deve acessar a página inicial do projeto, em seguida deve localizar a opção \hyperref[sub:issue_tracker]{Issue} no menu superior. Será apresentada a mesma tela da Figura X (ISSUES). Após isso, o usuário deve selecionar a aba \includegraphics[width=.3cm]{figuras/botao_createmilestone.png} (Milestones), abaixo do menu principal do Gitlab.

\graphicspath{{figuras/}}
\begin{figure}[H]
	\centering
	\includegraphics[width=.3\textwidth]{tela_criacaomilestone.png}
	\caption{Menu lateral contendo a seção labels.}
	\label{fig:menulateral_issues.png}
\end{figure}

Após preencher o título, a descrição do marco, além da data de fechamento do marco, basta selecionar a opção \includegraphics[width=.3cm]{figuras/botao_milestone.png} (Create milestone). Após isso, basta selecionar as issues, além das pessoas que vão fazer parte desse marco.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Wiki}

O Gitlab também fornece uma Wiki colaborativa para cada projeto. Essa wiki é utilizada como por exemplo, para que os desenvolvedores que não desejem versionar a documentação dentro do repositório do software, possam colocar todos os artefatos relacionados a este dentro da própria de wiki que o Gitlab fornece.

Para acessar a Wiki do projeto, o usuário deve acessar a página inicial do projeto no Gitlab (repositório) e no menu superior direito (ao lado de "Settings"), deve acessar a opção Wiki.

Caso o projeto não possua nenhuma página wiki, é criado uma primeira página chamada de home, que serve de página inicial da wiki. As demais páginas podem ser criadas através do botão \includegraphics[width=.3cm]{figuras/botao_newpage.png}.

\begin{tcolorbox}[colback=red!5,colframe=red!40!black,title=\textbf{Observação}]
Existem 3 tipos de notações para escrita na Wiki do Gitlab, sendo a mais utilizada a Markdown. Toda a documentação e notação relacionada ao Markdown está disponível neste \href{https://softwarepublico.gov.br/gitlab/help/markdown/markdown}{link}.
\end{tcolorbox}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%