1. 为什么你需要一个个人访问令牌如果你在命令行里用git push往 GitHub 推送代码时突然弹出一个窗口让你输入用户名和密码而你明明记得密码是对的却死活登录不上去那你大概率是遇到了 GitHub 在 2021 年 8 月 13 日之后实施的一项重大安全策略变更。简单来说GitHub 不再支持使用账户密码Password通过 HTTPS 协议进行 Git 操作认证了。取而代之的就是今天我们要详细拆解的主角——个人访问令牌。这个令牌英文叫 Personal Access Token你可以把它理解为你账户的一个“专用钥匙”或者“临时工牌”。和你的主密码不同这把钥匙的权限是你可以精细控制的。你可以只给它读取仓库代码的权限也可以给它写入、删除仓库的权限甚至可以给它管理组织、访问包仓库等高级权限。最关键的是这把钥匙是“一次性”的当然可以设置有效期万一泄露了你可以随时单独吊销这把钥匙而无需修改你的主账户密码其他用令牌访问的服务也不会受影响。所以无论你是需要在 CI/CD 流水线如 GitHub Actions, Jenkins中自动拉取推送代码还是用脚本调用 GitHub API 管理你的项目抑或是仅仅想在本地命令行里顺畅地使用 Git创建并配置一个个人访问令牌都是你现在必须掌握的技能。这不仅是绕过密码认证限制的解决方案更是一种更安全、更现代的凭证管理实践。2. 令牌创建前的核心决策权限与有效期直接跳到创建步骤很简单但如果不理解背后的选项你可能会创建出一个权限过大或过小的令牌埋下安全风险或导致后续操作失败。因此在点击“Generate token”按钮之前我们必须先搞清楚两个核心概念作用域和有效期。2.1 作用域给你的令牌划定工作边界作用域决定了这个令牌能干什么。GitHub 提供了非常细粒度的权限控制主要分为以下几大类repo仓库这是最常用、最核心的权限。它下面又细分为repo完全控制私有和公共仓库的代码、议题、拉取请求等。权限极大请谨慎授予。public_repo仅能访问公共仓库。repo:status仅能访问仓库的提交状态常用于CI系统报告构建状态。repo_deployment访问部署状态。repo:invite接受仓库邀请。security_events读写安全事件用于代码扫描。workflow工作流如果你使用 GitHub Actions需要这个权限来启用、禁用工作流文件。write:packages / read:packages包管理用于向 GitHub Packages 推送或拉取容器镜像、npm包等。delete_repo删除仓库顾名思义允许删除仓库。高危权限非必要不勾选。admin:org管理组织管理组织成员、团队等。通常用于自动化管理脚本。user用户访问用户个人资料信息如邮箱。admin:public_key管理公钥管理账户的 SSH 密钥。admin:gpg_key管理GPG密钥管理账户的 GPG 密钥。实操心得最小权限原则我的经验是永远遵循“最小权限原则”。如果你只是需要在本地命令行推送代码到自己的私有仓库那么只勾选repo就足够了。如果你为 CI/CD 流水线创建令牌并且这个流水线只需要拉取代码和推送构建状态那么repo拉取代码 repo:status推送状态可能是更安全的选择。绝对不要因为省事就一股脑地勾选所有权限这相当于给了小偷一把万能钥匙。2.2 有效期为令牌设置一个“保质期”GitHub 允许你为令牌设置一个有效期这是一个非常重要的安全特性。选项通常包括7天30天90天自定义天数最长不超过1年永不过期不推荐为什么强烈不建议选择“永不过期”令牌一旦泄露就拥有了长期有效的访问权限。设置有效期相当于增加了一层时间防火墙。即使令牌不慎泄露攻击者也只能在有效期内作恶。到期后令牌自动失效你需要创建新的这本身也是一次安全审计的机会。对于生产环境的自动化流程我通常设置为90天并建立一个日历提醒在到期前一周进行轮换。对于临时性的脚本或测试7天或30天就足够了。3. 手把手创建你的第一个令牌理解了核心概念后我们进入实操环节。请跟随以下步骤在 GitHub 上创建你的第一个个人访问令牌。3.1 进入令牌创建页面登录你的 GitHub 账户。点击页面右上角的你的头像在下拉菜单中选择“Settings”设置。在左侧边栏的最底部找到并点击“Developer settings”开发者设置。在左侧边栏中点击“Personal access tokens”个人访问令牌。点击“Tokens (classic)”或直接点击“Generate new token”按钮下的“Generate new token (classic)”。目前 GitHub 推荐新的细粒度令牌但经典令牌更通用我们先从经典的开始。3.2 填写令牌信息与配置权限现在你会看到一个表单页面。Note备注这里非常重要不要随便填个“test”。请用一个清晰的名字描述这个令牌的用途例如“My-MacBook-Pro-Git-CLI”、“Company-CI-Jenkins-Production”、“Script-Auto-Create-Repo”。未来当你拥有多个令牌时清晰的备注能帮你快速识别和管理。Expiration有效期根据我们之前的讨论选择一个合适的有效期。例如用于个人电脑的可以选择“90天”。Select scopes选择作用域滚动权限列表根据你的需求勾选。对于最常见的“本地Git推送拉取”场景勾选“repo”这一个就够了。它会自动选中所有仓库相关的子权限。可选Repository access仓库访问如果你只想让令牌访问特定仓库可以在这里选择。默认是“All repositories”。3.3 生成并安全保存令牌滚动到页面底部点击绿色的“Generate token”按钮。关键时刻页面刷新后你会看到一个以ghp_开头的长字符串新格式令牌以github_pat_开头。这个令牌只会在此刻显示一次如果你刷新或离开这个页面就再也看不到它了。你必须立即将其复制并保存到安全的地方。我推荐的做法是密码管理器存入 1Password、Bitwarden、LastPass 等密码管理工具这是最安全的方式。本地加密文件如果你不使用密码管理器可以将其保存在本地一个加密的文本文件或使用gpg加密。绝对禁止不要将其写入普通的文本文件不要提交到 Git 仓库不要通过明文邮件或聊天工具发送。复制保存后这个令牌就可以使用了。你可以在 “Personal access tokens” 列表页面看到它但只能看到部分打码的字符并可以随时在这里将其吊销。4. 在 Git 命令行中使用令牌创建好令牌后我们需要用它来替代密码。Git 通过 HTTPS 协议克隆或推送时用户名是你的 GitHub 用户名密码就是这个令牌。4.1 首次克隆仓库当你克隆一个私有仓库时在 URL 中直接嵌入令牌是最直接的方法仅用于一次性操作或脚本。git clone https://ghp_你的令牌内容github.com/你的用户名/仓库名.git例如git clone https://ghp_abc123def456github.com/zhangsan/my-private-repo.git4.2 为现有仓库配置远程认证对于已经克隆到本地的仓库或者你不想在URL中暴露令牌更推荐使用 Git 的凭证存储助手。方法一使用缓存临时git config --global credential.helper cache # 可以设置缓存时间默认900秒15分钟例如设置为1小时 git config --global credential.helper cache --timeout3600设置后当你下一次执行git pull或git push时会提示你输入用户名和密码此处密码填令牌。输入一次后在缓存时间内就不再需要输入了。适合临时使用。方法二使用系统存储长期这是更常用的方式令牌会安全地存储在系统的密钥链中。macOS:git config --global credential.helper osxkeychainLinux:git config --global credential.helper libsecret # 或 gnome-keyring, cache, storeWindows:git config --global credential.helper wincred配置好后执行一次需要认证的操作如git push在弹出的窗口或命令行中用户名填你的 GitHub 用户名密码填刚才生成的个人访问令牌。之后系统就会记住这个凭证。方法三在远程 URL 中永久配置不推荐但需了解你也可以直接修改远程仓库的 URL将令牌写进去。但这样做令牌会以明文形式出现在.git/config文件中。git remote set-url origin https://ghp_你的令牌内容github.com/你的用户名/仓库名.git踩坑实录认证失败的常见原因用户名错误密码/令牌栏填对了但用户名栏填的是邮箱地址或其他内容。请确保用户名是你的 GitHub 登录用户名通常不含邮箱域名。令牌权限不足如果你只勾选了public_repo却试图推送私有仓库就会失败。检查令牌的作用域。令牌已过期创建时设置了有效期到期后令牌自动失效。去 GitHub 设置页面检查令牌状态并创建新的。凭证助手冲突如果你之前用其他方式存储了错误的密码系统可能会一直尝试旧的错误凭证。可以尝试清除缓存# 对于 cache git credential-cache exit # 或直接删除全局配置重新设置 git config --global --unset credential.helper然后在执行操作时重新输入。5. 在自动化脚本与 CI/CD 中安全使用令牌在自动化环境中我们无法进行交互式输入因此需要将令牌以环境变量或配置文件的形式提供给脚本或 CI/CD 平台。核心原则是绝对不要将令牌硬编码在脚本或代码仓库中。5.1 环境变量法推荐在运行脚本的机器上将令牌设置为环境变量。# Linux/macOS export GITHUB_TOKENghp_你的令牌内容 # 然后你的脚本或命令可以通过 $GITHUB_TOKEN 引用它 # 例如使用 curl 调用 API curl -H Authorization: token $GITHUB_TOKEN https://api.github.com/user# Windows (PowerShell) $env:GITHUB_TOKENghp_你的令牌内容 # 在同一个 PowerShell 会话中生效5.2 在 CI/CD 平台中配置以 GitHub Actions 为例GitHub Actions 提供了最安全的方式来使用令牌。使用内置的GITHUB_TOKEN在每个 GitHub Actions 工作流运行时都会自动生成一个临时的GITHUB_TOKEN密钥并拥有当前仓库的默认权限。你无需自己创建可以直接在 YAML 文件中使用${{ secrets.GITHUB_TOKEN }}。这是最安全、最推荐的方式因为它自动拥有最小权限且生命周期短暂。jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 with: token: ${{ secrets.GITHUB_TOKEN }}使用自定义仓库密钥如果你需要跨仓库访问或者需要GITHUB_TOKEN不具备的权限如访问其他仓库、管理组织则需要将自己创建的个人访问令牌添加到仓库的密钥中。进入你的 GitHub 仓库。点击“Settings”-“Secrets and variables”-“Actions”。点击“New repository secret”。Name 填写为MY_PAT或其他你喜欢的名字。Value 粘贴你的个人访问令牌。在工作流文件中通过${{ secrets.MY_PAT }}来引用它。env: MY_TOKEN: ${{ secrets.MY_PAT }} steps: - run: | echo Using token for API call curl -H Authorization: token $MY_TOKEN https://api.github.com/user/repos注意事项CI/CD 中的令牌安全永远不要echo或print令牌即使在 CI/CD 的日志中也要避免直接输出令牌内容。大多数平台会自动屏蔽以secret.方式引用的变量输出但自己仍需小心。使用最小权限令牌为 CI/CD 创建的令牌权限应精确到所需的最小范围。如果只是拉取代码可能连repo的写权限都不需要可以考虑更细的权限或使用actions/checkout等官方 Action。定期轮换为 CI/CD 设置的令牌也应设置有效期并建立流程定期更新仓库密钥中的值。6. 令牌的进阶管理与安全实践创建和使用令牌只是第一步良好的管理习惯才能确保长期的安全。6.1 令牌的日常管理回到 GitHub 的“Settings” - “Developer settings” - “Personal access tokens”页面这里是你管理所有令牌的控制台。查看与识别你可以看到所有活跃的令牌列表包括备注名、权限范围、上次使用时间和过期时间。清晰的备注名至关重要。吊销令牌如果某个令牌泄露或不再需要立即点击对应的“Revoke”按钮。这是令牌相比密码的最大优势——定点清除不影响其他服务。权限复审定期例如每季度回顾令牌列表检查每个令牌是否还有存在的必要其权限是否仍然合适。6.2 启用双因素认证提升账户安全个人访问令牌是认证的一种方式而保护生成令牌的源头——你的 GitHub 账户——同样重要。强烈建议为你的 GitHub 账户启用双因素认证。启用 2FA 后即使你的密码泄露攻击者没有你的第二因素如手机验证码、安全密钥也无法登录从而无法创建新的令牌或管理现有令牌。这为你的账户增加了一道坚固的防线。你可以在“Settings” - “Password and authentication”中设置 2FA。6.3 令牌泄露的应急处理如果你怀疑或确认某个令牌已经泄露例如发现未知的仓库操作、API调用请立即执行以下步骤立即吊销泄露的令牌在令牌管理页面找到它并点击“Revoke”。这会立即使该令牌失效所有使用该令牌的客户端和服务将立即失去访问权限。审查日志在“Settings” - “Security” - “Security log”中查看账户的完整活动日志。筛选相关时间段的操作确认是否有未授权的活动。轮换相关凭证如果该令牌用于 CI/CD 或其他重要服务在吊销旧令牌后需要立即创建新令牌并更新所有使用该令牌的服务配置。评估影响根据令牌的权限范围检查是否有仓库被恶意修改、是否有敏感信息被窃取、是否有未知的部署或包发布。必要时回滚代码或数据。7. 经典令牌与细粒度令牌的选择在创建令牌时你可能注意到了 GitHub 在推广新的“细粒度个人访问令牌”。这里简单对比一下帮助你做选择特性经典个人访问令牌细粒度个人访问令牌权限模型粗粒度基于预定义的作用域如repo,admin:org。一个作用域内权限全有或全无。极细粒度可以精确到单个仓库的读/写权限甚至仓库内特定区域如议题、拉取请求。资源访问通常可以访问用户有权访问的所有资源如所有仓库。创建时必须指定可以访问的特定仓库或所有仓库权限在资源上也是细分的。有效期最长1年或永不过期。最长1年不能设置为永不过期。适用场景通用场景需要访问多个仓库或宽泛权限的自动化脚本、命令行工具。对安全性要求极高的场景需要将权限限制在特定仓库和特定操作例如只为某个第三方应用授权访问单个仓库的议题。当前状态仍可使用但 GitHub 可能会在未来停止支持。GitHub 推荐使用代表更现代的、更安全的权限管理方向。个人建议对于个人在命令行中使用或者需要宽泛权限的自动化脚本例如管理自己所有仓库的脚本经典令牌目前更简单直接。对于授予第三方应用集成或者CI/CD 中需要访问特定仓库的场景强烈建议使用细粒度令牌。它能实现最小权限原则的极致大幅降低安全风险。长远来看逐渐迁移到细粒度令牌是更佳实践。创建细粒度令牌的流程类似只是在权限选择界面变成了可逐项展开的、按仓库和权限类型勾选的树状结构更加直观。创建和管理个人访问令牌从最初的“绕过密码认证的权宜之计”已经演变为现代开发工作流中不可或缺的安全凭证管理环节。理解其原理谨慎分配权限妥善保管并定期审计这些习惯能让你的自动化流程既高效又稳固。下次当你的git push遇到认证问题时你应该能从容地打开 GitHub 设置页面生成一把合适的“钥匙”并知道如何安全地使用它了。