Commit status: opt-in event message as description (spec.commitStatusDescriptionExpr)

オープン
#1,436 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

@schdief がすでに取り組んでいます。

2026年11月16日 から。

  • #1437 @schdief による — オープン

評価

難易度
5/5
見積もり時間
1週間以上
初心者へのやさしさ
38/100
issue の種類
機能追加
明瞭さ
明確に書かれている
活発さ
活発
技術スタック
github, go

調査の方向性

Start with api/v1/provider_types.go and internal/server/provider_commit_status.go to trace how commitStatusExpr is declared and evaluated. Then follow event_handlers.go into internal/notifier/factory.go and the six commit status notifiers; the issue lists the proposed tests and docs/spec/v1/providers.md. Done means the optional expression is validated, unset or empty values preserve current descriptions, and custom descriptions are normalized and safely truncated to each provider's limit.

索引モデルが issue の本文から書いたものです。

説明

Problem

Git commit status providers (github, gitlab, gitea, bitbucket, bitbucketserver,
azuredevops) write only the event reason as the status description. For a failed
Kustomization the commit shows:

kustomization/apps — health check failed

while the event that triggered it carries the actual explanation:

health check failed after 5m0s: timeout waiting for: [HelmRelease/apps/podinfo status: 'InProgress': Helm upgrade failed for release apps/podinfo with chart [email protected]: context deadline exceeded]

(The kstatus part after 'InProgress' is proposed in fluxcd/pkg#1379; today the message ends
after the status.)

The description is built from the reason only
(util.go#L50-L56,
used by github.go#L75
and the other five commit status notifiers).

The commit status is often the only Flux output that application developers see. Pipelines
that wait for the commit status after a GitOps change and developers looking at the commit
both learn that the deployment failed, not why. Finding out needs cluster access, a UI or
a second notification channel, which many platform setups don't give to application teams.

spec.commitStatusExpr made the status context configurable. The description still
can't be changed.

Proposal

Add an optional CEL field to Provider (v1), next to commitStatusExpr:

apiVersion: notification.toolkit.fluxcd.io/v1
kind: Provider
metadata:
  name: github
  namespace: flux-system
spec:
  type: github
  address: https://github.com/org/repo
  secretRef:
    name: github-token
  commitStatusDescriptionExpr: "event.message"

Semantics:

  1. Same environment as commitStatusExpr: variables event, alert and provider; the result
    must be a string
    (provider_commit_status.go#L34-L40).
  2. The result is collapsed to one line (whitespace runs become a single space) and shortened
    in the middle
    to the provider's description limit, e.g. 140 characters for GitHub (longer
    descriptions are rejected with HTTP 422). Flux messages put the generic part first and the
    concrete cause last, so keeping both ends keeps both: the 198-character message above
    becomes
    health check failed after 5m0s: timeout waiting for: [HelmRelease/app…ease apps/podinfo with chart [email protected]: context deadline exceeded]
    
    Truncation is rune-safe. Per-provider limits are constants next to each notifier; GitHub is
    140. The limits of the other providers would be confirmed in the PR.
  3. An empty result falls back to today's reason-based description, so expressions such as
    event.severity == 'error' ? event.message : '' change only failures.
  4. If the field is unset, behaviour is unchanged.
  5. Validation: the same XValidation rule as commitStatusExpr (commit status provider types
    only,
    provider_types.go#L66).
    Open question: should an evaluation error drop the event, as commitStatusExpr does
    today
    (event_handlers.go#L462-L466),
    or fall back to the default description and log? We would prefer the fallback, because a
    status with the plain reason is better than no status at all.

Examples:

Expression Description on failure
event.message the full message, shortened in the middle
event.reason + ': ' + event.message reason first, then the message
event.severity == 'error' ? event.message : '' message on failure, today's text on success
Effect on deduplication and API usage

duplicateGithubStatus skips a write when the latest status with the same context has the
same state and description
(github.go#L111-L133).
Messages vary more than reasons (for example durations such as after 5m0s), so repeated
failures write a new status more often. That's still at most one write per forwarded event,
the same as a provider without deduplication, and the feature is opt-in. Conditional
requests (#977) are complementary.

Implementation sketch
File Change
api/v1/provider_types.go CommitStatusDescriptionExpr string \json:"commitStatusDescriptionExpr,omitempty"`; extend the XValidationrule; regenerate CRDs and API docs. v1 only, likechangeRequestComment`, since v1beta3 is deprecated
internal/server/provider_commit_status.go factor the CEL evaluation of newCommitStatus into a shared helper; add newCommitStatusDescription
internal/server/event_handlers.go evaluate the description next to createCommitStatus (L457); pass it in prepareNotifier (L534-L535)
internal/notifier/factory.go CommitStatusDescription field and WithCommitStatusDescription option, next to WithCommitStatus (L165-L170); hand it to the six commit status notifiers
internal/notifier/util.go commitStatusDescription(event, custom string, limit int): default to formatNameAndDescription, else normalize and truncateMiddle
github.go, gitlab.go, gitea.go, bitbucket.go, bitbucketserver.go, azure_devops.go use the helper instead of formatNameAndDescription
tests truncateMiddle (ASCII, multi-byte, limit edges); per-notifier description and dedup; CEL cases in event_handlers_test.go like the existing commitStatusExpr table (L1197ff); API validation in provider_controller_test.go
docs/spec/v1/providers.md new section after "Custom Commit Status Messages" (L2373ff)
Alternatives considered
  • Always send the message. That's a breaking change for existing statuses and
    deduplication, so we don't propose it.
  • A plain switch (commitStatusDescription: Reason|Message). It's simpler but less
    flexible; we'd be fine with it if maintainers prefer.
  • PR comment providers (githubpullrequestcomment and similar). They need change request
    metadata on the event and cover preview environments, not commits on a deployed branch.
Context

We run Flux for many application teams who don't have cluster access. Today we work around
this with a small in-cluster component that writes the message into extra commit statuses.
We would like to drop it in favour of upstream support. I'll open a PR for this.

Related: #589 (extra information in the GitHub status; a maintainer was open to it), #977
(rate limiting), #1387 (per-context duplicate check, closed unmerged), #1434 (GitHub duplicate
check per context; touches the same notifier, independent of this proposal).

主要言語
Go
スター
182
フォーク
183
平均マージ
9時間 20分
マージ済み PR(30日)
26

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

fluxcd/notification-controller のほかの issue

fluxcd/notification-controller の issue をすべて見る

似ている issue

Go の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。