1. 為什么你需要一個個人訪問令牌如果你在命令行里用git push往 GitHub 推送代碼時突然彈出一個窗口讓你輸入用戶名和密碼而你明明記得密碼是對的卻死活登錄不上去那你大概率是遇到了 GitHub 在 2021 年 8 月 13 日之后實施的一項重大安全策略變更。簡單來說GitHub 不再支持使用賬戶密碼Password通過 HTTPS 協(xié)議進行 Git 操作認證了。取而代之的就是今天我們要詳細拆解的主角——個人訪問令牌。這個令牌英文叫 Personal Access Token你可以把它理解為你賬戶的一個“專用鑰匙”或者“臨時工牌”。和你的主密碼不同這把鑰匙的權(quán)限是你可以精細控制的。你可以只給它讀取倉庫代碼的權(quán)限也可以給它寫入、刪除倉庫的權(quán)限甚至可以給它管理組織、訪問包倉庫等高級權(quán)限。最關鍵的是這把鑰匙是“一次性”的當然可以設置有效期萬一泄露了你可以隨時單獨吊銷這把鑰匙而無需修改你的主賬戶密碼其他用令牌訪問的服務也不會受影響。所以無論你是需要在 CI/CD 流水線如 GitHub Actions, Jenkins中自動拉取推送代碼還是用腳本調(diào)用 GitHub API 管理你的項目抑或是僅僅想在本地命令行里順暢地使用 Git創(chuàng)建并配置一個個人訪問令牌都是你現(xiàn)在必須掌握的技能。這不僅是繞過密碼認證限制的解決方案更是一種更安全、更現(xiàn)代的憑證管理實踐。2. 令牌創(chuàng)建前的核心決策權(quán)限與有效期直接跳到創(chuàng)建步驟很簡單但如果不理解背后的選項你可能會創(chuàng)建出一個權(quán)限過大或過小的令牌埋下安全風險或?qū)е潞罄m(xù)操作失敗。因此在點擊“Generate token”按鈕之前我們必須先搞清楚兩個核心概念作用域和有效期。2.1 作用域給你的令牌劃定工作邊界作用域決定了這個令牌能干什么。GitHub 提供了非常細粒度的權(quán)限控制主要分為以下幾大類repo倉庫這是最常用、最核心的權(quán)限。它下面又細分為repo完全控制私有和公共倉庫的代碼、議題、拉取請求等。權(quán)限極大請謹慎授予。public_repo僅能訪問公共倉庫。repo:status僅能訪問倉庫的提交狀態(tài)常用于CI系統(tǒng)報告構(gòu)建狀態(tài)。repo_deployment訪問部署狀態(tài)。repo:invite接受倉庫邀請。security_events讀寫安全事件用于代碼掃描。workflow工作流如果你使用 GitHub Actions需要這個權(quán)限來啟用、禁用工作流文件。write:packages / read:packages包管理用于向 GitHub Packages 推送或拉取容器鏡像、npm包等。delete_repo刪除倉庫顧名思義允許刪除倉庫。高危權(quán)限非必要不勾選。admin:org管理組織管理組織成員、團隊等。通常用于自動化管理腳本。user用戶訪問用戶個人資料信息如郵箱。admin:public_key管理公鑰管理賬戶的 SSH 密鑰。admin:gpg_key管理GPG密鑰管理賬戶的 GPG 密鑰。實操心得最小權(quán)限原則我的經(jīng)驗是永遠遵循“最小權(quán)限原則”。如果你只是需要在本地命令行推送代碼到自己的私有倉庫那么只勾選repo就足夠了。如果你為 CI/CD 流水線創(chuàng)建令牌并且這個流水線只需要拉取代碼和推送構(gòu)建狀態(tài)那么repo拉取代碼 repo:status推送狀態(tài)可能是更安全的選擇。絕對不要因為省事就一股腦地勾選所有權(quán)限這相當于給了小偷一把萬能鑰匙。2.2 有效期為令牌設置一個“保質(zhì)期”GitHub 允許你為令牌設置一個有效期這是一個非常重要的安全特性。選項通常包括7天30天90天自定義天數(shù)最長不超過1年永不過期不推薦為什么強烈不建議選擇“永不過期”令牌一旦泄露就擁有了長期有效的訪問權(quán)限。設置有效期相當于增加了一層時間防火墻。即使令牌不慎泄露攻擊者也只能在有效期內(nèi)作惡。到期后令牌自動失效你需要創(chuàng)建新的這本身也是一次安全審計的機會。對于生產(chǎn)環(huán)境的自動化流程我通常設置為90天并建立一個日歷提醒在到期前一周進行輪換。對于臨時性的腳本或測試7天或30天就足夠了。3. 手把手創(chuàng)建你的第一個令牌理解了核心概念后我們進入實操環(huán)節(jié)。請跟隨以下步驟在 GitHub 上創(chuàng)建你的第一個個人訪問令牌。3.1 進入令牌創(chuàng)建頁面登錄你的 GitHub 賬戶。點擊頁面右上角的你的頭像在下拉菜單中選擇“Settings”設置。在左側(cè)邊欄的最底部找到并點擊“Developer settings”開發(fā)者設置。在左側(cè)邊欄中點擊“Personal access tokens”個人訪問令牌。點擊“Tokens (classic)”或直接點擊“Generate new token”按鈕下的“Generate new token (classic)”。目前 GitHub 推薦新的細粒度令牌但經(jīng)典令牌更通用我們先從經(jīng)典的開始。3.2 填寫令牌信息與配置權(quán)限現(xiàn)在你會看到一個表單頁面。Note備注這里非常重要不要隨便填個“test”。請用一個清晰的名字描述這個令牌的用途例如“My-MacBook-Pro-Git-CLI”、“Company-CI-Jenkins-Production”、“Script-Auto-Create-Repo”。未來當你擁有多個令牌時清晰的備注能幫你快速識別和管理。Expiration有效期根據(jù)我們之前的討論選擇一個合適的有效期。例如用于個人電腦的可以選擇“90天”。Select scopes選擇作用域滾動權(quán)限列表根據(jù)你的需求勾選。對于最常見的“本地Git推送拉取”場景勾選“repo”這一個就夠了。它會自動選中所有倉庫相關的子權(quán)限?？蛇xRepository access倉庫訪問如果你只想讓令牌訪問特定倉庫可以在這里選擇。默認是“All repositories”。3.3 生成并安全保存令牌滾動到頁面底部點擊綠色的“Generate token”按鈕。關鍵時刻頁面刷新后你會看到一個以ghp_開頭的長字符串新格式令牌以github_pat_開頭。這個令牌只會在此刻顯示一次如果你刷新或離開這個頁面就再也看不到它了。你必須立即將其復制并保存到安全的地方。我推薦的做法是密碼管理器存入 1Password、Bitwarden、LastPass 等密碼管理工具這是最安全的方式。本地加密文件如果你不使用密碼管理器可以將其保存在本地一個加密的文本文件或使用gpg加密。絕對禁止不要將其寫入普通的文本文件不要提交到 Git 倉庫不要通過明文郵件或聊天工具發(fā)送。復制保存后這個令牌就可以使用了。你可以在 “Personal access tokens” 列表頁面看到它但只能看到部分打碼的字符并可以隨時在這里將其吊銷。4. 在 Git 命令行中使用令牌創(chuàng)建好令牌后我們需要用它來替代密碼。Git 通過 HTTPS 協(xié)議克隆或推送時用戶名是你的 GitHub 用戶名密碼就是這個令牌。4.1 首次克隆倉庫當你克隆一個私有倉庫時在 URL 中直接嵌入令牌是最直接的方法僅用于一次性操作或腳本。git clone https://ghp_你的令牌內(nèi)容github.com/你的用戶名/倉庫名.git例如git clone https://ghp_abc123def456github.com/zhangsan/my-private-repo.git4.2 為現(xiàn)有倉庫配置遠程認證對于已經(jīng)克隆到本地的倉庫或者你不想在URL中暴露令牌更推薦使用 Git 的憑證存儲助手。方法一使用緩存臨時git config --global credential.helper cache # 可以設置緩存時間默認900秒15分鐘例如設置為1小時 git config --global credential.helper cache --timeout3600設置后當你下一次執(zhí)行g(shù)it pull或git push時會提示你輸入用戶名和密碼此處密碼填令牌。輸入一次后在緩存時間內(nèi)就不再需要輸入了。適合臨時使用。方法二使用系統(tǒng)存儲長期這是更常用的方式令牌會安全地存儲在系統(tǒng)的密鑰鏈中。macOS:git config --global credential.helper osxkeychainLinux:git config --global credential.helper libsecret # 或 gnome-keyring, cache, storeWindows:git config --global credential.helper wincred配置好后執(zhí)行一次需要認證的操作如git push在彈出的窗口或命令行中用戶名填你的 GitHub 用戶名密碼填剛才生成的個人訪問令牌。之后系統(tǒng)就會記住這個憑證。方法三在遠程 URL 中永久配置不推薦但需了解你也可以直接修改遠程倉庫的 URL將令牌寫進去。但這樣做令牌會以明文形式出現(xiàn)在.git/config文件中。git remote set-url origin https://ghp_你的令牌內(nèi)容github.com/你的用戶名/倉庫名.git踩坑實錄認證失敗的常見原因用戶名錯誤密碼/令牌欄填對了但用戶名欄填的是郵箱地址或其他內(nèi)容。請確保用戶名是你的 GitHub 登錄用戶名通常不含郵箱域名。令牌權(quán)限不足如果你只勾選了public_repo卻試圖推送私有倉庫就會失敗。檢查令牌的作用域。令牌已過期創(chuàng)建時設置了有效期到期后令牌自動失效。去 GitHub 設置頁面檢查令牌狀態(tài)并創(chuàng)建新的。憑證助手沖突如果你之前用其他方式存儲了錯誤的密碼系統(tǒng)可能會一直嘗試舊的錯誤憑證。可以嘗試清除緩存# 對于 cache git credential-cache exit # 或直接刪除全局配置重新設置 git config --global --unset credential.helper然后在執(zhí)行操作時重新輸入。5. 在自動化腳本與 CI/CD 中安全使用令牌在自動化環(huán)境中我們無法進行交互式輸入因此需要將令牌以環(huán)境變量或配置文件的形式提供給腳本或 CI/CD 平臺。核心原則是絕對不要將令牌硬編碼在腳本或代碼倉庫中。5.1 環(huán)境變量法推薦在運行腳本的機器上將令牌設置為環(huán)境變量。# Linux/macOS export GITHUB_TOKENghp_你的令牌內(nèi)容 # 然后你的腳本或命令可以通過 $GITHUB_TOKEN 引用它 # 例如使用 curl 調(diào)用 API curl -H Authorization: token $GITHUB_TOKEN https://api.github.com/user# Windows (PowerShell) $env:GITHUB_TOKENghp_你的令牌內(nèi)容 # 在同一個 PowerShell 會話中生效5.2 在 CI/CD 平臺中配置以 GitHub Actions 為例GitHub Actions 提供了最安全的方式來使用令牌。使用內(nèi)置的GITHUB_TOKEN在每個 GitHub Actions 工作流運行時都會自動生成一個臨時的GITHUB_TOKEN密鑰并擁有當前倉庫的默認權(quán)限。你無需自己創(chuàng)建可以直接在 YAML 文件中使用${{ secrets.GITHUB_TOKEN }}。這是最安全、最推薦的方式因為它自動擁有最小權(quán)限且生命周期短暫。jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 with: token: ${{ secrets.GITHUB_TOKEN }}使用自定義倉庫密鑰如果你需要跨倉庫訪問或者需要GITHUB_TOKEN不具備的權(quán)限如訪問其他倉庫、管理組織則需要將自己創(chuàng)建的個人訪問令牌添加到倉庫的密鑰中。進入你的 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 的日志中也要避免直接輸出令牌內(nèi)容。大多數(shù)平臺會自動屏蔽以secret.方式引用的變量輸出但自己仍需小心。使用最小權(quán)限令牌為 CI/CD 創(chuàng)建的令牌權(quán)限應精確到所需的最小范圍。如果只是拉取代碼可能連repo的寫權(quán)限都不需要可以考慮更細的權(quán)限或使用actions/checkout等官方 Action。定期輪換為 CI/CD 設置的令牌也應設置有效期并建立流程定期更新倉庫密鑰中的值。6. 令牌的進階管理與安全實踐創(chuàng)建和使用令牌只是第一步良好的管理習慣才能確保長期的安全。6.1 令牌的日常管理回到 GitHub 的“Settings” - “Developer settings” - “Personal access tokens”頁面這里是你管理所有令牌的控制臺。查看與識別你可以看到所有活躍的令牌列表包括備注名、權(quán)限范圍、上次使用時間和過期時間。清晰的備注名至關重要。吊銷令牌如果某個令牌泄露或不再需要立即點擊對應的“Revoke”按鈕。這是令牌相比密碼的最大優(yōu)勢——定點清除不影響其他服務。權(quán)限復審定期例如每季度回顧令牌列表檢查每個令牌是否還有存在的必要其權(quán)限是否仍然合適。6.2 啟用雙因素認證提升賬戶安全個人訪問令牌是認證的一種方式而保護生成令牌的源頭——你的 GitHub 賬戶——同樣重要。強烈建議為你的 GitHub 賬戶啟用雙因素認證。啟用 2FA 后即使你的密碼泄露攻擊者沒有你的第二因素如手機驗證碼、安全密鑰也無法登錄從而無法創(chuàng)建新的令牌或管理現(xiàn)有令牌。這為你的賬戶增加了一道堅固的防線。你可以在“Settings” - “Password and authentication”中設置 2FA。6.3 令牌泄露的應急處理如果你懷疑或確認某個令牌已經(jīng)泄露例如發(fā)現(xiàn)未知的倉庫操作、API調(diào)用請立即執(zhí)行以下步驟立即吊銷泄露的令牌在令牌管理頁面找到它并點擊“Revoke”。這會立即使該令牌失效所有使用該令牌的客戶端和服務將立即失去訪問權(quán)限。審查日志在“Settings” - “Security” - “Security log”中查看賬戶的完整活動日志。篩選相關時間段的操作確認是否有未授權(quán)的活動。輪換相關憑證如果該令牌用于 CI/CD 或其他重要服務在吊銷舊令牌后需要立即創(chuàng)建新令牌并更新所有使用該令牌的服務配置。評估影響根據(jù)令牌的權(quán)限范圍檢查是否有倉庫被惡意修改、是否有敏感信息被竊取、是否有未知的部署或包發(fā)布。必要時回滾代碼或數(shù)據(jù)。7. 經(jīng)典令牌與細粒度令牌的選擇在創(chuàng)建令牌時你可能注意到了 GitHub 在推廣新的“細粒度個人訪問令牌”。這里簡單對比一下幫助你做選擇特性經(jīng)典個人訪問令牌細粒度個人訪問令牌權(quán)限模型粗粒度基于預定義的作用域如repo,admin:org。一個作用域內(nèi)權(quán)限全有或全無。極細粒度可以精確到單個倉庫的讀/寫權(quán)限甚至倉庫內(nèi)特定區(qū)域如議題、拉取請求。資源訪問通常可以訪問用戶有權(quán)訪問的所有資源如所有倉庫。創(chuàng)建時必須指定可以訪問的特定倉庫或所有倉庫權(quán)限在資源上也是細分的。有效期最長1年或永不過期。最長1年不能設置為永不過期。適用場景通用場景需要訪問多個倉庫或?qū)挿簷?quán)限的自動化腳本、命令行工具。對安全性要求極高的場景需要將權(quán)限限制在特定倉庫和特定操作例如只為某個第三方應用授權(quán)訪問單個倉庫的議題。當前狀態(tài)仍可使用但 GitHub 可能會在未來停止支持。GitHub 推薦使用代表更現(xiàn)代的、更安全的權(quán)限管理方向。個人建議對于個人在命令行中使用或者需要寬泛權(quán)限的自動化腳本例如管理自己所有倉庫的腳本經(jīng)典令牌目前更簡單直接。對于授予第三方應用集成或者CI/CD 中需要訪問特定倉庫的場景強烈建議使用細粒度令牌。它能實現(xiàn)最小權(quán)限原則的極致大幅降低安全風險。長遠來看逐漸遷移到細粒度令牌是更佳實踐。創(chuàng)建細粒度令牌的流程類似只是在權(quán)限選擇界面變成了可逐項展開的、按倉庫和權(quán)限類型勾選的樹狀結(jié)構(gòu)更加直觀。創(chuàng)建和管理個人訪問令牌從最初的“繞過密碼認證的權(quán)宜之計”已經(jīng)演變?yōu)楝F(xiàn)代開發(fā)工作流中不可或缺的安全憑證管理環(huán)節(jié)。理解其原理謹慎分配權(quán)限妥善保管并定期審計這些習慣能讓你的自動化流程既高效又穩(wěn)固。下次當你的git push遇到認證問題時你應該能從容地打開 GitHub 設置頁面生成一把合適的“鑰匙”并知道如何安全地使用它了。