Octokit Python 使用教程：工作流管理与数据分析功能实操

? Octokit Python 安装与认证：开启 GitHub 自动化之旅

要想用 Octokit Python 玩转 GitHub 工作流和数据分析，第一步得把工具装好。咱直接通过 pip 安装就行，打开终端敲上 pip install octokit ，等一会儿就能安装好。装完之后，得搞定认证问题，毕竟要访问 GitHub 的数据，没权限可不行。

Octokit Python 支持多种认证方式，常用的是个人访问令牌（Personal Access Token）。你先登录 GitHub，进入设置里的开发者设置，生成一个令牌，记得给令牌勾选合适的权限，像 repo、workflow 这些权限都得按需选上。拿到令牌后，在代码里这么用：

python

from octokit import Octokit

octokit = Octokit(auth="你的个人访问令牌")

这样就完成了认证，接下来就能用这个 octokit 对象去调用 GitHub 的 API 啦。

? 工作流管理实操：从创建到监控全流程

? 创建自定义工作流

GitHub 工作流通常是通过 YAML 文件定义的，Octokit Python 能帮咱们方便地创建和管理这些工作流。比如咱想在代码推送到 main 分支时运行一个测试工作流，先得准备好工作流的 YAML 内容，像这样：

yaml

name: Test Workflow
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: Run tests
      run: python -m pytest

然后用 Octokit Python 把这个文件放到仓库的 .github/workflows/ 目录下。代码大概是这样的：

python

repo_owner = "你的用户名"
repo_name = "你的仓库名"
workflow_path = ".github/workflows/test_workflow.yml"
workflow_content = "刚才写的 YAML 内容"

octokit.rest.repos.create_or_update_file_contents(
    owner=repo_owner,
    repo=repo_name,
    path=workflow_path,
    message="Add test workflow",
    content=workflow_content.encode("utf-8").hex(),
    sha=get_existing_file_sha(octokit, repo_owner, repo_name, workflow_path)  # 如果文件不存在，sha 可以设为 None
)

这里有个小细节要注意，获取现有文件的 SHA 是为了更新文件时用，要是文件不存在，就直接创建。

? 查询工作流运行状态

工作流创建好之后，咱们得知道它什么时候运行，运行结果咋样。Octokit Python 提供了接口来获取工作流列表和运行状态。比如获取仓库里所有的工作流：

python

workflows = octokit.rest.actions.list_repo_workflows(
    owner=repo_owner,
    repo=repo_name
).data

for workflow in workflows:
    print(f"工作流名称：{workflow['name']}，ID：{workflow['id']}")

要是想查看某个工作流的具体运行记录，得先拿到工作流的 ID，然后用这个 ID 去获取运行列表：

python

workflow_id =   # 替换成实际的工作流 ID
runs = octokit.rest.actions.list_workflow_runs(
    owner=repo_owner,
    repo=repo_name,
    workflow_id=workflow_id
).data

for run in runs:
    print(f"运行 ID：{run['id']}，状态：{run['status']}，结论：{run['conclusion']}")

这里要注意，状态可能是 “in_progress”“completed” 等，结论可能是 “success”“failure” 等，通过这些信息就能清楚工作流的运行情况。

⚡ 手动触发工作流运行

有时候咱们想手动触发工作流运行，比如代码合并后想提前跑一下部署工作流。Octokit Python 也能实现这个功能，不过得确保工作流支持手动触发，也就是在 YAML 里配置了 workflow_dispatch 事件。

触发的代码是这样的：

python

octokit.rest.actions.create_workflow_dispatch(
    owner=repo_owner,
    repo=repo_name,
    workflow_id=workflow_id
)

触发之后，再通过前面查询运行状态的方法，就能看到新的运行记录啦。

? 数据分析功能实操：从数据提取到可视化

? 获取仓库核心数据

Octokit Python 能获取仓库的各种数据，比如提交记录、 Issues、Pull Requests 等。先拿获取提交记录来说，指定仓库和分支，就能拿到提交列表：

python

commits = octokit.rest.repos.list_commits(
    owner=repo_owner,
    repo=repo_name,
    sha="main"
).data

for commit in commits:
    print(f"提交哈希：{commit['sha']}，作者：{commit['commit']['author']['name']}，提交时间：{commit['commit']['author']['date']}")

获取 Issues 和 Pull Requests 时，注意它们的状态参数，比如获取打开状态的 Issues：

python

issues = octokit.rest.issues.list_repo_issues(
    owner=repo_owner,
    repo=repo_name,
    state="open"
).data

? 处理数据生成统计报表

拿到数据之后，咱们得处理一下，生成有价值的统计报表。比如统计每个月的提交次数，先把提交时间转换成月份，然后用字典统计：

