Skip to content

Clonando o repositório num UCS / host de instalação

Leia no seu idioma: English · Português · Español

Status do escopo (pós-congelamento de escopo 2026-05-10) — Ver ARCHITECTURE.md para os 37 MÓDULOs canônicos + 7 Test Kinds + arquitetura de safety DOM/CPOS/PIE-PA. ADRs 0014, 0019-0025 cobrem adições pós-Freeze.

Sequência de onboarding: Acesso → Clone ← você está aqui → Instalar · alternativa: Instalação air-gap · setup do mantenedor: Private Repo Setup Este documento cobre as quatro opções de autenticação para git clone num servidor (tipicamente um Cisco UCS) onde você vai instalar o TLSStress.Art. O repositório é privado — clone anônimo não funciona.

Escolha sua opção

Opção Quando escolher Tempo de setup Vida útil da auth
A — GitHub CLI Primeira instalação, laptop com browser disponível 2 min Até revogar manualmente
B — Deploy key (SSH) Instalação permanente + git pull automatizado 5 min Até remover a chave
C — Personal Access Token (PAT) PoV rápido, máquina descartável 1 min Validade do token (definida na criação)
D — Tarball Air-gapped, sem permissão de git no host 1 min One-shot

Se você está seguindo RUNBOOK_FIRST_INSTALL.pt-BR.md pela primeira vez, use a Opção A. É o caso mais comum e rotaciona o token sozinho.

Opção A — GitHub CLI (recomendada para primeira instalação)

ssh ucs-1.example.com
sudo apt update && sudo apt install -y gh
gh auth login
# Escolha:
#   - GitHub.com
#   - HTTPS
#   - Authenticate Git with credentials
#   - Login with a web browser
# Copie o código de 8 dígitos mostrado no terminal do UCS,
# abra a URL no seu laptop, cole o código, autorize.

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

O que acontece: gh salva um token OAuth em ~/.config/gh/hosts.yml com permissões para os repos que você tem acesso. Comandos git clone https://github.com/... subsequentes também funcionam porque gh se registra como Git credential helper.

Vantagens: Token rotaciona sozinho, MFA-aware (se sua conta usa MFA, gh resolve), uma única ferramenta para gerenciar auth.

Desvantagens: Requer interação com browser uma vez no setup (operador abre a URL no laptop dele).

Para rotacionar ou revogar: gh auth refresh ou gh auth logout.

Opção B — Deploy key SSH (recomendada para instalações permanentes)

Uma deploy key é uma chave SSH registrada contra UM repositório específico, com permissão read-only. Não é sua chave SSH pessoal. Se o host for comprometido, só esse repo é afetado — não sua conta.

# No 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
# Copie a chave pública impressa para o clipboard.

# Na UI web do GitHub (você, como admin do repositório):
# 1. Navegue para https://github.com/nollagluiz/AI_forSE/settings/keys
# 2. Click "Add deploy key"
# 3. Title: "UCS-1 lab.example.com"
# 4. Key: cole a chave pública
# 5. ☐ Allow write access — DEIXE DESMARCADO (read-only é o correto para instalações)
# 6. Save

# De volta no UCS — adicione entrada SSH config para que git use a chave certa:
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 .

O que acontece: GitHub registra a chave pública no repo. Qualquer conexão SSH autenticada com a chave privada correspondente ganha acesso de leitura ao repo.

Vantagens: Setup zero-interativo, scriptável, audit-loggable por chave, revogável por host sem afetar outros operadores.

Desvantagens: Admin do repositório (você) precisa adicionar a chave uma vez por UCS. Chave SSH em disco precisa de proteção do filesystem (chmod 600).

Para revogar: na UI do GitHub, Settings → Deploy keys → Delete. O próximo git pull daquele host falha imediatamente.

Opção C — Personal Access Token (PAT) via HTTPS (rápido / temporário)

# Em qualquer browser:
# 1. Navegue para 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. Defina expiration: 30–90 dias
# 7. Generate, copie o token (mostrado UMA VEZ)

# No UCS:
mkdir -p ~/tlsstress && cd ~/tlsstress
git clone https://github.com/nollagluiz/AI_forSE.git .
# Quando perguntar:
#   Username: <seu username GitHub>
#   Password: <cole o PAT>

# Opcional — armazene credenciais para não perguntar de novo:
git config --global credential.helper store
# AVISO: escreve ~/.git-credentials em texto plano. Aceitável para máquina
# de PoV descartável; NÃO aceitável para instalações permanentes.
# Melhor: credential.helper cache  (em memória, expira após 15 min)

Vantagens: Caminho mais rápido. Funciona em qualquer host com git instalado.

Desvantagens: PAT em texto plano em disco se usar credential.helper store. Token expira; você precisa rotacionar. PAT pertence a uma pessoa, não ao host — se essa pessoa sair da Cisco, o token precisa ser regerado.

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

Opção D — Tarball (não requer git)

Útil quando: - Política do host proíbe instalação de git - Instalação é air-gapped (operador carrega o artefato manualmente) - Você quer um snapshot num SHA conhecido, sem surpresas de git pull

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

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

# Ou via curl + REST (funciona sem 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

# Transfira o .tar.gz para o UCS pelo seu método (scp, USB, etc.)
# No UCS:
mkdir -p ~/tlsstress && cd ~/tlsstress
tar -xzf ai_forse-main.tar.gz --strip-components=1

Vantagens: Sem git no host, sem chave SSH, sem PAT em disco. Snapshot simples.

Desvantagens: Sem git pull para upgrades — você re-baixa um tarball novo cada vez. Perde audit trail do git log.

Para ambientes air-gapped, baixe também o manifest asset-hashes.txt da mesma release (após PR #187 entrar) e verifique SHA-256 de cada YAML/Caddyfile antes de aplicar.

Verificando que o clone está intacto

Após qualquer das opções acima:

cd ~/tlsstress
git log -1 --oneline 2>/dev/null || echo "sem histórico 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

Se você usou Opção B (deploy key) ou Opção C (PAT), confirme que git pull ainda funciona: 

git pull
# deve reportar "Already up to date." (já que você acabou de clonar)

Pegadinhas comuns

Sintoma Causa provável Correção
Permission denied (publickey) Chave SSH errada no path, ou deploy key não adicionada ssh -vT git@github.com-ai_forse para debug; verifique que fingerprint da chave bate com o que GitHub mostra em Settings → Deploy keys
fatal: could not read Username Clone HTTPS sem credential helper, sem PAT requisitado Use gh auth setup-git após gh auth login, ou defina credential.helper store e re-clone
fatal: unable to access ... 403 PAT sem permissão Contents: Read Regere PAT com escopo correto; verifique resource owner = nollagluiz
tar: Cannot extract (tarball) Download truncado Re-baixe; verifique tamanho do arquivo bate com Content-Length da resposta da API
gh: Bad credentials Token gh revogado, expirado, ou SSO da org não autorizado gh auth logout && gh auth login

Considerações de privacidade e auditoria

  • Opção A loga na API do GitHub como sessão gh-CLI do usuário. Visível no audit log do usuário.
  • Opção B loga cada fetch como fingerprint da deploy-key. Visível no audit log de deploy-keys do repo.
  • Opção C loga como dono do PAT. Atividade do PAT está no audit log do token pessoal do usuário.
  • Opção D não produz entrada de log de evento de clone; só o API call para /tarball/main é logado.

Para rastrear quem clonou o repo quando, prefira Opções A ou B.

Relacionados