SSH 连接 GitHub

1.目的与前置条件

1.1 目的

• 使用 Ed25519 算法生成高强度密钥对，实现本地与 GitHub 之间的免密 SSH 认证。

• 统一权限、命名、配置标准，规避因权限或密钥管理不当导致的连接失败与安全风险。

• 为云原生运维中的配置管理、应用部署、流水线（如 ArgoCD、Flux）提供可靠的 Git 接入基础。

1.2 前置条件

• 操作系统：Linux（Ubuntu / CentOS 等）或 macOS，已安装 git 与 ssh 客户端。

• 拥有 GitHub 账号且具备仓库操作权限。

• 网络可直连 github.com:22

2.生成 SSH 密钥对（Ed25519）

# 生成密钥对，注释应包含“主机名-用途-日期”等标识
ssh-keygen -t ed25519 -C "$(hostname)-github-$(date +%Y%m%d)" -f ~/.ssh/id_ed25519_github -N ""

• 专用文件名 id_ed25519_github 区分不同平台（如 GitLab、内部 Git 服务器），便于多密钥管理。

• 注释中至少包含主机名与日期，方便审计与吊销。

• 关于密钥口令（passphrase）：生产环境推荐设置口令以保护私钥，可配合 ssh-agent 使用，避免明文私钥泄露后直接滥用。

  • 若场景允许，可将 -N "" 改为交互式输入口令。

3.严控文件权限（关键）

# 确保 ~/.ssh 目录权限 700
chmod 700 ~/.ssh

# 私钥文件权限必须为 600
chmod 600 ~/.ssh/id_ed25519_github

# 公钥文件权限 644（可读即可）
chmod 644 ~/.ssh/id_ed25519_github.pub

SSH 客户端会强制检查权限，过于宽松（如目录 770、私钥 644）将直接拒绝连接，并报 Permissions 0xxx for '...' are too open 错误。

4.添加公钥至 GitHub

4.1 复制公钥内容

cat ~/.ssh/id_ed25519_github.pub

选中并复制完整输出（以 ssh-ed25519 开头，以注释结尾）。

4.2 在 GitHub 中登记

1. 登陆 GitHub.com → Settings → SSH and GPG keys。

2. 点击 New SSH key。

3. Title：填入与注释一致或更具可读性的标识，如 jenkins-node01-20260510。

4. Key type：选择 Authentication Key。

5. Key：粘贴公钥全文，点击 Add SSH key。

5.测试 SSH 连接

ssh -T git@github.com

成功提示：

Hi <username>! You've successfully authenticated, but GitHub does not provide shell access.

若失败，运行 ssh -vT git@github.com 查看详细诊断信息，常见原因：权限错误、公钥未添加、网络不通、代理未配置。

6.Git 全局用户配置

git config --global user.name "TestUser"                        # 建议改为企业邮箱前缀或工号
git config --global user.email "TestUser@gmail.com"             # 企业场景必须使用公司邮箱

user.email 必须为公司在职邮箱，否则提交记录可能无法被内部 Git 审计、代码评审平台（如 Gerrit、GitLab）识别。

可使用 git config --global --list 确认。

7.常见工作流与安全操作

核心原则

• 严禁直接向 main / master 等受保护分支推送。

• 所有代码变更必须通过特性分支 + Pull Request（PR）合并。

• 强制推送（--force 系列）在保护分支上绝对禁止。

7.1 日常协作：基于 main 创建特性分支并提 PR

# 1. 克隆仓库
git clone git@github.com:Company/your-repo.git
cd your-repo

# 2. 拉取最新的 main（确保本地不过时）
git checkout main
git pull origin main

# 3. 从 main 顶部创建特性分支（命名规范：feat/ 或 fix/）
git checkout -b feat/add-health-check

# 4. 进行修改，并提交
echo "change" > some-file.yaml
git add .
git commit -m "feat: add health check endpoint config"

# 5. 推送特性分支到远端
git push -u origin feat/add-health-check

# 6. 进入 GitHub 仓库页面，创建 Pull Request
#  源分支：feat/add-health-check → 目标分支：main
#  填写变更说明，指定审核人，等待审批与 CI 检查

