Skip to content

Commit a44ef99

Browse files
openshift-ci[bot]openshift-ci[bot]
authored
Merge pull request #1008 from otaviof/shipwright-trigger-api
Shipwright Triggers API
2 parents db96ab7 + 3f6ef66 commit a44ef99

File tree

12 files changed

+1036
-2
lines changed

12 files changed

+1036
-2
lines changed

‎deploy/crds/shipwright.io_buildruns.yaml‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -466,6 +466,87 @@ spec:
466466
should take to execute.
467467
format: duration
468468
type: string
469+
trigger:
470+
description: Trigger defines the scenarios where a new build should
471+
be triggered.
472+
properties:
473+
secretRef:
474+
description: SecretRef points to a local object carrying the
475+
secret token to validate webhook request.
476+
properties:
477+
name:
478+
description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
479+
TODO: Add other useful fields. apiVersion, kind, uid?'
480+
type: string
481+
type: object
482+
when:
483+
description: When the list of scenarios when a new build should
484+
take place.
485+
items:
486+
description: TriggerWhen a given scenario where the webhook
487+
trigger is applicable.
488+
properties:
489+
github:
490+
description: GitHub describes how to trigger builds
491+
based on GitHub (SCM) events.
492+
properties:
493+
branches:
494+
description: Branches slice of branch names where
495+
the event applies.
496+
items:
497+
type: string
498+
type: array
499+
events:
500+
description: Events GitHub event names.
501+
items:
502+
description: GitHubEventName set of WhenGitHub
503+
valid event names.
504+
type: string
505+
minItems: 1
506+
type: array
507+
type: object
508+
image:
509+
description: Image slice of image names where the event
510+
applies.
511+
properties:
512+
names:
513+
description: Names fully qualified image names.
514+
items:
515+
type: string
516+
type: array
517+
type: object
518+
name:
519+
description: Name name or the short description of the
520+
trigger condition.
521+
type: string
522+
objectRef:
523+
description: ObjectRef describes how to match a foreign
524+
resource, either using the name or the label selector,
525+
plus the current resource status.
526+
properties:
527+
name:
528+
description: Name target object name.
529+
type: string
530+
selector:
531+
additionalProperties:
532+
type: string
533+
description: Selector label selector.
534+
type: object
535+
status:
536+
description: Status object status.
537+
items:
538+
type: string
539+
type: array
540+
type: object
541+
type:
542+
description: Type the event type
543+
type: string
544+
required:
545+
- name
546+
- type
547+
type: object
548+
type: array
549+
type: object
469550
volumes:
470551
description: Volumes contains volume Overrides of the BuildStrategy
471552
volumes in case those are allowed to be overridden. Must only
@@ -4190,6 +4271,87 @@ spec:
41904271
should take to execute.
41914272
format: duration
41924273
type: string
4274+
trigger:
4275+
description: Trigger defines the scenarios where a new build should
4276+
be triggered.
4277+
properties:
4278+
secretRef:
4279+
description: SecretRef points to a local object carrying the
4280+
secret token to validate webhook request.
4281+
properties:
4282+
name:
4283+
description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
4284+
TODO: Add other useful fields. apiVersion, kind, uid?'
4285+
type: string
4286+
type: object
4287+
when:
4288+
description: When the list of scenarios when a new build should
4289+
take place.
4290+
items:
4291+
description: TriggerWhen a given scenario where the webhook
4292+
trigger is applicable.
4293+
properties:
4294+
github:
4295+
description: GitHub describes how to trigger builds
4296+
based on GitHub (SCM) events.
4297+
properties:
4298+
branches:
4299+
description: Branches slice of branch names where
4300+
the event applies.
4301+
items:
4302+
type: string
4303+
type: array
4304+
events:
4305+
description: Events GitHub event names.
4306+
items:
4307+
description: GitHubEventName set of WhenGitHub
4308+
valid event names.
4309+
type: string
4310+
minItems: 1
4311+
type: array
4312+
type: object
4313+
image:
4314+
description: Image slice of image names where the event
4315+
applies.
4316+
properties:
4317+
names:
4318+
description: Names fully qualified image names.
4319+
items:
4320+
type: string
4321+
type: array
4322+
type: object
4323+
name:
4324+
description: Name name or the short description of the
4325+
trigger condition.
4326+
type: string
4327+
objectRef:
4328+
description: ObjectRef describes how to match a foreign
4329+
resource, either using the name or the label selector,
4330+
plus the current resource status.
4331+
properties:
4332+
name:
4333+
description: Name target object name.
4334+
type: string
4335+
selector:
4336+
additionalProperties:
4337+
type: string
4338+
description: Selector label selector.
4339+
type: object
4340+
status:
4341+
description: Status object status.
4342+
items:
4343+
type: string
4344+
type: array
4345+
type: object
4346+
type:
4347+
description: Type the event type
4348+
type: string
4349+
required:
4350+
- name
4351+
- type
4352+
type: object
4353+
type: array
4354+
type: object
41934355
volumes:
41944356
description: Volumes contains volume Overrides of the BuildStrategy
41954357
volumes in case those are allowed to be overridden. Must only

