@leoferolive/self-workflows
v1.0.2
Published
CLI scaffolding tool for deploying applications to K3s with GitHub Actions
Maintainers
Readme
self-workflows
Reusable CI/CD workflows and scaffolding tools for K3s deployments
Ferramenta de scaffolding para criar aplicações com infraestrutura CI/CD automatizada para deploy em cluster K3s via GitHub Actions.
Visão Geral
O self-workflows fornece:
- Workflows CI/CD reutilizáveis via GitHub Actions
- CLI de scaffolding para criar novas aplicações rapidamente
- Templates Kubernetes prontos para deploy
- Suporte a backend (Java/Spring Boot) e frontend (Node.js)
- Deploy automatizado para cluster K3s via Tailscale
Pré-requisitos
- K3s cluster rodando em seu homelab
- Tailscale configurado para acesso VPN ao cluster
- GitHub account com GitHub Container Registry habilitado
- Node.js 20+ para usar a CLI de scaffolding
Instalação
Opção 1: Via npm (Recomendado)
# Instalar globalmente
npm install -g @leoferolive/self-workflows
# Ou usar diretamente com npx (sem instalação)
npx @leoferolive/self-workflows backend minha-api -u leoferoliveOpção 2: Via Git Clone (Desenvolvimento)
# Clonar repositório
git clone https://github.com/leoferolive/self-workflows.git
cd self-workflows
# Instalar dependências
npm install
# Instalar CLI globalmente
npm linkUso
Criar Nova Aplicação Backend
new-app backend minha-api -u leoferoliveCriar Nova Aplicação Frontend
new-app frontend meu-app -u leoferoliveOpções Avançadas
# Customizar domínio, versões e réplicas
new-app backend minha-api \
-u leoferolive \
--domain example.com \
--java-version 17 \
--replicas 3
new-app frontend meu-app \
-u leoferolive \
--domain example.com \
--node-version 18 \
--replicas 2Uso via npx (Sem Instalação)
npx @leoferolive/self-workflows backend minha-api -u leoferolive
npx @leoferolive/self-workflows frontend meu-app -u leoferoliveOpções Disponíveis
| Opção | Descrição | Padrão |
|-------|-----------|--------|
| -u, --user <github-user> | Usuário do GitHub | leoferolive |
| -r, --template-repo <repo> | Repositório de templates | self-workflows |
| --domain <domain> | Domínio para ingress | leoferolive.com.br |
| --java-version <version> | Versão do Java (backend) | 21 |
| --node-version <version> | Versão do Node.js (frontend) | 20 |
| --replicas <count> | Número de réplicas | 1 |
Estrutura do Projeto
Após criar uma aplicação com new-app, a seguinte estrutura será gerada:
minha-api/
├── .github/
│ └── workflows/
│ └── deploy.yml # Workflow CI/CD que chama self-workflows
├── k8s/
│ ├── namespace.yaml # Namespace Kubernetes
│ ├── deployment.yaml # Deployment da aplicação
│ ├── service.yaml # Service interno
│ └── ingress.yaml # Ingress Traefik
├── Dockerfile # Dockerfile multi-stage
└── README.md # Instruções básicasConfiguração do GitHub
Após criar a aplicação e fazer push para o GitHub, configure os seguintes secrets:
Secrets Necessários
- TAILSCALE_AUTHKEY - Auth key do Tailscale
- KUBECONFIG - Config do K3s em base64
Gerar KUBECONFIG em Base64
# Exportar kubeconfig atual
base64 -w 0 ~/.kube/configWorkflow de Deploy
- Push para main → Trigger automático do workflow
- Build & Push → Imagem Docker é buildada e pushada para GHCR
- Deploy → Tailscale conecta ao K3s e aplica manifests Kubernetes
- Rollout → Deployment é atualizado com nova imagem
Stack de Deploy
- Registry: GitHub Container Registry (ghcr.io)
- Pipeline: GitHub Actions
- Cluster: K3s (homelab)
- Networking: Tailscale para acesso VPN
- Ingress: Traefik com entrada via
webentrypoint - Domínio:
{APP_NAME}.{DOMAIN}
Validações de Nome
O nome da aplicação deve seguir estas regras:
- Apenas letras minúsculas, números e hífens
- Não pode começar ou terminar com hífen
- Não pode conter hífens consecutivos
Exemplos válidos: minha-api, app-v2, demo123
Exemplos inválidos: minha_api, Meu-App, app--v1, -app
Desenvolvimento
Estrutura do Repositório
self-workflows/
├── .github/
│ └── workflows/
│ └── deploy.yml # Workflow unificado reutilizável
├── scripts/
│ └── new-app.js # CLI de scaffolding
├── templates/
│ ├── backend/ # Template para backend Java
│ │ ├── .github/workflows/
│ │ ├── k8s/
│ │ └── Dockerfile
│ └── frontend/ # Template para frontend Node.js
│ ├── .github/workflows/
│ ├── k8s/
│ └── Dockerfile
└── package.jsonExecutar CLI em Modo Desenvolvimento
# Executar sem instalar globalmente
node scripts/new-app.js backend test-app -u leoferoliveDesenvolvimento
Configurar Ambiente
# Clonar repositório
git clone https://github.com/leoferolive/self-workflows.git
cd self-workflows
# Instalar dependências
npm install
# Criar link global para testes locais
npm linkScripts Disponíveis
npm run dev # Executa CLI localmente
npm run test # Executa testes
npm run lint # Verifica qualidade do código
npm run lint:fix # Corrige problemas automaticamente
npm run format # Formata código
npm run format:check # Verifica formataçãoPublicar Nova Versão
# 1. Atualizar versão (cria tag e auto-commit)
npm version major|minor|patch
# 2. Fazer push da tag
git push origin main --tags
# 3. GitHub Actions publica automaticamente no npmContribuindo
Contribuições são bem-vindas! Por favor, leia CONTRIBUTING.md para detalhes.
Licença
Este projeto está licenciado sob a licença ISC - veja o arquivo LICENSE para detalhes.
Autor
LeoFerOlive
