Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[RFC] Dedicated API for commit status updates #2639

Draft
wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

[RFC] Dedicated API for commit status updates #2639

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ba204eb
RFC for CommitStatus API kind in the noticfication-controller
somtochiama Apr 13, 2022
bd50aa2
Address multi-cluster issue
somtochiama Apr 15, 2022
99765b1
Correct sentence
somtochiama Apr 16, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 71 additions & 0 deletions rfcs/0008-commitstatus/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@

# RFC-xxxx Create a new API kind for Commit Status

**Status:** provisional

**Creation date:** 2022-05-12

**Last update:** 2022-05-12

## Summary

There should be a dedicated kind in the notification controller for sending commit status notifications to git providers.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would expect the summary to be written as [This RFC] <summary>. So in this particular case, something like:

This RFC proposes to create a dedicated CommitStatus kind in the to allow configuration of commit status notifications to a (Git) Provider.


## Motivation

Currently, The Alert type can reference both git providers and chat providers. However, the differences between the two providers and how notifications being sent to them should be handled has continued to diverge.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. Currently, the ...
  2. git -> Git
  3. I would provide examples of what Git providers and/or chat providers are to provide further context.
  4. The last part of this line is difficult to read ("being sent to them should be handled has continued to diverge").

For example, there is a limit on the length of the name/context of the status for git provider.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reference which proofs this?


When one commit triggers more than one deployment/reconciliation in different clusters, the commit status notification from one overwrites the other as seen in this [issue](https://github.com/fluxcd/notification-controller/issues/195).
A new field specific to the git commit status will allow Flux users to specify a prefix that will be prepended to the context to differentiate the statuses.

By creating a separate kind for git commit status, the specific nuances of the provider can be properly taken into account and it would allow more flexibility in adding fields specific to each kind.
Comment on lines +19 to +22
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would restructure the argumentation here to gradually get to the point of introducing a new kind, because the changes to the current kind or not justified.

Paraphrasing:

We have observed the issue to be <problem>, this would require the introduction of
<something> because of <reason>. Which is ultimately solved by <introducing new kind>,
because of <argumentation>.


### Goals

- Add a new kind `CommitStatus` to Flux notification controller for handling commit status notifications.
- Add support for sending different commit status for different environments/clusters.

### Non-Goals

- Add new `spec` fields to the `Alert` kind.

## Proposal

Introduce a new kind in the notification-controller called `CommitStatus`.
The `CommitStatus` kind will similar to the `Alert` kind, referencing a provider and including event sources to accept events from. The major difference is that it will only reference git providers. Additionally, it can only have a `Kustomization` as its event source since it requires the `revision` field in the event metadata.
It would include a new field `.spec.prefix` that will be used to differentiate results of multiple deployments on different clusters triggered by the same commit and prevent one from overwriting the other.

This proposal will also introduce breaking changes as the `Alert` kind will no longer send notifications to git providers.
Comment on lines +35 to +39
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is very thin and lacks technical details.


### User Stories

If a user want to receive status notification on github for a deployment, a `CommitStatus` kind can be used:

```yaml
apiVersion: notification.toolkit.fluxcd.io/v1beta1
kind: CommitStatus
metadata:
name: webapp
namespace: flux-system
spec:
providerRef:
name: github # The `spec.type` of the provider has to be github, gitlab, or bitbucket
eventSeverity: info
eventSources:
- kind: Kustomization
name: webapp
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should probably have a summary field here similar to Alert. This can be helpful in adding some metadata about the event, which can be helpful, for example when there are multiple clusters. (ref: fluxcd/notification-controller#194)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The name summary doesn't make sense for commit status IMO, it should be prefix or something else.

prefix: dev
```

### Alternatives

Alternatively, we could keep using the `Alert` kind for sending notifications to git providers. While this might not be much of a pain now, it would continue to grow as the implementations details of new features might differ for the chat and git providers.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Instead of

While this might not be much of a pain now, ...

I would phrase it as (something like):

This would not allow for further growth of the Git and chat providers. As the implementation details of new features might differ, making it difficult to invent an API around this which is self explanatory and user friendly.


## Implementation History

- [Implement GitHub commit status notifier](https://github.com/fluxcd/notification-controller/pull/27)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would think none of these entries belong under "implementation history", as they are not related to this RFC but rather to what moved us to creating this RFC. Making it e.g. part of the motivation, which is the section in which you provide historical context to build up your case.

- [Add Gitlab notifier](https://github.com/fluxcd/notification-controller/pull/43)
- [Add bitbucket notifier](https://github.com/fluxcd/notification-controller/pull/73)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Azure DevOps is missing from here.

- [Add Azure DevOps provider](https://github.com/fluxcd/notification-controller/pull/86)