‎deploy/crds/shipwright.io_builds.yaml‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -444,6 +444,87 @@ spec:
444444
should take to execute.
445445
format: duration
446446
type: string
447+
trigger:
448+
description: Trigger defines the scenarios where a new build should
449+
be triggered.
450+
properties:
451+
secretRef:
452+
description: SecretRef points to a local object carrying the secret
453+
token to validate webhook request.
454+
properties:
455+
name:
456+
description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
457+
TODO: Add other useful fields. apiVersion, kind, uid?'
458+
type: string
459+
type: object
460+
when:
461+
description: When the list of scenarios when a new build should
462+
take place.
463+
items:
464+
description: TriggerWhen a given scenario where the webhook
465+
trigger is applicable.
466+
properties:
467+
github:
468+
description: GitHub describes how to trigger builds based
469+
on GitHub (SCM) events.
470+
properties:
471+
branches:
472+
description: Branches slice of branch names where the
473+
event applies.
474+
items:
475+
type: string
476+
type: array
477+
events:
478+
description: Events GitHub event names.
479+
items:
480+
description: GitHubEventName set of WhenGitHub valid
481+
event names.
482+
type: string
483+
minItems: 1
484+
type: array
485+
type: object
486+
image:
487+
description: Image slice of image names where the event
488+
applies.
489+
properties:
490+
names:
491+
description: Names fully qualified image names.
492+
items:
493+
type: string
494+
type: array
495+
type: object
496+
name:
497+
description: Name name or the short description of the trigger
498+
condition.
499+
type: string
500+
objectRef:
501+
description: ObjectRef describes how to match a foreign
502+
resource, either using the name or the label selector,
503+
plus the current resource status.
504+
properties:
505+
name:
506+
description: Name target object name.
507+
type: string
508+
selector:
509+
additionalProperties:
510+
type: string
511+
description: Selector label selector.
512+
type: object
513+
status:
514+
description: Status object status.
515+
items:
516+
type: string
517+
type: array
518+
type: object
519+
type:
520+
description: Type the event type
521+
type: string
522+
required:
523+
- name
524+
- type
525+
type: object
526+
type: array
527+
type: object
447528
volumes:
448529
description: Volumes contains volume Overrides of the BuildStrategy
449530
volumes in case those are allowed to be overridden. Must only contain

