Skip to content

Cloning the repository on a UCS / install host

Read in your language: English · Português · Español

Scope status (post-Scope-Freeze 2026-05-10) — See ARCHITECTURE.md for the canonical 37 MÓDULOs + 7 Test Kinds + DOM/CPOS/PIE-PA safety architecture. ADRs 0014, 0019-0025 cover post-Freeze additions.

Onboarding sequence: Access → Clone ← you are here → Install · alternate: Air-gap install · maintainer setup: Private Repo Setup This document covers the four authentication options for git clone on a server (typically a Cisco UCS) where you will install TLSStress.Art. Repository is private — anonymous clone does not work.

Pick your option

Option When to pick it Time to set up Auth lifetime
A — GitHub CLI First install, browser-capable laptop available 2 min Until manually revoked
B — Deploy key (SSH) Permanent install + automated git pull 5 min Until you remove the key
C — Personal Access Token (PAT) Quick PoV, machine you'll discard 1 min Token expiry (set at creation)
D — Tarball Air-gapped, no git allowed on the host 1 min One-shot

If you are following RUNBOOK_FIRST_INSTALL.md for the first time, use Option A. It is the most common case and rotates the token automatically.

ssh ucs-1.example.com
sudo apt update && sudo apt install -y gh
gh auth login
# Choose:
#   - GitHub.com
#   - HTTPS
#   - Authenticate Git with credentials
#   - Login with a web browser
# Copy the 8-digit code shown on the UCS terminal,
# open the URL on your laptop, paste the code, authorize.

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

What happens: gh saves an OAuth token in ~/.config/gh/hosts.yml with permissions for the repos you can access. Subsequent git clone https://github.com/... commands also work because gh registers itself as the Git credential helper.

Pros: Token rotates on its own, MFA-aware (if your account uses MFA, gh handles it), single tool to manage auth.

Cons: Requires browser interaction once at setup (operator opens the URL on their laptop).

To rotate or revoke: gh auth refresh or gh auth logout.

A deploy key is an SSH key registered against ONE specific repository, with read-only permission. It is not your personal SSH key. If the host is compromised, only this repo is affected — not your account.

# On the 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
# Copy the printed public key to your clipboard.

# On the GitHub web UI (you, as repository admin):
# 1. Navigate to https://github.com/nollagluiz/AI_forSE/settings/keys
# 2. Click "Add deploy key"
# 3. Title: "UCS-1 lab.example.com"
# 4. Key: paste the public key
# 5. ☐ Allow write access — LEAVE UNCHECKED (read-only is correct for installs)
# 6. Save

# Back on the UCS — add an SSH config entry so git uses the right key:
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 .

What happens: GitHub registers the public key on the repo. Any SSH connection authenticated with the matching private key gets read access to that repo.

Pros: Zero interactive setup, scriptable, audit-loggable per key, revocable per host without affecting other operators.

Cons: Repository admin (you) must add the key once per UCS. SSH key on disk needs filesystem protection (chmod 600).

To revoke: in GitHub UI, Settings → Deploy keys → Delete. The next git pull from that host fails immediately.

Option C — Personal Access Token (PAT) over HTTPS (quick / temporary)

# On any browser:
# 1. Navigate to 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. Set expiration: 30–90 days
# 7. Generate, copy the token (shown ONCE)

# On the UCS:
mkdir -p ~/tlsstress && cd ~/tlsstress
git clone https://github.com/nollagluiz/AI_forSE.git .
# When prompted:
#   Username: <your GitHub username>
#   Password: <paste the PAT>

# Optional — store credentials so it does not prompt again:
git config --global credential.helper store
# WARNING: writes ~/.git-credentials in plain text. Acceptable for a
# disposable PoV machine; NOT acceptable for permanent installs.
# Better: credential.helper cache  (in-memory, expires after 15 min)

Pros: Fastest path. Works on any host with git installed.

Cons: PAT in plain text on disk if you use credential.helper store. Token expires; you must rotate. PAT belongs to a person, not the host — if that person leaves Cisco, the token must be regenerated.

To revoke: GitHub Settings → Developer settings → Personal access tokens → Revoke.

Option D — Tarball (no git required)

Useful when: - The host policy forbids installing git - The install is air-gapped (operator manually carries the artifact in) - You want a snapshot at a known SHA, with no surprises from git pull

# On a machine with internet + gh CLI auth:
gh release download --repo nollagluiz/AI_forSE --archive=tar.gz -O ai_forse-latest.tar.gz

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

# Or via curl + REST (works without 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

# Transfer the .tar.gz to the UCS via your method (scp, USB, etc.)
# On the UCS:
mkdir -p ~/tlsstress && cd ~/tlsstress
tar -xzf ai_forse-main.tar.gz --strip-components=1

Pros: No git on the host, no SSH key, no PAT on disk. Simple snapshot.

Cons: No git pull for upgrades — you re-download a new tarball each time. Loses the audit trail of git log.

For air-gapped environments, also download the asset-hashes.txt manifest from the same release (after PR #187 ships) and verify SHA-256 of each YAML/Caddyfile before applying.

Verifying the clone is intact

After any of the above:

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

du -sh .
# expected: ~80 MB

If you used Option B (deploy key) or Option C (PAT), confirm git pull still works: 

git pull
# should report "Already up to date." (since you just cloned)

Common pitfalls

Symptom Likely cause Fix
Permission denied (publickey) Wrong SSH key in path, or deploy key not added ssh -vT git@github.com-ai_forse to debug; verify the key fingerprint matches what GitHub shows in Settings → Deploy keys
fatal: could not read Username HTTPS clone without credential helper, no PAT prompted Use gh auth setup-git after gh auth login, or set credential.helper store and re-clone
fatal: unable to access ... 403 PAT lacks Contents: Read permission Regenerate PAT with the correct scope; verify resource owner = nollagluiz
tar: Cannot extract (tarball) Truncated download Re-download; verify file size matches Content-Length from the API response
gh: Bad credentials gh token revoked, expired, or org SSO not authorized gh auth logout && gh auth login

Privacy and audit considerations

  • Option A logs to GitHub's API as the user's gh-CLI session. Visible in the user's audit log.
  • Option B logs each fetch as the deploy-key fingerprint. Visible in the repo's deploy-key audit log.
  • Option C logs as the PAT owner. PAT activity is in the user's personal token audit log.
  • Option D does not produce a clone-event log entry; only the API call to /tarball/main is logged.

For tracing who cloned the repo when, prefer Options A or B.