Bitzsoft.Integrations.ProjectManagement.GitHub 1.0.4

Bitzsoft.Integrations.ProjectManagement.GitHub

GitHub REST API v3 项目与工单连接器实现。遵循项目管理通用抽象规范，实现 IProjectManagementService 接口与专属的 IGitHubProjectManagementService 扩展接口。

功能特性

• 通用契约对齐：实现 IProjectManagementService 抽象规范，统一将 GitHub Repositories 映射为项目空间，Issues 映射为任务，支持创建、更新、完成与列表过滤。
• 灵活鉴权机制：支持 Personal Access Token (PAT) 与 GitHub App Installation Token 鉴权。
• GHES 企业私有化支持：支持配置 GitHub Enterprise Server (GHES) 私有化基地址（如 https://github.corp.internal/api/v3）及自签名 SSL 证书信任（AllowInsecureCertificates）。
• Issue 状态流转管理：专有支持关闭工单（CloseIssueAsync，支持 completed / not_planned 等原因）与重新打开工单（ReopenIssueAsync）。
• Issue 评论流管理：支持读取历史讨论评论（ListCommentsAsync）与发表新评论（AddCommentAsync）。
• 标签与里程碑协同：支持动态为工单打标签（AddLabelsAsync）与查询仓库里程碑（ListMilestonesAsync）。
• 合并请求（Pull Request）读取：支持按编号精准提取 PR 状态、分支与元数据（GetPullRequestAsync）。
• 工业级弹性韧性：集成 Polly 标准韧性管道（429/503 指数退避重试与熔断保护）及全量出站请求审计日志（RequestLogging）。

安装

dotnet add package Bitzsoft.Integrations.ProjectManagement.GitHub

<PackageReference Include="Bitzsoft.Integrations.ProjectManagement.GitHub" Version="1.0.0" />

配置

在 appsettings.json 中配置 GitHub 连接器参数：

{
  "ProjectManagement": {
    "GitHub": {
      "BaseUrl": "https://api.github.com",
      "AccessToken": "ghp_your-personal-access-token",
      "DefaultOwner": "my-organization",
      "DefaultRepo": "my-repository",
      "AllowInsecureCertificates": false,
      "UserAgent": "Bitzsoft-Integrations/1.0"
    }
  }
}

配置项说明

注册服务

支持通过配置源绑定或委托方式进行依赖注入注册：

using Microsoft.Extensions.DependencyInjection;

// 方式 1：通过 IConfiguration 绑定注册（推荐，默认读取 ProjectManagement:GitHub）
services.AddBitzsoftGitHubProjectManagement(configuration);

// 自定义配置节路径：
// services.AddBitzsoftGitHubProjectManagement(configuration, "Integrations:GitHub");

// 方式 2：通过委托手动配置注册
services.AddBitzsoftGitHubProjectManagement(options =>
{
    options.BaseUrl = "https://api.github.com";
    options.AccessToken = "ghp_your-personal-access-token";
    options.DefaultOwner = "my-organization";
    options.DefaultRepo = "my-repository";
    options.AllowInsecureCertificates = false;
});

使用示例（通用 IProjectManagementService）

以下代码演示如何在业务类中通过依赖注入使用通用的 IProjectManagementService 契约操作 GitHub Issues：

using System;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;
using Bitzsoft.Integrations.ProjectManagement;
using Bitzsoft.Integrations.ProjectManagement.Dtos;
using TaskStatus = Bitzsoft.Integrations.ProjectManagement.Dtos.TaskStatus;

namespace YourNamespace;

public class GitHubIssueAppService
{
    private readonly IProjectManagementService _pmService;

    public GitHubIssueAppService(IProjectManagementService pmService)
    {
        _pmService = pmService;
    }

    public async Task<PmTask> ReportIssueAsync(
        string repoPath,
        string title,
        string description,
        string? assignee = null,
        CancellationToken cancellationToken = default)
    {
        var request = new CreateTaskRequest
        {
            ProjectId = repoPath,
            Name = title,
            Description = description,
            AssigneeId = assignee,
            Priority = TaskPriority.High
        };

        return await _pmService.CreateTaskAsync(request, cancellationToken);
    }

    public async Task<PmTask> GetIssueAsync(
        string issueIdOrNumber,
        CancellationToken cancellationToken = default)
    {
        return await _pmService.GetTaskAsync(issueIdOrNumber, cancellationToken);
    }

    public async Task<List<PmTask>> ListOpenIssuesAsync(
        string repoPath,
        CancellationToken cancellationToken = default)
    {
        var request = new ListTasksRequest
        {
            ProjectId = repoPath,
            Status = TaskStatus.Todo,
            PageIndex = 1,
            PageSize = 30
        };

        return await _pmService.ListTasksAsync(request, cancellationToken);
    }

    public async Task<PmResult> CloseIssueAsync(
        string issueIdOrNumber,
        CancellationToken cancellationToken = default)
    {
        return await _pmService.CompleteTaskAsync(issueIdOrNumber, cancellationToken);
    }
}

专有扩展能力（IGitHubProjectManagementService）

当业务需要调用 GitHub 专属特性（如评论追加与检索、标签批量设置、工单关闭/重新打开、拉取请求详情查询、里程碑列表等）时，可直接注入专属接口 IGitHubProjectManagementService：

using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;
using Bitzsoft.Integrations.ProjectManagement.GitHub;
using Bitzsoft.Integrations.ProjectManagement.GitHub.Dtos;

namespace YourNamespace;

public class GitHubAdvancedCollaborationService
{
    private readonly IGitHubProjectManagementService _gitHubService;

    public GitHubAdvancedCollaborationService(IGitHubProjectManagementService gitHubService)
    {
        _gitHubService = gitHubService;
    }

    public async Task AddCommentAndTagAsync(
        string owner,
        string repo,
        int issueNumber,
        string commentText,
        List<string> tags,
        CancellationToken cancellationToken = default)
    {
        await _gitHubService.AddCommentAsync(
            owner,
            repo,
            issueNumber,
            commentText,
            cancellationToken);

        if (tags.Count > 0)
        {
            await _gitHubService.AddLabelsAsync(
                owner,
                repo,
                issueNumber,
                tags,
                cancellationToken);
        }
    }

    public async Task LifecycleControlAsync(
        string owner,
        string repo,
        int issueNumber,
        bool reopen,
        CancellationToken cancellationToken = default)
    {
        if (reopen)
        {
            await _gitHubService.ReopenIssueAsync(owner, repo, issueNumber, cancellationToken);
        }
        else
        {
            await _gitHubService.CloseIssueAsync(owner, repo, issueNumber, "completed", cancellationToken);
        }
    }

    public async Task<GitHubPullRequestDto> GetPrInfoAsync(
        string owner,
        string repo,
        int prNumber,
        CancellationToken cancellationToken = default)
    {
        return await _gitHubService.GetPullRequestAsync(owner, repo, prNumber, cancellationToken);
    }

    public async Task<List<GitHubMilestoneDto>> GetOpenMilestonesAsync(
        string owner,
        string repo,
        CancellationToken cancellationToken = default)
    {
        return await _gitHubService.ListMilestonesAsync(owner, repo, "open", cancellationToken);
    }
}

依赖

相关包