‎docs/build.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ SPDX-License-Identifier: Apache-2.0
1717
- [Defining the Output](#defining-the-output)
1818
- [Defining Retention Parameters](#defining-retention-parameters)
1919
- [Defining Volumes](#defining-volumes)
20+
- [Defining Triggers](#defining-triggers)
2021
- [BuildRun deletion](#BuildRun-deletion)
2122

2223
## Overview
@@ -602,6 +603,109 @@ spec:
602603
name: test-config
603604
```
604605

606+
### Defining Triggers
607+
608+
Using the triggers, you can submit `BuildRun` instances when certain events happen. The idea is to be able to trigger Shipwright builds in an event driven fashion, for that purpose you can watch certain types of events.
609+
610+
**Note**: triggers rely on the [Shipwright Triggers](https://github.com/shipwright-io/triggers) project to be deployed and configured in the same Kubernetes cluster where you run Shipwright Build. If it is not set up, the triggers defined in a Build are ignored.
611+
612+
The types of events under watch are defined on the `.spec.trigger` attribute, please consider the following example:
613+
614+
```yaml
615+
apiVersion: shipwright.io/v1alpha1
616+
kind: Build
617+
spec:
618+
source:
619+
url: https://github.com/shipwright-io/sample-go
620+
contextDir: docker-build
621+
credentials:
622+
name: webhook-secret
623+
trigger:
624+
when: []
625+
```
626+
627+
Certain types of events will use attributes defined on `.spec.source` to complete the information needed in order to dispatch events.
628+
629+
#### GitHub
630+
631+
The GitHub type is meant to react upon events coming from GitHub WebHook interface, the events are compared against the existing `Build` resources, and therefore it can identify the `Build` objects based on `.spec.source.url` combined with the attributes on `.spec.trigger.when[].github`.
632+
633+
To identify a given `Build` object, the first criteria is the repository URL, and then the branch name listed on the GitHub event payload must also match. Following the criteria:
634+
635+
- First, the branch name is checked against the `.spec.trigger.when[].github.branches` entries
636+
- If the `.spec.trigger.when[].github.branches` is empty, the branch name is compared against `.spec.source.revision`
637+
- If `spec.source.revision` is empty, the default revision name is used ("main")
638+
639+
The following snippet shows a configuration machting `Push` and `PullRequest` events on the `main` branch, for example:
640+
641+
```yaml
642+
# [...]
643+
spec:
644+
source:
645+
url: https://github.com/shipwright-io/sample-go
646+
trigger:
647+
when:
648+
- name: push and pull-request on the main branch
649+
type: GitHub
650+
github:
651+
events:
652+
- Push
653+
- PullRequest
654+
branches:
655+
- main
656+
```
657+
658+
#### Image
659+
660+
In order to watch over images, in combination with the [Image](https://github.com/shipwright-io/image) controller, you can trigger new builds when those container image names change.
661+
662+
For instance, lets imagine the image named `ghcr.io/some/base-image` is used as input for the Build process and every time it changes we would like to trigger a new build. Please consider the following snippet:
663+
664+
```yaml
665+
# [...]
666+
spec:
667+
trigger:
668+
when:
669+
- name: watching for the base-image changes
670+
type: Image
671+
image:
672+
names:
673+
- ghcr.io/some/base-image:latest
674+
```
675+
676+
#### Tekton Pipeline
677+
678+
Shipwright can also be used in combination with [Tekton Pipeline](https://github.com/tektoncd/pipeline), you can configure the Build to watch for `Pipeline` resources in Kubernetes reacting when the object reaches the desired status (`.objectRef.status`), and is identified either by its name (`.objectRef.name`) or a label selector (`.objectRef.selector`). The example below uses the label selector approach:
679+
680+
```yaml
681+
# [...]
682+
spec:
683+
trigger:
684+
when:
685+
- name: watching over for the Tekton Pipeline
686+
type: Pipeline
687+
objectRef:
688+
status:
689+
- Succeeded
690+
selector:
691+
label: value
692+
```
693+
694+
While the next snippet uses the object name for identification:
695+
696+
```yaml
697+
# [...]
698+
spec:
699+
trigger:
700+
when:
701+
- name: watching over for the Tekton Pipeline
702+
type: Pipeline
703+
objectRef:
704+
status:
705+
- Succeeded
706+
name: tekton-pipeline-name
707+
```
708+
605709
### Sources
606710

607711
Sources represent remote artifacts, as in external entities added to the build context before the actual Build starts. Therefore, you may employ `.spec.sources` to download artifacts from external repositories.

0 commit comments

Comments
 (0)