gitops-new-project

name: gitops-new-project description: Use when scaffolding a complete new GitOps project including namespaces, dev/hmg/stg/prod overlays, ArgoCD Applications, and AppProject version: 1.0.0 owner: platform-governance tier: full source: .enterprise/governance/agent-skills/gitops-new-project/SKILL.md quick: .enterprise/governance/agent-skills/gitops-new-project/SKILL-QUICK.md portable: true license: Apache-2.0

GitOps New Project — Guia Completo

Quando usar

Carregue esta skill quando o usuário pedir:

• novo projeto no k8s, novo projeto, criar projeto
• bootstrapar projeto, bootstrap k8s, onboarding k8s
• scaffoldar projeto, scaffold projeto
• configurar projeto no cluster, registrar projeto no ArgoCD
• adicionar projeto ao gitops, estrutura k8s para projeto
• iniciar projeto no Kubernetes, subir projeto do zero
• criar estrutura gitops, criar namespace, criar ArgoCD app

PASSO 1 — Coletar informações

1. Nome do projeto — kebab-case (ex: payment-gateway)
2. Serviços iniciais — para cada: nome, imagem, porta, tipo (http-api|worker|fpm)
3. Infraestrutura — PostgreSQL | MySQL | Redis | RabbitMQ | NATS | Kafka | Nenhuma
4. Ambientes — default: dev hmg stg prod
5. Ingress em dev? — domínio (ex: payment-gateway.hideakiservicos.net)

PASSO 2 — Ler projetos de referência

Antes de criar qualquer arquivo, leia:

• apps/cambio-real-services-dev.yaml — template de ArgoCD Application (services)
• apps/cambio-real-infra-dev.yaml — template de ArgoCD Application (infra, sem prune)
• argocd/base/appproject-cambio-real.yaml — template de AppProject
• cambio-real/scripts/bootstrap-dev.sh — template de bootstrap script

PASSO 3 — Criar manifests de services

<project>/services/base/kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - <service>-deployment.yaml
  - <service>-service.yaml

<project>/services/overlays/<env>/kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: <project>-<env>
resources:
  - ../../base
commonLabels:
  environment: <env>
  tier: services
images:
  - name: ghcr.io/hideakisolutions/<project>/<service>
    newTag: develop

Criar deployments e services seguindo o padrão do cambio-real (imagePullSecrets, labels, probes).

PASSO 4 — Criar manifests de infra (se solicitado)

<project>/infra/base/ — StatefulSets para cada componente

<project>/infra/overlays/<env>/kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: <project>-<env>
resources:
  - ../../base
commonLabels:
  environment: <env>
  tier: infra

PASSO 5 — Criar ArgoCD Applications

Services app (apps/<project>-services-<env>.yaml) — prune: true

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: <project>-services-<env>
  namespace: argocd
spec:
  project: <project>
  source:
    repoURL: git@github.com:HideakiSolutions/platform-gitops.git
    targetRevision: develop
    path: <project>/services/overlays/<env>
  destination:
    server: https://kubernetes.default.svc
    namespace: <project>-<env>
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

Infra app (apps/<project>-infra-<env>.yaml) — SEM prune (CRÍTICO)

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: <project>-infra-<env>
  namespace: argocd
spec:
  project: <project>
  source:
    repoURL: git@github.com:HideakiSolutions/platform-gitops.git
    targetRevision: develop
    path: <project>/infra/overlays/<env>
  destination:
    server: https://kubernetes.default.svc
    namespace: <project>-<env>
  syncPolicy:
    automated:
      selfHeal: true
      # prune: false (omitido intencionalmente — proteção de PVCs e dados stateful)
    syncOptions:
      - CreateNamespace=true

PASSO 6 — Criar AppProject

argocd/base/appproject-<project>.yaml

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: <project>
  namespace: argocd
spec:
  description: Projeto <project> - acesso restrito
  sourceRepos:
    - git@github.com:HideakiSolutions/platform-gitops.git
  destinations:
    - namespace: <project>-*
      server: https://kubernetes.default.svc
  clusterResourceWhitelist:
    - group: '*'
      kind: '*'
  namespaceResourceWhitelist:
    - group: '*'
      kind: '*'

PASSO 7 — Criar bootstrap script

<project>/scripts/bootstrap-dev.sh — seguir padrão do cambio-real/scripts/bootstrap-dev.sh. Incluir: criar namespace, criar secrets, aplicar ArgoCD apps.

PASSO 8 — Validar

./scripts/ci/validate_project_kustomize.sh <project>

PASSO 9 — Branch e commit

git checkout -b feat/new-project-<project>
git add <project>/
git add apps/<project>-*.yaml
git add argocd/base/appproject-<project>.yaml
git commit -m "feat(platform): add <project> k8s project manifests"
git push origin feat/new-project-<project>

Regra crítica — prune

Quick Mode

For low-context activation, load .enterprise/governance/agent-skills/gitops-new-project/SKILL-QUICK.md or QUICK.md first. Load this full skill for deep analysis, violation fixing, or formal review gates.