diff options
Diffstat (limited to 'doc/architecture/blueprints/gitlab_ci_events')
| -rw-r--r-- | doc/architecture/blueprints/gitlab_ci_events/decisions/001_hierarchical_events.md | 62 | ||||
| -rw-r--r-- | doc/architecture/blueprints/gitlab_ci_events/index.md | 8 |
2 files changed, 68 insertions, 2 deletions
diff --git a/doc/architecture/blueprints/gitlab_ci_events/decisions/001_hierarchical_events.md b/doc/architecture/blueprints/gitlab_ci_events/decisions/001_hierarchical_events.md new file mode 100644 index 00000000000..cec8fa47634 --- /dev/null +++ b/doc/architecture/blueprints/gitlab_ci_events/decisions/001_hierarchical_events.md @@ -0,0 +1,62 @@ +--- +owning-stage: "~devops::verify" +description: 'GitLab CI Events ADR 001: Use hierarchical events' +--- + +# GitLab CI Events ADR 001: Use hierarchical events + +## Context + +We did some brainstorming in [an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/424865) +with multiple use-cases for running CI pipelines based on subscriptions to CI +events. The pattern of using hierarchical events emerged, it is clear that +events may be grouped together by type or by origin. + +For example: + +```yaml +annotate: + on: issue/created + script: ./annotate $[[ event.issue.id ]] + +summarize: + on: issue/closed + script: ./summarize $[[ event.issue.id ]] +``` + +When making this decision we didn't focus on the syntax yet, but the grouping +of events seems to be useful in majority of use-cases. + +We considered making it possible for users to subscribe to multiple events in a +group at once: + +```yaml +audit: + on: events/gitlab/gitlab-org/audit/* + script: ./audit $[[ event.operation.name ]] +``` + +The implication of this is that events within the same groups should share same +fields / schema definition. + +## Decision + +Use hierarchical events: events that can be grouped together and that will +share the same fields following a stable contract. For example: all _issue_ +events will contain `issue.iid` field. + +How we group events has not been decided yet, we can either do that by +labeling or grouping using path-like syntax. + +## Consequences + +The implication is that we will need to build a system with stable interface +describing events' payload and / or schema. + +## Alternatives + +An alternative is not to use hierarchical events, and making it necessary to +subscribe to every event separately, without giving users any guarantess around +common schema for different events. This would be especially problematic for +events that naturally belong to some group and users expect a common schema +for, like audit events. diff --git a/doc/architecture/blueprints/gitlab_ci_events/index.md b/doc/architecture/blueprints/gitlab_ci_events/index.md index 51d65869dfb..afa7f324111 100644 --- a/doc/architecture/blueprints/gitlab_ci_events/index.md +++ b/doc/architecture/blueprints/gitlab_ci_events/index.md @@ -2,9 +2,9 @@ status: proposed creation-date: "2023-03-15" authors: [ "@furkanayhan" ] -owners: [ "@furkanayhan" ] +owners: [ "@fabiopitino" ] coach: "@grzesiek" -approvers: [ "@jreporter", "@cheryl.li" ] +approvers: [ "@fabiopitino", "@jreporter", "@cheryl.li" ] owning-stage: "~devops::verify" participating-stages: [ "~devops::package", "~devops::deploy" ] --- @@ -46,6 +46,10 @@ Events" blueprint is about making it possible to: ## Proposal +### Decisions + +- [001: Use hierarchical events](decisions/001_hierarchical_events.md) + ### Requirements Any accepted proposal should take in consideration the following requirements and characteristics: |