コンテンツにスキップ

2026-03 GitHub Actions ログ artifact 保管・構造化要件

位置づけ

本ドキュメントは、CI/CD 実行時の GitHub Actions ログを GitHub artifact に保管し、あとから解析可能にするための追加合意事項です。

目的は、GitHub UI 上の一時的な job log だけに依存せず、workflow run / job / step / attachment の対応関係を機械可読に残すことです。

適用範囲

初回の適用対象は以下とします。

  • ci-pr-develop.yml
  • ci-pr-main.yml
  • ci-push-develop.yml
  • e2e-full.yml
  • staging-smoke-storefront.yml
  • lighthouse-ci.yml
  • deploy-staging.yml
  • deploy-production.yml

追加合意事項

  1. GitHub Actions の各対象 workflow run について、workflow-level artifact を必須とする。
  2. workflow-level artifact には、少なくとも以下を含める。
  3. manifest.json
  4. ci-run.json
  5. ai-summary.json
  6. ai-summary.md
  7. artifacts.json
  8. failed-step-tails/*.log
  9. jobs/<job-id>/job.json
  10. jobs/<job-id>/steps.json
  11. jobs/<job-id>/github-log.txt
  12. summary.md
  13. ci-run.json を AI 向け triage の第一入力 とし、raw log 全文より優先する。
  14. github-log.txt は 成功・失敗を問わず全 run で保存する。
  15. E2E / smoke / deploy などで job log 以外の補助ログがある場合は、job-local attachment artifact として別 artifact に保存してよい。
  16. retention は 7 日を既定 とし、triage 都合で明示 override が必要な workflow のみ 14 日または 30 日を許容する。
  17. 既存の GitHub masking を前提とし、collector 側では最小限の補助 redaction のみを許容する。
  18. .env、Secrets Manager の dump、credential file、secret bulk input など、機微情報の平文を含みうるファイルは artifact 対象外とする。

構造化ログの識別子

trace_id

  • 各 workflow run に対して trace_id を 1 つ必須とする。
  • trace_id は 32 文字の 16 進文字列とし、以下の入力から決定的に生成する。
  • repository
  • run_id
  • run_attempt
  • 目的は、同一 run に属する manifest / raw log / attachment を相関できるようにすること。

span_id

  • 各 job には span_id 相当の識別子を持たせてよい。
  • span_id は 16 文字の 16 進文字列とし、trace_id と job identity から決定的に生成する。
  • OTel backend 連携は初回スコープ外だが、識別子長は将来の連携を妨げない形式に寄せる。

artifact 命名規則

workflow-level artifact

ci-logs-<run_id>-<run_attempt>-<workflow-slug>

job-local attachment artifact

gha-job-attachments-<workflow-slug>-<job-key>-<suffix>

補足:

  • workflow-slug は YAML ファイル名相当の安定した識別子を用いる。
  • job-key は GitHub Actions の job key、またはそれに準ずる安定識別子を用いる。
  • matrix / shard がある場合は suffix に含める。

manifest.json の必須項目

  • schemaVersion
  • traceId
  • repository
  • workflow.name
  • workflow.slug
  • run.id
  • run.attempt
  • run.eventName
  • run.ref
  • run.sha
  • run.actor
  • run.status
  • run.conclusion
  • run.startedAt
  • run.completedAt
  • retentionDays
  • standardizedTelemetry.ciRunPath
  • standardizedTelemetry.aiSummaryJsonPath
  • standardizedTelemetry.aiSummaryMarkdownPath
  • standardizedTelemetry.failedStepTailDir

workflow_run 起点の workflow では、以下も保持する。

  • run.sourceWorkflowRunId

job.json / steps.json の必須項目

job.json

  • jobId
  • name
  • traceId
  • spanId
  • status
  • conclusion
  • startedAt
  • completedAt
  • durationMs
  • runnerName
  • runnerGroupName
  • labels

steps.json

各 step ごとに以下を保持する。

  • name
  • status
  • duration_ms
  • started_at
  • finished_at
  • error.type
  • error.message_tail
  • log_tail_path

ci-run.json の必須項目

  • schema_version
  • trace_id
  • cicd.pipeline.name
  • cicd.pipeline.run_id
  • cicd.pipeline.run_attempt
  • cicd.job.name
  • repository.full_name
  • repository.ref_name
  • repository.revision
  • run.status
  • steps[].name
  • steps[].status
  • steps[].duration_ms
  • steps[].error.type
  • steps[].error.message_tail

補足:

  • ci-run.json は run 全体の代表 job / 失敗 step を top-level に持ちつつ、jobs[] で全 job の正規化結果を保持してよい。
  • steps[].error.type は少なくとも timeout / dependency_install_error / compile_error / typecheck_error / test_failure / e2e_failure / deploy_error / auth_error / network_error / unknown の enum に寄せる。
  • steps[].error.message_tail は mask 済みかつ 4000 文字以下とする。

AI summary 契約

ai-summary.json / ai-summary.md には少なくとも以下を含める。

  • failed_step
  • error_type
  • suspected_cause
  • reproducibility
  • fix_candidates
  • confidence

AI へ渡す入力順位は次に固定する。

  1. ci-run.json
  2. failed-step-tails/*.log
  3. テストレポートや screenshot / trace
  4. jobs/<job-id>/github-log.txt

attachment manifest の必須項目

job-local attachment artifact には manifest.json を必須とし、以下を含める。

  • schemaVersion
  • traceId
  • workflow.slug
  • run.id
  • run.attempt
  • job.key
  • job.name
  • attachmentKind
  • files[].relativePath
  • files[].sourcePath
  • files[].sizeBytes
  • files[].sha256
  • detectedManifests[]
  • detectedManifests[].kind
  • detectedManifests[].relativePath

detectedManifests[] は attachment bundle 内に含まれる nested manifest を列挙し、少なくとも以下の kind を識別できること。

  • playwright-artifacts
  • sentry-diagnostics
  • workflow-archive

可能な場合は nested manifest 側の traceId / workflowTraceId / app / suite / environment も保持し、attachment manifest だけで次に辿る bundle を判断できるようにする。

受け入れ観点

  1. 任意の対象 workflow run について、artifact を見れば trace_id と run/job/step の対応関係が分かること。
  2. 各 job の raw log が artifact 内に存在すること。
  3. E2E service log や deploy 補助ログがある job では、対応する attachment artifact を辿れること。
  4. workflow_run 起点の workflow では、元の workflow_run.id を manifest から確認できること。
  5. secret 値そのものが artifact に平文で含まれないこと。