As informações apresentadas nesta página são complementares às diretrizes de desenvolvimento de software do Ministério da Saúde.
¶ DevSecOps
As diretrizes contidas nesta página não são exaustivas: casos omissos devem analisados pela equipe da COATIC para que sejam adicionados oportunamente.
A seguir são apresentados alguns pilares das práticas DevSecOps e as diretrizes que devem ser seguidas para cada um desses pilares.
¶ Controle de Versão (SCM)
O controle de versionamento de softwares dentro do Datasus deve ser feito utilizando-se o SCM Git. Por ser uma ferramenta muito completa e flexivel, é importante delimitar também o fluxo de interação com os repositórios, também chamado de Git workflow. Um dos fluxos de trabalho mais comuns no SCM Git é o Gitflow, mas boa parte da comunidade de desenvolvimento de software vem desaconselhando seu uso devido a, entre outras razões, sua grande complexidade (mais informações em: https://www.endoflineblog.com/gitflow-considered-harmful e https://docs.gitlab.com/ee/topics/gitlab_flow.html#problems-with-the-git-flow).
Com um intuito de simplificar a padronizar a interação com o repositório, proporcionar o rastreamento de cada artefato e seus deploys em cada ambiente e, finalmente, minimizar a possibilidade de erro humano na referida interação, o Git workflow a ser utilizado no Datasus é o Oneflow (https://www.endoflineblog.com/oneflow-a-git-branching-model-and-workflow). Vale ressaltar, entretanto, que a implementação desse fluxo no âmbito do Datasus assume algumas particularidades, que são detalhados a seguir.
¶ Estratégia de branches
A implementação do Oneflow no Datasus assumirá 3 conjuntos de branches:
main: branch padrão do Git. Utilizada para delimitar a versão de produção da aplicação.develop: utilizada como base de desenvolvimento de features e como branch padrão para análise de código estático.- feature branches: branches de funcionalidades. Utilizadas para implementar as funcionalidades que serão integradas na branch
develop
¶ Regras de nomenclatura
O padrão de nomenclatura das referências a commits é de extrema importância em qualquer Git workflow, já que ele tem implicações diretas cas esteiras de automação de validação e implantação das aplicações. Os nomes de tags e branches no Datasus serão ditados pelas regras que se seguem.
¶ Padrão de nomes de branches de feature
Branches de feature devem começar com o prefixo feat/, acrescidas de string que denote o nome da funcionalidade a ser desenvolvida.
Exemplo: feat/tela-de-login, feat/cadastro-paciente.
¶ Padrão de nomes de tags
As tags têm grande importância na implementação do Oneflow do Datasus. É através de seu uso que será possível rastrear qual versão da aplicação está implantada em cada ambiente. Seu uso também auxilia a eliminar um problema muito recorrente no Gitflow: sobrescrita de implantações em ambientes de validação. Nesse contexto, as tags também serão divididas em conjuntos, cada uma com uma regra de nomenclatura própria. O tipo de tag e as regras de nomeação de cada uma delas são detalhadas a seguir.
- Tags de feature: utilizadas para deploy de funcionalidade ainda em desenvolvimento numa branch de feature. Regra de nomenclatura: prefixo
dev/feat/acrescido do nome da funcionalidade e de um número inteiro, para diferenciar diferentes deploys de uma mesma feature em validação.- Exemplo:
dev/feat/tela-de-login-1,dev/feat/cadastro-paciente-2.
- Exemplo:
- Tags de desenvolvimento: utilizadas para delimitar um pacote de funcionalidades e/ou conjunto de commits a serem validados em ambiente de desenvolvimento. Regra de nomenclatura: prefixo
dev/vacrescido de uma string se versão de acordo com o padrão SemVer (https://semver.org/).- Exemplo:
dev/v1.2.0,dev/v0.5.1.
- Exemplo:
- Tag de candidata a release: utilizada para delimitar um pacote de funcionalidades que já estão prontas para serem validadas em ambiente de homologação. Regra de nomenclatura: prefixo
hmg/vacrescido da versão a ser liberada, também no padrão SemVer, acrescido no sufixorc-X, onde X é um número inteiro para diferenciar possíveis pacotes distintos.- Exemplo:
dev/v1.2.0-rc1,dev/v1.2.0-rc2.
- Exemplo:
- Tag de produção: utilizada para delimitar versões que foram para ambiente de produção. Regra de nomenclatura: prefixo
vmais string indicando a versão, de acordo com o padrão SemVer.- Exemplo:
v1.2.0.
- Exemplo:
¶ Estratégia de merge
Uma das grandes vantagens do Oneflow em relação ao Gitflow é sua capacidade de manter a árvore de commits do repositório organizada mais facilmente. Uma árvore de commits linear, na qual as branches principais avançam sempre através de fast-forward merges é consideravelmente mais fácil de interpretar do que uma com commits de merge habituais. Essa visualização dá aos desenvolvedores do projeto informações valiosas sobre quais abordagens funcionaram (ou não) ao longo da evolução do código da aplicação. A imagem ilustra o processo de rebase + fast-foward merge que deve ser seguido ao integrar branches de feature à branch develop.
¶ Quality and Security Gates
Processos de desenvolvimento maduros, alinhados à práticas DevSecOps, implementam gates de qualidade para garantir que os padrões arquiteturais e boas práticas de código estão sendo seguidos, bem como aspectos de segurança e confiabilidade da aplicação. O Datasus utiliza ferramentas como GitLab (https://about.gitlab.com/), SonarQube (https://www.sonarsource.com/products/sonarqube/), Tryvi (https://aquasecurity.github.io/trivy), OWASP ZAP (https://www.zaproxy.org/), dentre outras, para implementar os referidos gates de qualidade e segurança. Essas ferramentas são capazes de rodar em modo SAST (análise estática) ou DAST (análise dinâmica). Com o intuito de melhor elucidar onde cada verificação dessa é mais pertinente, pode-se dividir esses gates em 2 conjuntos principais, relacionados ao estágio onde são aplicados.
- Quality Gates de Integração Contínua: etapas de checagem de qualidade executadas ainda em tempo de Merge Request, para cada incremento de código realizado no repositório. São eles:
- build e testes unitários: montagem do código e execução bem sucedida de todos os testes unitários;
- análise estática de código e porcentagem de cobertura por testes: verificação de más praticas de programação (code smells), dependências e/ou código malicioso e de porcentagem mínima de cobertura de código por testes unitários;
- code-review: verificação de código por pares, etapa fundamental de qualquer processo de desenvolvimento de software profissional.
A imagem a seguir ilustra em detalhes em que momento cada um desses quality gates deve ser executado. Por serem executados em tempo de Merge Request, este só deverá ser aprovado caso todas as checagens tenham sido realizadas com parecer favorável. Caso contrário, os desenvolvedores devem corrigir as não-conformidades apontadas pelas ferramentas e/ou por seus pares e submeter novamente o código à Merge Request.
- Quality Gates de implantação: etapas de checagem de qualidade relacionadas ao artefato de deploy.
- segurança de imagem do container: verificação de vulnerabilidades conhecidas associadas ao container;
- deploy bem-sucedido: verificação relacionada à saúde da aplicação após a implantação e à aspectos de segurança com utilizando ferramentas de DAST.
Os artefatos desenvolvidos para o Datasus devem ser imagens de container Docker.
A imagem a seguir ilustra os principais participantes relacionados ao deploy de um artefato, bem como em que etapa as verificações mencionadas acima devem ocorrer.
¶ Rastreamento de artefatos e fluxo de deploy
Como mencionado nas seções anteriores, uma das grandes vantagens do Oneflow em relação ao Gitflow é a capacidade de rastrear artefatos de deploy mais facilmente. Para isso, esse Git workflow faz ostensivo uso de tags. São as tags que disparam os pipelines de deploy as regras de nomenclatura associadas a elas que ditam em qual ambiente a implantação será feita. Há um rega geral, entretanto, que se aplica a todos os artefatos:
O nome da tag aplicada ao repositório deve ser identica à tag da imagem do container do artefato a ser implantado.
¶ Mapeamento tag x ambientes
Tags de feature (
dev/feat/) devem disparar a geração de artefatos para uso em ambiente localTags de desenvolvimento (
dev/) devem disparar geração de artefato sua implantação em ambiente de devTags de candidata à release (
hmg/vW.Y.Z-rcX) devem disparar a geração de artefato e sua implantação em ambiente hmgTags de produção (
vW.Y.Z) deve ser aplicada ao mesmo commit que gerou a candidata à release aprovada e cujo artefato foi promovido à produção
¶ Fluxo de deploy
A seguir é mostrado um exemplo prático de como se dá um fluxo de deploy habitual, bem os comandos que podem ser utilizados para implementar o Git workflow desejado. Este fluxo sintetiza os princípios que foram descritos neste documento e ilustra como a árvore de commits do repositório deve se comportar ao longo do desenvolvimento e deploy das funcionalidades da aplicação. É importante ressaltar, entretanto, que devido a complexidade do Git, é possível se obter um mesmo resultado através de formas (e comandos) distintas. O guia de comandos utilizado abaixo deve ser utilizado apenas como referência.
¶ Implantação em dev
¶ Implantação em homologação e promoção para produção
