如何用 GitHub Actions 自部署 GitHub Readme Stats，并统计私有仓库数据

目录背景介绍通过 GitHub Actions 自部署 GitHub Readme Stats如何使用 GitHub Actions 配置统计私有仓库数据1. 生成 Personal Access Token (PAT) 以统计私有仓库**如何生成 Personal Access Token (PAT)**2. 使用 GitHub Secrets 存储 PAT3. 为什么默认配置无法统计私有仓库4. 修改配置以支持私有仓库统计想要更好的阅读体验点击直接这里查看原文背景介绍经常逛 GitHub 的人应该都见过个人主页上的这种统计卡片。这背后常见的实现方案就是GitHub Readme Stats。它的统计原理是通过调用 GitHub API 获取用户的公共或私有数据然后通过动态生成的 SVG 图像呈现出来。但是最近由于用户量的增加GitHub Readme Stats的公共实例在 Vercel 上面临了流量和额度超限的问题导致许多用户无法加载其统计卡片。官方在其 GitHub 仓库的说明中指出这件事有多严重呢比如下面不仅我自己的统计无法显示甚至 GitHub Readme Stats 官方仓库的统计也无法显示了。官方声明中提到虽然公共实例通过缓存来提高稳定性但由于流量高峰和 API 限制卡片显示已经不再稳定。为了避免此问题官方建议用户自行托管服务如 Vercel 或其他平台或者使用GitHub Actions工作流生成卡片并存储在个人仓库中。下面就介绍一种几乎零维护的方案直接用 GitHub Actions 生成静态 SVG同时支持私有仓库统计。通过 GitHub Actions 自部署 GitHub Readme Stats为了避免公共实例的流量限制可以选择通过GitHub Actions自行部署 GitHub Readme Stats。这种方法最简单不需要自行设置服务器相比于自己部署 Vercel 服务它的部署过程更方便。只需要在个人 GitHub 仓库中配置一次 GitHub Actions 工作流GitHub 将自动为你生成并更新统计卡片避免了公共服务的限制。这个方法甚至不需要 fork 官方仓库只需要在自己的 README 仓库也就是与你 GitHub 用户名同名的仓库中新建一个 workflow 即可。比如我的仓库原来只有一个README.md文件现在只需要新建.github/workflows/github-readme-stats.yml填入以下内容name:Update README cardson:schedule:-cron:0 3 * * *# 每天更新一次workflow_dispatch:# 允许手动触发permissions:contents:write# 允许工作流提交生成后的 SVGjobs:build:runs-on:ubuntu-lateststeps:-uses:actions/checkoutv6-name:Generate stats carduses:readme-tools/github-readme-stats-actionv1with:card:statsoptions:username${{github.repository_owner}}show_iconstruepath:profile/stats.svgtoken:${{secrets.GITHUB_TOKEN}}-name:Generate top languages carduses:readme-tools/github-readme-stats-actionv1with:card:top-langsoptions:username${{github.repository_owner}}layoutcompactlangs_count6path:profile/top-langs.svgtoken:${{secrets.GITHUB_TOKEN}}-name:Commit cardsrun:|git config user.name github-actions[bot] git config user.email 41898282github-actions[bot]users.noreply.github.com git add profile/*.svg git commit -m Update README cards || exit 0 git push注意这里生成的图片位置分别是profile/stats.svg和profile/top-langs.svg所以需要你在README.md中把原来对公共实例的引用替换成本仓库里的静态文件例如 然后提交代码。由于上述配置是每天生成一次所以第一次通常需要你到 GitHub Actions 页面手动触发一次。如何使用 GitHub Actions 配置统计私有仓库数据1. 生成 Personal Access Token (PAT) 以统计私有仓库如果你希望通过GitHub Actions统计私有仓库的数据必须生成一个Personal Access Token (PAT)因为默认工作流中使用的GITHUB_TOKEN更适合当前仓库内的自动化操作并不适合拿来读取你账号下所有私有仓库的统计信息。要统计私有仓库数据更稳妥的做法是使用你自己创建的PAT。如何生成 Personal Access Token (PAT)登录 GitHub访问 GitHub 并登录到你的账户。进入开发者设置在 GitHub 首页右上角点击头像选择Settings。在左侧菜单中选择Developer settings。生成 Personal Access Token在Developer settings中选择Personal access tokens。如果只是为了统计私有仓库建议直接使用Tokens (classic)。点击Generate new token创建一个新的 token。根据 GitHub Readme Stats 官方说明如果要读取私有仓库统计至少需要以下权限repo允许访问私有仓库。read:user访问用户数据用于获取贡献信息等。官方文档还提到fine-grained token在这个场景下对私有贡献统计并不理想因此这里更推荐 classic PAT。生成并保存 Token设置Token description例如 “GitHub Stats Token”并选择所需的权限。点击Generate token生成后保存好这个 Token。注意PAT生成后只能在此页面显示一次因此请务必将其保存好。如果丢失你将无法查看这个 Token只能重新生成。2. 使用 GitHub Secrets 存储 PAT为了避免将PAT直接暴露在工作流文件中这将会泄露敏感信息我们使用GitHub Secrets来存储 Token。GitHub Secrets是加密存储的环境变量它可以在 GitHub Actions 中安全地使用而不会被公开。进入仓库的 Settings在 GitHub README 这个仓库也就是与你用户名同名的仓库页面点击右上角的Settings。创建新的 Secret在左侧菜单中选择Secrets and variables→Actions。点击New repository secret。在Name中输入GH_TOKEN这是我们后续在工作流文件中使用的环境变量名称。在Value中粘贴你生成的Personal Access Token (PAT)。点击Add secret保存。在 GitHub Actions 中使用 Secret你可以通过${{ secrets.GH_TOKEN }}来引用在Secrets中存储的 Token。3. 为什么默认配置无法统计私有仓库上面官方给出的基础配置无法统计私有仓库数据是因为在那个配置中使用的是token: ${{ secrets.GITHUB_TOKEN }}根据 GitHub Readme Stats 官方文档默认的GITHUB_TOKEN仅适用于公开统计如果要统计私有仓库则需要改用带repo和read:user权限的PAT。4. 修改配置以支持私有仓库统计为了确保 GitHub Actions 能统计私有仓库的数据我们需要修改配置文件使用Personal Access Token (PAT)并将其存储在GitHub Secrets中。以下是完整的工作流配置name:Update README cardson:schedule:-cron:0 6 * * *# 每天早上6点更新workflow_dispatch:# 允许手动触发permissions:contents:write# 允许 GitHub Actions 写入仓库内容jobs:build:runs-on:ubuntu-lateststeps:-uses:actions/checkoutv6-name:Generate stats carduses:readme-tools/github-readme-stats-actionv1with:card:statsoptions:username${{github.repository_owner}}show_iconstruepath:profile/stats.svgtoken:${{secrets.GH_TOKEN}}# 使用 GitHub Secrets 中存储的 PAT-name:Generate top languages carduses:readme-tools/github-readme-stats-actionv1with:card:top-langsoptions:username${{github.repository_owner}}layoutcompactlangs_count6path:profile/top-langs.svgtoken:${{secrets.GH_TOKEN}}-name:Commit cardsrun:|git config user.name github-actions[bot] git config user.email 41898282github-actions[bot]users.noreply.github.com git add profile/*.svg git commit -m Update README cards || exit 0 git push配置解析permissions: contents: write确保 GitHub Actions 有权限将生成的卡片推送到仓库。token: ${{ secrets.GH_TOKEN }}使用存储在 GitHub Secrets 中的PAT允许读取私有仓库统计数据。top-langs额外生成语言分布卡片避免只生成总览 stats 卡片。cron: 0 6 * * *设置工作流每天凌晨六点自动更新统计卡片。这种方法也有缺点就是更新不够及时比如我的配置是一天一次。但是因为这个方法实在太简单太方便了足以抵消这些缺点。