合并权限：通常由仓库维护者或自动化合并，个人不得在有保护规则的情况下直接合并到 main。

7.2 首次初始化新仓库

仅在仓库刚建立、分支保护规则未生效时，允许初始化推送。但完成后必须立即开启保护。

# 1. 本地初始化
mkdir new-service
cd new-service
git init
git checkout -b main

echo "# New Service" > README.md
git add .
git commit -m "Initial commit"

# 2. 关联远程并推送（绝不可用 --force）
git remote add origin git@github.com:Company/new-service.git
git push -u origin main

立即设置保护：
GitHub 仓库 → Settings → Branches → Add classic branch protection rule

• 进入设置：进入你的GitHub仓库页面，点击顶部导航栏的 “Settings”（设置）。

• 找到规则：在左侧菜单的“Code and automation”（代码与自动化）部分，点击 “Branches”（分支）。

• 添加规则：点击 “Add classic branch protection rule” 按钮。

• 指定分支名：在“Branch name pattern”输入框里，填上你要保护的分支，比如 main。

• 勾选关键配置：

  • ✅ Require a pull request before merging (合并前必须发起PR)：这是核心。勾选后，任何人都无法直接将代码推送到main分支，必须通过PR。

  • ✅ Require approvals (要求审批)：建议设置为1或更多，确保代码有人看过才能合入。

  • ✅ Require status checks to pass before merging (合并前必须通过状态检查)：如果你设置了CI/CD（持续集成/部署），可以勾选此选项，确保所有自动化测试通过后才能合并。

  • ✅ Do not allow bypassing the above settings (不允许绕过以上设置)：这一项非常重要。勾选后，之前以“Include administrators”形式存在的管理员特权会被关闭。这意味着包括你自己在内的任何人都必须遵守这些规则。

• 保存规则：滚动到底部，点击绿色的 “Create” 或 “Save changes” 按钮。

完成以上设置后，你再尝试直接git push origin main，就会被GitHub拒绝，这正是设置生效的表现。你之后所有的代码改动，都需要通过创建Pull Request来进行。

7.3  错误操作警示

git push origin main

尝试直接写入受保护分支，推送被拒；安全告警

git push --force-with-lease origin main

强制覆盖主分支历史，丢失团队提交，P0 事故

git branch -M main 后直接 push

试图用本地重命名覆盖远程保护策略，误解协作流程，提交不被允许

记住：凡是绕过 PR 直接修改 main 的操作，都是生产环境的绝对禁区。

8.补充实践

• 密钥生命周期管理：定期轮换（建议 90~180 天），离职员工密钥立即吊销。

• 无口令密钥与 CI/CD：用于 Jenkins、Tekton、Argo Workflows 的部署密钥（Deploy Key）建议仅授予只读权限，并单独生成，不与个人开发密钥混用。

• GitOps 连接测试：在部署 ArgoCD 或 Flux 前，务必通过 ssh -T git@github.com 验证集群内 Pod 是否可成功认证。

• 安全扫描：将 ~/.ssh 目录纳入合规基线检查，权限不符合自动告警。

9.故障排查速查表

Permission denied (publickey)

公钥未添加/权限不对，ssh -Tv git@github.com，核对 GitHub 已登记公钥，重设权限 600/700

ssh: connect … port 22: Connection timed out

防火墙拦截 22 端口，用 nc -vz github.com 22 确认；改用 SSH over HTTPS（443 端口）

Too many authentication failures

客户端尝试了过多密钥，在 ~/.ssh/config 中设 IdentitiesOnly yes

Host key verification failed

主机指纹记录不符，
检查 DNS 劫持或代理；可删除 known_hosts 中对应行重试

error: GH006: Protected branch update failed …

直接推送到受保护分支，改用特性分支 + Pull Request，遵守分支保护

10.协作铁律汇总

 严禁行为

• 直接 push 到 main / master

• 对共享分支使用 --force 系列

• 使用个人邮箱提交公库代码

• 私钥在团队内拷贝共享

 合规操作

• 通过 feat/xxx 分支发起 PR，审核后合并

• 永远不在受保护分支上强制推送；如有必要，与团队协商并临时关闭保护

• 配置公司邮箱 user.email

• 每人独立生成，定期轮换，私钥不离开本机