python

from datetime import datetime

monthly_commits = {}
for commit in commits:
    commit_date = datetime.strptime(commit['commit']['author']['date'], "%Y-%m-%dT%H:%M:%SZ")
    month = commit_date.strftime("%Y-%m")
    if month in monthly_commits:
        monthly_commits[month] += 
    else:
        monthly_commits[month] = 

print("每月提交次数：")
for month, count in monthly_commits.items():
    print(f"{month}：{count} 次")

再比如统计 Issues 的状态分布，用一个字典记录不同状态的数量：

python

issue_status = {}
for issue in issues:
    status = issue['state']
    if status in issue_status:
        issue_status[status] += 
    else:
        issue_status[status] = 

print("Issues 状态分布：")
for status, count in issue_status.items():
    print(f"{status}：{count} 个")

? 可视化数据助力决策

数据处理完了，可视化一下更直观。咱们可以用 matplotlib 库来绘制图表，比如绘制每月提交次数的折线图：

python

import matplotlib.pyplot as plt

months = list(monthly_commits.keys())
counts = list(monthly_commits.values())

plt.figure(figsize=(, ))
plt.plot(months, counts, marker='o')
plt.title("每月提交次数趋势")
plt.xlabel("月份")
plt.ylabel("提交次数")
plt.xticks(rotation=)
plt.grid(True)
plt.show()

绘制 Issues 状态分布的饼图：

python

plt.figure(figsize=(, ))
plt.pie(counts, labels=statuses, autopct='%1.1f%%')
plt.title("Issues 状态分布")
plt.axis('equal')
plt.show()

这里要注意，用 matplotlib 之前得先安装，通过 pip install matplotlib 就能安装。

? 常见问题解决：让操作更顺畅

❌ 认证失败怎么办

要是认证失败，先检查个人访问令牌是否正确，有没有过期，权限是否足够。可以重新生成一个令牌，确保在代码里正确使用。另外，检查网络是否正常，有时候网络问题也会导致认证失败。

? 数据获取不完整咋回事

数据获取不完整可能是因为 GitHub API 的分页机制，Octokit Python 返回的数据默认是第一页，每页最多 100 条。这时候需要处理分页，比如用 page 和 per_page 参数获取更多数据：

python

page = 
per_page = 
while True:
    commits = octokit.rest.repos.list_commits(
        owner=repo_owner,
        repo=repo_name,
        sha="main",
        page=page,
        per_page=per_page
    ).data
    if not commits:
        break
    # 处理当前页的数据
    page +=

? 工作流未触发怎么处理

工作流未触发时，先检查工作流的 YAML 文件是否正确，事件配置是否符合触发条件，比如分支名称是否正确，有没有错别字。另外，手动触发工作流时，确保工作流支持 workflow_dispatch 事件。

? 进阶技巧：提升操作效率

? 使用异步请求

如果需要处理大量数据，同步请求可能会比较慢，Octokit Python 支持异步请求，能提升效率。使用异步方式时，需要用 aiohttp 库，安装之后，代码大概是这样的：

python

import asyncio
from octokit import AsyncOctokit

async def main():
    async with AsyncOctokit(auth="你的个人访问令牌") as octokit:
        workflows = await octokit.rest.actions.list_repo_workflows(
            owner=repo_owner,
            repo=repo_name
        )
        print(workflows.data)

asyncio.run(main())

? 自定义数据处理函数

把常用的数据处理逻辑封装成函数，比如统计提交次数、分析 Issues 状态等，这样代码更整洁，复用性也更高。比如封装一个统计提交次数的函数：

python

def count_monthly_commits(commits):
    monthly_commits = {}
    for commit in commits:
        commit_date = datetime.strptime(commit['commit']['author']['date'], "%Y-%m-%dT%H:%M:%SZ")
        month = commit_date.strftime("%Y-%m")
        monthly_commits[month] = monthly_commits.get(month, ) + 
    return monthly_commits

? 批量处理操作

在创建多个工作流或者处理大量数据时，用循环批量处理，避免重复写代码。比如批量创建多个工作流文件，先把工作流内容存到一个列表里，然后循环创建：

python

workflow_configs = [
    {"name": "test_workflow.yml", "content": "第一个工作流内容"},
    {"name": "deploy_workflow.yml", "content": "第二个工作流内容"}
]

for config in workflow_configs:
    octokit.rest.repos.create_or_update_file_contents(
        owner=repo_owner,
        repo=repo_name,
        path=f".github/workflows/{config['name']}",
        message=f"Add {config['name']}",
        content=config['content'].encode("utf-8").hex(),
        sha=get_existing_file_sha(octokit, repo_owner, repo_name, f".github/workflows/{config['name']}")
    )