spendeskplatform/github-actions-exporter

github-actions-exporter

镜像概述和主要用途

github-actions-exporter是一个用于Prometheus的指标导出器，专门用于收集和导出GitHub Actions相关指标。它能够监控GitHub Actions工作流的运行状态、持续时间、自托管运行器状态以及工作流使用时长等关键信息，帮助用户通过Prometheus实现对CI/CD流程的可视化监控和告警。

容器镜像地址：https://hub.docker.com/repository/docker/spendeskplatform/github-actions-exporter

核心功能和特性

• 多指标支持：导出工作流运行状态、持续时间、自托管运行器状态、工作流使用时长等多种指标
• 灵活认证：支持GitHub令牌（Personal Access Token）或GitHub应用（GitHub App）两种认证方式
• 可配置监控范围：可指定监控的组织和仓库，默认监控组织下所有仓库
• 自定义导出字段：支持配置需要导出的工作流指标字段
• GitHub Enterprise支持：适配GitHub Enterprise环境，可配置API URL和企业名称
• 可调整刷新频率：自定义GitHub Actions状态的刷新时间间隔

使用场景和适用范围

• 需要监控GitHub Actions工作流运行状态的开发团队
• 需跟踪自托管运行器在线状态和负载情况的组织
• 使用Prometheus进行监控的CI/CD环境
• 管理私有仓库GitHub-hosted runners使用时长的场景
• GitHub Enterprise环境下的CI/CD流程监控

详细使用方法和配置说明

认证方式

支持两种认证方式（仅可配置一种）：

1. GitHub令牌认证：使用Personal Access Token
2. GitHub应用认证：需配置App ID、Installation ID和Private Key

注意事项

• 监控公共仓库时，GitHub令牌需包含public_repo权限
• GitHub应用认证在GitHub Enterprise环境中暂不支持

配置选项

Docker部署示例

使用GitHub令牌认证

bash
docker run -d \
  -p 9999:9999 \
  -e GITHUB_TOKEN="your_github_token" \
  -e GITHUB_ORGAS="your_organization" \
  -e GITHUB_REFRESH=60 \
  --name github-actions-exporter \
  spendeskplatform/github-actions-exporter

使用GitHub应用认证

bash
docker run -d \
  -p 9999:9999 \
  -e GITHUB_APP_ID="your_app_id" \
  -e GITHUB_APP_INSTALLATION_ID="your_installation_id" \
  -e GITHUB_APP_PRIVATE_KEY="your_private_key" \
  -e GITHUB_ORGAS="your_organization" \
  --name github-actions-exporter \
  spendeskplatform/github-actions-exporter

docker-compose配置示例

yaml
version: '3'
services:
  github-actions-exporter:
    image: spendeskplatform/github-actions-exporter
    ports:
      - "9999:9999"
    environment:
      - GITHUB_TOKEN=your_github_token
      - GITHUB_ORGAS=your_organization
      - GITHUB_REPOS=your_organization/repo1,your_organization/repo2
      - GITHUB_REFRESH=30
      - PORT=9999
    restart: always

导出指标详情

github_workflow_run_status

• 类型：Gauge
• 描述：工作流运行状态

状态值说明

标签字段

github_workflow_run_duration_ms

• 类型：Gauge
• 描述：工作流运行持续时间（毫秒）

标签字段：与github_workflow_run_status相同

github_job

⚠️ 此指标是github_workflow_run_status的重复项，即将弃用，不建议使用。

github_runner_status

• 类型：Gauge
• 描述：仓库级自托管运行器状态

状态值说明

标签字段

github_runner_organization_status

• 类型：Gauge
• 描述：组织级自托管运行器状态

状态值说明：与github_runner_status相同

标签字段

github_runner_enterprise_status

• 类型：Gauge
• 描述：企业级自托管运行器状态

状态值说明：与github_runner_status相同

标签字段

github_workflow_usage_seconds

• 类型：Gauge
• 描述：私有仓库中GitHub-hosted runners的工作流计费时长（秒）

标签字段

示例：

# HELP github_workflow_usage Number of billable seconds used by a specific workflow during the current billing cycle. Any job re-runs are also included in the usage. Only apply to workflows in private repositories that use GitHub-hosted runners.
# TYPE github_workflow_usage gauge
github_workflow_usage_seconds{id="2862037",name="Create Release",node_id="MDg6V29ya2Zsb3cyODYyMDM3",repo="xxx/xxx",state="active",os="UBUNTU"} 706.609

认证配置详细说明

GitHub令牌权限配置

GitHub令牌需包含以下权限：

repo
  - repo:status
  - repo_deployment
  - public_repo

admin:org
  - write:org
  - read:org

GitHub应用认证配置

创建GitHub应用

• 个人账号：访问https://github.com/settings/apps/new?url=http://github.com/github-actions-exporter/github-actions-exporter&webhook_active=false&public=false&administration=write&actions=read%EF%BC%8C%E8%BE%93%E5%85%A5%E5%BA%94%E7%94%A8%E5%90%8D%E7%A7%B0%E5%90%8E%E7%82%B9%E5%87%BB%22Create GitHub App"
• 组织账号：将URL中的:org替换为组织名称，访问https://github.com/organizations/:org/settings/apps/new?url=http://github.com/github-actions-exporter/github-actions-exporter&webhook_active=false&public=false&administration=write&organization_self_hosted_runners=write&actions=read%EF%BC%8C%E8%BE%93%E5%85%A5%E5%BA%94%E7%94%A8%E5%90%8D%E7%A7%B0%E5%90%8E%E7%82%B9%E5%87%BB%22Create GitHub App"

认证错误处理

无效GitHub令牌

• GitHub API返回401 Bad credentials，并显示错误消息

无效GitHub应用配置

• App ID或Installation ID错误：显示类似could not refresh installation id 12345678's token: request &{Method:POST URL:https://api.github.com/app/installations/12345678/access_tokens的错误
• 私钥错误：显示类似Error: Client creation failed.authentication failed: could not parse private key: Invalid Key: Key must be PEM encoded PKCS1 or PKCS8 private key的错误

Kubernetes Secret配置示例

yaml
kind: Secret
apiVersion: v1
metadata:
  name: actions-exporter
  namespace: github-actions-exporter
type: Opaque
data:
  github_token: AAAAAA  #  base64编码的GitHub令牌
  # github_app_id: BBBBBB  #  base64编码的GitHub应用ID（二选一）
  # github_app_installation_id: CCCCCCCCC  #  base64编码的GitHub应用安装ID（二选一）
  # github_app_private_key: DDDDDDD  #  base64编码的GitHub应用私钥（二选一）

使用外部密钥管理器示例（EKS Secret Manager）

yaml
apiVersion: 'kubernetes-client.io/v1'
kind: ExternalSecret
metadata:
  name: actions-exporter
  namespace: github-actions-exporter
spec:
  backendType: secretsManager
  data:
    # - key: MySecretManagerKey
    #   name: github_token
    #   property: github_token
    - key: MySecretManagerKey
      name: github_app_id
      property: github_app_id
    - key: MySecretManagerKey
      name: github_app_installation_id
      property: github_app_installation_id
    - key: MySecretManagerKeyPrivateKey
      name: github_app_private_key