Automatizar geração de publicação do hapi.etica.ai e geração de arquivos derivados baseados em schemas criados pelos humanos

[fititnt]

• Tópico relacionado
  • Customização especial na geração de GitHub Pages #5
  • [MVP] Implementação prática de OpenAPI para gerar documentação interativa #6

---

Como o conteúdo de hapi.etica.ai não apenas precisa gerar site estático (nisso estamos usando Jekyll) mas também gerar uma quantidade significativa de arquivos a partir dos OpenAPI (que futuramente poderíamos até habilitar SDKs de código para APIs documentadas) requer ferramentas mais complexas, como o openapi-generator-cli.

Resumindo: editar o resultado desse projeto tende a ser até mais simples do que seria programar diretamente mas linguagens de programação, porém requer uma automação prévia para salvar todo mundo de ter que entender como funciona. Essa automação prévia é o motivo desse tópico.

A ideia aqui é permitir que, apenas ao receber uma submissão de código no ramo main, se não houver problemas de validação, o resultado é enviado e publicado no outro repositório, o HXP-CPLP/hapi.etica.ai (e aquele repositório é que contém o resultado do https://hapi.etica.ai.

Sobre os scripts e reuso por outras organizações

Com exceção a esse tópico em português, os scripts de como reproduzir o deploy vão ficar em inglês.

Primeiro porque, para comunidade do CPLP, seja eu diretamente ou colegas podem ajudar a consertar os scripts (provavelmente eles vão funcionar por anos, então isso não é problema).

Porém o motivo principal é que, se necessário no futuro, parte do trabalho do HXP-CPLP pode ser incorporado por outras organizações, inclusive internacionais, que tenham interesse em homologar ao menos parte do que for feito aqui, em especial os schemas. Não quer dizer que vai acontecer, mas se for, detalhes como este simplificam.

Notem que embora nossa preocupação aqui com licença domínio público esteja no caminho certo, se para outras organizações for complicado demais adotar (a ponto de ter que licitações e planejamento financeiro) mesmo ideias boas poderiam demorar muitos meses. Some-se a isso que ideia de ter mais de uma versão de idioma tende a ser visto como difícil de implementar (muito por causa de iniciativas fracassadas no passado) então o máximo de automação que podemos conseguir, melhor. (Mas automações com relação a mais idiomas são para segundo momento, primeiro precisaríamos pelo menos inglês e Português)

[fititnt]

./systema/infrastructuram/temporarium.sh

#### Create an exclusive SSH key for specific repository _______________________
### Create on local computer ---------------------------------------------------
# @see https://docs.github.com/en/developers/overview/managing-deploy-keys
# @see https://docs.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent

ssh-keygen -t ed25519 -C "etica.of.a.ai+HXL-CPLP-hapi.etica.ai@gmail.com" -f "$HOME/.ssh/eticaai/id_ed25519-hapi"

#### Change git push to use custom SSH key _____________________________________
# (...)

### ALTERNATIVE TWO ------------------------------------------------------------
# @see https://stackoverflow.com/questions/7927750/specify-an-ssh-key-for-git-push-for-a-given-domain/43953433#43953433
# fititnt@bravo:/workspace/git/HXL-CPLP/Auxilium-Humanitarium-API$ ./systema/programma/displicandum-gh-pages.sh
#   manual instructions says
#       cd /workspace/git/HXL-CPLP/Auxilium-Humanitarium-API/systema/cache/gh-pages-temp-git
#       git push -u remote-publisher gh-pages --force
# New command instead of git push -u remote-publisher gh-pages --force
#   GIT_SSH_COMMAND="ssh -i $HOME/.ssh/eticaai/id_ed25519-hapi" git push -u remote-publisher gh-pages --force

[fititnt]

.travis.yml

# @see systema/infrastructuram/temporarium.sh
# @see https://docs.travis-ci.com/user/deployment/script/

deploy:
  provider: script
  script: bash systema/infrastructuram/travis-ci.sh
  on:
    branch: main

./systema/infrastructuram/travis-ci.sh

#!/bin/sh
#===============================================================================
#
#          FILE:  travis-ci.sh
#
#         USAGE:  ./systema/infrastructuram/travis-ci.sh
#
#   DESCRIPTION:  ---
#
#       OPTIONS:  ---
#
#  REQUIREMENTS:  ---
#          BUGS:  ---
#         NOTES:  ---
#        AUTHOR:  Emerson Rocha <rocha[at]ieee.org>
#       COMPANY:  EticaAI
#       LICENSE:  Public Domain dedication
#                 SPDX-License-Identifier: Unlicense
#       VERSION:  v1.0
#       CREATED:  2021-05-11 18:04 UTC started as temporarium.sh
#      REVISION:  2021-05-11 19:34 UTC started travis-ci.sh
#===============================================================================
# @see https://docs.travis-ci.com/user/deployment/script/

echo "hello from /systema/infrastructuram/travis-ci.sh"
exit 0

---

---

---

---

[fititnt]

Ok. Agora pelo menos sem erro.

Próximo passo é colocar toda funcionalidade que foi feita manualmente no #5 para o pessoal não precisar saber a fundo infra.

.travis.yml

# @see systema/infrastructuram/temporarium.sh
# @see https://docs.travis-ci.com/user/deployment/script/

# Without specifing language, it would default to ruby and this can fail
# script: bash systema/infrastructuram/travis-ci.sh
# @see https://docs.travis-ci.com/user/languages/minimal-and-generic/
language: generic

deploy:
  provider: script
  script: bash systema/infrastructuram/travis-ci.sh
  on:
    branch: main

[fititnt]

---

---

# ./systema/infrastructuram/travis-ci.sh
(...)
### Recommendations on how to avoid leaking secrets to build logs
# @see https://docs.travis-ci.com/user/best-practices-security#recommendations-on-how-to-avoid-leaking-secrets-to-build-logs
# Despite our best efforts, there are however many ways in which secure
# information can accidentally be exposed. These vary according to what tools
# you are using and what settings you have enabled. Some things to look out for are:
#    settings which duplicate commands to standard output, such as set -x or set -v in your bash scripts
#    displaying environment variables, by running env or printenv
#    printing secrets within the code, for example echo "$SECRET_KEY"
#    using tools that print secrets on error output, such as php -i
#    git commands like git fetch or git push may expose tokens or other secure environment variables
#    mistakes in string escaping
#    settings which increase command verbosity
#    testing tools or plugins that may expose secrets while operating
echo "HAPI_DEPLOY_KEY_TEST: [$HAPI_DEPLOY_KEY_TEST]"

echo "hello from /systema/infrastructuram/travis-ci.sh"
exit 0

---

---

Humm...

[fititnt]

Finalmente o #5 está totalmente automatizado via GitHub actions! Ótimo.

Creio que antes de começar a ter mais movimento por aqui, também uma base do template visual poderia já existir. Isso salvaria trabalho depois para quem for gerenciar o frontend.

[fititnt]

Estamos testando alguma estratégia para permitir executar plugins jekyll/ruby (motivação aqui https://github.com/HXL-CPLP/Auxilium-Humanitarium-API/issues/9#issuecomment-841706968).

Ainda que primeira tentativa tenha dado um errinho (isso creio que é questão de ajustes) o fato de usar uma extensão diferente para isso parece adicionar pelo menos 2min30s a mais.

Não que isso seja algo ruim, mas apenas para mencionar que 'o custo' de usar GitHub Pages (sem plugins) via GitHub actions dificilmente levaria a estourar quota gratuita do GitHub.

E que se formos usar a nova estratégia, ainda que 2-3 minutos esteja ok, faz diferença podermos usar cache.

peaceiris/actions-gh-pages@v3 (GitHub pages, sem plugins)

• https://github.com/HXL-CPLP/Auxilium-Humanitarium-API/runs/2591753918

jeffreytse/jekyll-deploy-action@v0.2.1 (GitHub pages, permite plugins)

• https://github.com/HXL-CPLP/Auxilium-Humanitarium-API/runs/2592101076

---

Edit: adicionado imagens com marcação verde

[fititnt]

Humm... Ok. Como o novo plugin usa GitHub Personal Tokens (em vez do outro que usa Deploy Key, aka SSH keys) parece fazer sentido a gente precisar re-autorizar o @eticaaibot no HXL-CPLP/hapi.etica.ai.

Estou deixando escrito aqui pois pode ser útil para quem quiser usar a a versão anterior e também saber as diferenças com a nova.

• https://github.com/HXL-CPLP/Auxilium-Humanitarium-API/runs/2592330143

remote: Permission to HXL-CPLP/hapi.etica.ai.git denied to eticaaibot.
fatal: unable to access 'https://***@github.com/HXL-CPLP/hapi.etica.ai.git/': The requested URL returned error: 403

---

[fititnt]

Agora sim! Finalmente voltou a funcionar! <3

Antes estavamos usando o peaceiris/actions-gh-pages@v3 (que, sinceramente, é o que maioria das pessoas deveria escolher, é mais simples e mais rápido).

Agora estamos com o jeffreytse/jekyll-deploy-action@v0.2.1, (https://github.com/jeffreytse/jekyll-deploy-action), que permite executar plugins extras. Nosso caso é bem mais avançado.

Diferenças em relação ao peaceiris/actions-gh-pages@v3

1. Sem suporte a Deploy Keys (precisa usar GitHub Personal Tokens, porem como já tinhamos o @eticaaibot, é aceitável, porém recomendo não usarem própria conta se forem ter projeto compartilhado!)
2. Sem suporte para definir o destination_dir: como o peaceiris/actions-gh-pages@v3 (por isso prints em anexo mostram o que foi alterado, para publicar em / e não /docs)
3. Ele consome em torno de 2min22 segundos apenas para inicializar. (é aceitável, bem aceitável)

---

---

---

---

[fititnt]

O GitHub Actions (https://github.com/HXL-CPLP/Auxilium-Humanitarium-API/actions) está temporariamente fora do ar (https://www.githubstatus.com/).

Descobri isso ao tentar reportar aviso em https://support.github.com/contact pensando que era algum bug com nosso projeto, mas logo deve estar resolvido.

O site continua no ar. É so temporariamente envio de novas versões

---

Prints

---

---

---

[fititnt]

Vide

• [Hapi versão Alpha] Fluxo de trabalho de de traduções até geração do Hapi (do website, dos schemas e das OpenAPI) #13.

Creio que podemos fechar esse tópico. Já existe a automação, porém agora é refinar como tradutores podem colaborar.