Skip to content

Clonando el repositorio en un UCS / host de instalación

Lee en tu idioma: English · Português · Español

Estado del alcance (post-congelación de alcance 2026-05-10) — Ver ARCHITECTURE.md para los 37 MÓDULOs canónicos + 7 Test Kinds + arquitectura de safety DOM/CPOS/PIE-PA. ADRs 0014, 0019-0025 cubren adiciones post-Freeze.

Secuencia de onboarding: Acceso → Clone ← estás aquí → Instalar · alternativa: Instalación air-gap · setup del mantenedor: Private Repo Setup Este documento cubre las cuatro opciones de autenticación para git clone en un servidor (típicamente un Cisco UCS) donde vas a instalar TLSStress.Art. El repositorio es privado — clone anónimo no funciona.

Elige tu opción

Opción Cuándo elegirla Tiempo de setup Vida útil de la auth
A — GitHub CLI Primera instalación, laptop con browser disponible 2 min Hasta revocar manualmente
B — Deploy key (SSH) Instalación permanente + git pull automatizado 5 min Hasta remover la clave
C — Personal Access Token (PAT) PoV rápido, máquina descartable 1 min Vida del token (definida en la creación)
D — Tarball Air-gapped, sin permiso de git en el host 1 min One-shot

Si estás siguiendo RUNBOOK_FIRST_INSTALL.es.md por primera vez, usa la Opción A. Es el caso más común y rota el token solo.

Opción A — GitHub CLI (recomendada para primera instalación)

ssh ucs-1.example.com
sudo apt update && sudo apt install -y gh
gh auth login
# Elige:
#   - GitHub.com
#   - HTTPS
#   - Authenticate Git with credentials
#   - Login with a web browser
# Copia el código de 8 dígitos mostrado en el terminal del UCS,
# abre la URL en tu laptop, pega el código, autoriza.

mkdir -p ~/tlsstress && cd ~/tlsstress
gh repo clone nollagluiz/AI_forSE .

Qué pasa: gh guarda un token OAuth en ~/.config/gh/hosts.yml con permisos para los repos a los que tienes acceso. Comandos git clone https://github.com/... subsecuentes también funcionan porque gh se registra como Git credential helper.

Pros: Token rota solo, MFA-aware (si tu cuenta usa MFA, gh lo maneja), una sola herramienta para gestionar auth.

Cons: Requiere interacción con browser una vez en el setup (operador abre la URL en su laptop).

Para rotar o revocar: gh auth refresh o gh auth logout.

Opción B — Deploy key SSH (recomendada para instalaciones permanentes)

Una deploy key es una clave SSH registrada contra UN repositorio específico, con permiso read-only. No es tu clave SSH personal. Si el host es comprometido, solo ese repo es afectado — no tu cuenta.

# En el UCS:
ssh-keygen -t ed25519 -C "ucs-host-1@cisco.com" -f ~/.ssh/id_ai_forse_deploy -N ""
cat ~/.ssh/id_ai_forse_deploy.pub
# Copia la clave pública impresa al clipboard.

# En la UI web de GitHub (tú, como admin del repositorio):
# 1. Navega a https://github.com/nollagluiz/AI_forSE/settings/keys
# 2. Click "Add deploy key"
# 3. Title: "UCS-1 lab.example.com"
# 4. Key: pega la clave pública
# 5. ☐ Allow write access — DEJA SIN MARCAR (read-only es lo correcto para installs)
# 6. Save

# De vuelta en el UCS — añade entrada SSH config para que git use la clave correcta:
cat >> ~/.ssh/config <<'EOF'
Host github.com-ai_forse
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ai_forse_deploy
  IdentitiesOnly yes
EOF
chmod 600 ~/.ssh/config

mkdir -p ~/tlsstress && cd ~/tlsstress
git clone git@github.com-ai_forse:nollagluiz/AI_forSE.git .

Qué pasa: GitHub registra la clave pública en el repo. Cualquier conexión SSH autenticada con la clave privada correspondiente gana acceso de lectura al repo.

Pros: Setup zero-interactivo, scripteable, audit-loggable por clave, revocable por host sin afectar otros operadores.

Cons: Admin del repositorio (tú) debe añadir la clave una vez por UCS. Clave SSH en disco necesita protección de filesystem (chmod 600).

Para revocar: en la UI de GitHub, Settings → Deploy keys → Delete. El siguiente git pull desde ese host falla inmediatamente.

Opción C — Personal Access Token (PAT) vía HTTPS (rápido / temporal)

# En cualquier browser:
# 1. Navega a https://github.com/settings/tokens?type=beta
# 2. "Generate new token" → fine-grained
# 3. Resource owner: nollagluiz
# 4. Repository access: Only select repositories → AI_forSE
# 5. Permissions → Repository → Contents: Read-only
# 6. Define expiration: 30–90 días
# 7. Generate, copia el token (mostrado UNA VEZ)

# En el UCS:
mkdir -p ~/tlsstress && cd ~/tlsstress
git clone https://github.com/nollagluiz/AI_forSE.git .
# Cuando pregunte:
#   Username: <tu username GitHub>
#   Password: <pega el PAT>

# Opcional — almacena credenciales para que no pregunte de nuevo:
git config --global credential.helper store
# AVISO: escribe ~/.git-credentials en texto plano. Aceptable para máquina
# de PoV descartable; NO aceptable para instalaciones permanentes.
# Mejor: credential.helper cache  (en memoria, expira tras 15 min)

Pros: Camino más rápido. Funciona en cualquier host con git instalado.

Cons: PAT en texto plano en disco si usas credential.helper store. Token expira; debes rotar. PAT pertenece a una persona, no al host — si esa persona sale de Cisco, el token debe ser regenerado.

Para revocar: GitHub Settings → Developer settings → Personal access tokens → Revoke.

Opción D — Tarball (no requiere git)

Útil cuando: - Política del host prohíbe instalación de git - Instalación es air-gapped (operador lleva el artefacto manualmente) - Quieres un snapshot en un SHA conocido, sin sorpresas de git pull

# En una máquina con internet + auth gh CLI:
gh release download --repo nollagluiz/AI_forSE --archive=tar.gz -O ai_forse-latest.tar.gz

# O tag específico:
gh release download v3.6.0 --repo nollagluiz/AI_forSE --archive=tar.gz -O ai_forse-v3.6.0.tar.gz

# O vía curl + REST (funciona sin gh):
curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $GH_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  "https://api.github.com/repos/nollagluiz/AI_forSE/tarball/main" \
  -o ai_forse-main.tar.gz

# Transfiere el .tar.gz al UCS por tu método (scp, USB, etc.)
# En el UCS:
mkdir -p ~/tlsstress && cd ~/tlsstress
tar -xzf ai_forse-main.tar.gz --strip-components=1

Pros: Sin git en el host, sin clave SSH, sin PAT en disco. Snapshot simple.

Cons: Sin git pull para upgrades — descargas un tarball nuevo cada vez. Pierdes audit trail de git log.

Para ambientes air-gapped, descarga también el manifest asset-hashes.txt del mismo release (tras PR #187 entrar) y verifica SHA-256 de cada YAML/Caddyfile antes de aplicar.

Verificando que el clone está intacto

Tras cualquiera de las opciones arriba:

cd ~/tlsstress
git log -1 --oneline 2>/dev/null || echo "sin historial git (tarball)"
ls -1 | head -10
# esperado: agent  cloner  dashboard  docs  k6-agent  k8s  observability
#           personas  persona-seeder  platform  scripts  webserver  ...

du -sh .
# esperado: ~80 MB

Si usaste Opción B (deploy key) o Opción C (PAT), confirma que git pull aún funciona: 

git pull
# debe reportar "Already up to date." (ya que recién clonaste)

Trampas comunes

Síntoma Causa probable Corrección
Permission denied (publickey) Clave SSH errada en el path, o deploy key no añadida ssh -vT git@github.com-ai_forse para debug; verifica que el fingerprint de la clave coincide con lo que GitHub muestra en Settings → Deploy keys
fatal: could not read Username Clone HTTPS sin credential helper, sin PAT solicitado Usa gh auth setup-git tras gh auth login, o define credential.helper store y re-clone
fatal: unable to access ... 403 PAT sin permiso Contents: Read Regenera PAT con scope correcto; verifica resource owner = nollagluiz
tar: Cannot extract (tarball) Descarga truncada Re-descarga; verifica tamaño del archivo coincide con Content-Length de la respuesta de la API
gh: Bad credentials Token gh revocado, expirado, o SSO de la org no autorizado gh auth logout && gh auth login

Consideraciones de privacidad y auditoría

  • Opción A loguea en la API de GitHub como sesión gh-CLI del usuario. Visible en el audit log del usuario.
  • Opción B loguea cada fetch como fingerprint de la deploy-key. Visible en el audit log de deploy-keys del repo.
  • Opción C loguea como dueño del PAT. Actividad del PAT está en el audit log del token personal del usuario.
  • Opción D no produce entrada de log de evento de clone; solo el API call a /tarball/main es logueado.

Para rastrear quién clonó el repo cuándo, prefiere Opciones A o B.

Relacionados