id: dag-release-gate-child-failure-policy-and-inherited-labels
namespace: company.team
description: |
Release readiness gate built as a `Dag`. Independent checks (git tag on GitHub, container tag on Docker Hub,
a smoke test subflow against staging) run in parallel, dependent steps wait for exactly the children they need,
`onChildFailure: CANCEL` stops the rest of the graph as soon as one check fails, and the release id travels as a
label into every child execution (`inheritLabels`), so one filter on the Executions page shows the whole release.
labels:
team: release
purpose: release-gate
inputs:
- id: release_id
type: STRING
defaults: 2026.10-rc1
description: |
Identifier of the release train. It becomes the `release_id` label of this execution and, through
`inheritLabels`, of every child execution, and it is the KV key suffix of the release record.
Lowercase letters, digits, `.`, `_` and `-`, up to 63 characters (the label and KV key rules).
- id: version
type: STRING
defaults: v2.0.5
description: Git tag of the GitHub release and tag of the container image, for
example `v2.0.5` or `2.0.5-rc1`.
- id: github_repo
type: STRING
defaults: kestra-io/kestra
description: GitHub repository `owner/name` that publishes the release. Read
through the public REST API (60 requests per hour unauthenticated).
- id: container_image
type: STRING
defaults: kestra/kestra
description: Docker Hub repository `namespace/name` that must carry the
`version` tag. Official images use the `library` namespace, for example
`library/nginx`.
- id: staging_url
type: STRING
defaults: https://httpbin.org/delay/2
description: Health endpoint of the staging deployment the smoke-check subflow
calls. The default stands in for a service that takes a moment to answer.
- id: record_ttl
type: DURATION
defaults: P90D
description: How long the release record and the failure record stay in the KV store.
- id: kestra_api_url
type: STRING
defaults: http://localhost:8080
description: Base URL of this Kestra instance. Used by the child-execution
cleanup in the Dag `errors` branch and for links in alerts when
`kestra.url` is not configured.
variables:
tenant: main
smoke_flow_id: release-smoke-check
active_states: '["CREATED", "RUNNING", "PAUSED", "QUEUED", "RETRYING"]'
checks:
- when: "{{ [inputs.release_id] | jq('.[0] |
test(\"^[a-z0-9][a-z0-9._-]{0,62}$\")') | first }}"
message: release_id must be a label-safe identifier (lowercase letters, digits,
`.`, `_`, `-`, 63 characters at most), for example `2026.10-rc1`.
style: ERROR
behavior: BLOCK_EXECUTION
- when: "{{ [inputs.version] | jq('.[0] |
test(\"^v?[0-9]+[.][0-9]+[.][0-9]+([.-][0-9A-Za-z.-]+)?$\")') | first }}"
message: version must look like a release tag, `v2.0.5`, `2.0.5` or `2.0.5-rc1`.
A branch name or `latest` cannot be gated.
style: ERROR
behavior: BLOCK_EXECUTION
- when: "{{ [inputs.github_repo] | jq('.[0] |
test(\"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$\")') | first }}"
message: github_repo must be `owner/name`, for example `kestra-io/kestra`.
style: ERROR
behavior: BLOCK_EXECUTION
- when: "{{ [inputs.container_image] | jq('.[0] |
test(\"^[a-z0-9_.-]+/[a-z0-9_.-]+$\")') | first }}"
message: container_image must be a Docker Hub repository `namespace/name`, for
example `kestra/kestra` or `library/nginx`.
style: ERROR
behavior: BLOCK_EXECUTION
- when: "{{ inputs.staging_url | startsWith('https://') or inputs.staging_url |
startsWith('http://') }}"
message: staging_url must be an absolute http(s) URL.
style: ERROR
behavior: BLOCK_EXECUTION
concurrency:
limit: 1
behavior: QUEUE
sla:
- id: gate_window
type: MAX_DURATION
duration: PT10M
behavior: FAIL
labels:
release_sla: breached
triggers:
- id: release_webhook
type: io.kestra.plugin.core.trigger.Webhook
key: "{{ secret('RELEASE_GATE_WEBHOOK_KEY') }}"
description: |
For the CI job that cuts the release: POST {"release_id": "2026.10-rc1", "version": "v2.0.5"} to
/api/v1/main/executions/webhook/company.team/dag-release-gate-child-failure-policy-and-inherited-labels/<key>.
Webhook executions skip flow-level `checks` on 2.0.5, which is why `validate_inputs` repeats them.
inputs:
release_id: "{{ trigger.body.release_id }}"
version: "{{ trigger.body.version }}"
tasks:
- id: validate_inputs
type: io.kestra.plugin.core.execution.Fail
description: The `checks` rules once more, for executions that bypass them
(Webhook trigger, Subflow calls). Fails before anything is labelled or
called.
condition: >-
{{ not ([inputs.release_id] | jq('.[0] |
test("^[a-z0-9][a-z0-9._-]{0,62}$")') | first)
or not ([inputs.version] | jq('.[0] | test("^v?[0-9]+[.][0-9]+[.][0-9]+([.-][0-9A-Za-z.-]+)?$")') | first)
or not ([inputs.github_repo] | jq('.[0] | test("^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$")') | first)
or not ([inputs.container_image] | jq('.[0] | test("^[a-z0-9_.-]+/[a-z0-9_.-]+$")') | first)
or not (inputs.staging_url | startsWith('https://') or inputs.staging_url | startsWith('http://')) }}
errorMessage: "Invalid inputs: release_id={{ inputs.release_id }} version={{
inputs.version }} github_repo={{ inputs.github_repo }} container_image={{
inputs.container_image }} staging_url={{ inputs.staging_url }}. See the
input descriptions for the accepted shapes."
- id: label_release
type: io.kestra.plugin.core.execution.Labels
description: |
Set before the Dag on purpose. `inheritLabels: true` on a Subflow copies the labels the parent carries at the
moment the child starts, so the release id is on every child execution and the Executions page can be
filtered with `release_id = <id>` to show the gate and its children together.
labels:
release_id: "{{ inputs.release_id }}"
release_version: "{{ inputs.version }}"
release_status: running
- id: release_graph
type: io.kestra.plugin.core.flow.Dag
description: |
The gate. Children without `dependsOn` start together; a child with `dependsOn` starts when all the listed
children ended SUCCESS. `onChildFailure: CANCEL` interrupts every still-running child the moment one fails and
marks it CANCELLED; the Dag then resolves FAILED and its `errors` tasks run. Keep the policy a literal: on
2.0.5 the value is rendered once per flow revision and reused, so an input would only apply to the first run.
onChildFailure: CANCEL
concurrent: 0
tasks:
- task:
id: release_tag
type: io.kestra.plugin.core.http.Request
description: The release must exist on GitHub under exactly this tag. A 404
fails the child, which fails the gate.
uri: "https://api.github.com/repos/{{ inputs.github_repo }}/releases/tags/{{
inputs.version }}"
headers:
Accept: application/vnd.github+json
options:
timeout:
connectTimeout: PT5S
readIdleTimeout: PT20S
retry:
type: constant
interval: PT5S
maxAttempts: 3
retryOnStatusCodes: [ 429, 502, 503, 504 ]
- task:
id: container_tag
type: io.kestra.plugin.core.http.Request
description: The image tag must exist on Docker Hub. Same shape of failure as
the git tag, in parallel with it.
uri: "https://hub.docker.com/v2/repositories/{{ inputs.container_image
}}/tags/{{ inputs.version }}"
options:
timeout:
connectTimeout: PT5S
readIdleTimeout: PT20S
retry:
type: constant
interval: PT5S
maxAttempts: 3
retryOnStatusCodes: [ 429, 502, 503, 504 ]
- task:
id: staging_smoke
type: io.kestra.plugin.core.flow.Subflow
description: |
A child execution of `release-smoke-check` (flow given in the blueprint description). `inheritLabels`
carries `release_id`, `release_version` and the flow labels down; `labels` adds `environment: staging`.
`wait: true` and `transmitFailed: true` make its failure the failure of this child. The Dag does not
interrupt a Subflow child on CANCEL; the `errors` branch below kills what is still running.
namespace: company.team
flowId: "{{ vars.smoke_flow_id }}"
inheritLabels: true
labels:
environment: staging
inputs:
release_id: "{{ inputs.release_id }}"
environment: staging
url: "{{ inputs.staging_url }}"
expected_status: 200
wait: true
transmitFailed: true
- task:
id: tag_labels
type: io.kestra.plugin.core.execution.Labels
description: Depends on `release_tag` only, so it runs as soon as GitHub
answered, while the other checks may still be running.
labels:
release_channel: "{{ fromJson(outputs.release_tag.body).prerelease ?
'prerelease' : 'stable' }}"
dependsOn: [ release_tag ]
- task:
id: compose_record
type: io.kestra.plugin.core.output.OutputValues
description: Needs all three checks, so it waits for the slowest. Reads the
Subflow outputs through `outputs.staging_smoke.outputs`.
values:
record: |-
{{ {
'release_id': inputs.release_id,
'version': inputs.version,
'github_repo': inputs.github_repo,
'release_name': fromJson(outputs.release_tag.body).name,
'release_url': fromJson(outputs.release_tag.body).html_url,
'published_at': fromJson(outputs.release_tag.body).published_at,
'prerelease': fromJson(outputs.release_tag.body).prerelease,
'container_image': inputs.container_image,
'image_pushed_at': fromJson(outputs.container_tag.body).last_updated,
'image_architectures': fromJson(outputs.container_tag.body).images | length,
'staging_status': outputs.staging_smoke.outputs.status_code,
'staging_execution': outputs.staging_smoke.executionId,
'gate_execution': execution.id,
'gated_at': execution.startDate
} | toJson }}
dependsOn: [ release_tag, container_tag, staging_smoke ]
- task:
id: record_release
type: io.kestra.plugin.core.kv.Set
description: One KV entry per release, the artefact other flows (deploy,
announce) read instead of calling GitHub and Docker Hub again.
key: "release_{{ inputs.release_id }}"
kvType: JSON
value: "{{ outputs.compose_record.values.record }}"
ttl: "{{ inputs.record_ttl }}"
kvDescription: "Release {{ inputs.release_id }} ({{ inputs.version }}) passed
the gate in execution {{ execution.id }}"
dependsOn: [ compose_record ]
errors:
- id: still_running_children
type: io.kestra.plugin.kestra.executions.Query
description: |
Runs the moment the Dag fails, while a Subflow child may still be running: `onChildFailure` cancels worker
tasks but does not reach into child executions. `triggerExecutionId` lists the executions this run started.
kestraUrl: "{{ inputs.kestra_api_url }}"
auth:
username: "{{ secret('KESTRA_API_USERNAME') }}"
password: "{{ secret('KESTRA_API_PASSWORD') }}"
triggerExecutionId: "{{ execution.id }}"
fetchType: FETCH
- id: kill_orphaned_children
type: io.kestra.plugin.core.flow.Loop
description: |
`rows` is a list of pages of execution objects, hence `flatten`; a `states` filter with more than one state
returns nothing on 2.0.5, so the state is filtered here. `propagateKill` reaches grandchildren.
values: >-
{{ fromJson(outputs.still_running_children.rows | toJson)
| jq('flatten | map(select(.state.current as $s | ' ~ vars.active_states ~ ' | index($s))) | map(.id)')
| first | toJson }}
transmitFailed: false
tasks:
- id: kill_child
type: io.kestra.plugin.kestra.executions.Kill
kestraUrl: "{{ inputs.kestra_api_url }}"
auth:
username: "{{ secret('KESTRA_API_USERNAME') }}"
password: "{{ secret('KESTRA_API_PASSWORD') }}"
executionId: "{{ item.value }}"
propagateKill: true
- id: log_cleanup
type: io.kestra.plugin.core.log.Log
level: WARN
message: >-
Release graph failed; {{
(outputs.kill_orphaned_children.iterationCount ?? 0) }} still-running
child execution(s) of release {{ inputs.release_id }} were killed.
- id: label_ready
type: io.kestra.plugin.core.execution.Labels
description: Reached only when every child of the Dag ended SUCCESS.
labels:
release_status: ready
- id: log_ready
type: io.kestra.plugin.core.log.Log
message: |
Release {{ inputs.release_id }} ({{ inputs.version }}) is ready: GitHub release "{{ fromJson(outputs.release_tag.body).name }}"
published {{ fromJson(outputs.release_tag.body).published_at }}, image {{ inputs.container_image }}:{{ inputs.version }}
for {{ fromJson(outputs.container_tag.body).images | length }} architecture(s), staging answered
{{ outputs.staging_smoke.outputs.status_code }} (execution {{ outputs.staging_smoke.executionId }}).
Record: KV key release_{{ inputs.release_id }}.
errors:
- id: failure
type: io.kestra.plugin.core.output.OutputValues
description: Read `errorLogs()` once, before this branch logs anything of its own.
values:
task: "{{ (errorLogs() | length) > 0 ? (errorLogs()[0].taskId ?? 'unknown') :
'none' }}"
message: "{{ (errorLogs() | length) > 0 ? errorLogs()[0].message : 'no task
error logged (SLA breach or kill)' }}"
smoke_execution: "{{ (outputs.staging_smoke.state ?? '') == 'FAILED' ?
outputs.staging_smoke.executionId : '' }}"
- id: label_failed
type: io.kestra.plugin.core.execution.Labels
labels:
release_status: failed
release_failed_task: "{{ outputs.failure.values.task }}"
- id: record_failure
type: io.kestra.plugin.core.kv.Set
description: Dead-letter per release, next to the record a successful gate would
have written. Same TTL. An invalid release id cannot be a KV key, so that
case lands under `release_invalid-input_failed`.
key: "release_{{ outputs.failure.values.task == 'validate_inputs' ?
'invalid-input' : inputs.release_id }}_failed"
kvType: JSON
ttl: "{{ inputs.record_ttl }}"
value: |-
{{ {
'release_id': inputs.release_id,
'version': inputs.version,
'failed_task': outputs.failure.values.task,
'message': outputs.failure.values.message,
'smoke_execution': outputs.failure.values.smoke_execution,
'killed_children': outputs.kill_orphaned_children.iterationCount ?? 0,
'gate_execution': execution.id,
'failed_at': execution.startDate
} | toJson }}
- id: log_failure
type: io.kestra.plugin.core.log.Log
level: ERROR
message: >-
Release {{ inputs.release_id }} ({{ inputs.version }}) failed the gate in
task {{ outputs.failure.values.task }}: {{ outputs.failure.values.message
}} {%- if outputs.failure.values.smoke_execution != '' %} The status code
and reason are in the smoke-check execution {{
outputs.failure.values.smoke_execution }}.{% endif %} {{ kestra.url ??
inputs.kestra_api_url }}/ui/{{ vars.tenant }}/executions/{{ flow.namespace
}}/{{ flow.id }}/{{ execution.id }}
- id: alert_failure
type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
description: allowFailure so a missing `SLACK_WEBHOOK_URL` does not hide the
original error; the same text is in the ERROR log above.
allowFailure: true
url: "{{ secret('SLACK_WEBHOOK_URL') }}"
messageText: >-
:rotating_light: Release `{{ inputs.release_id }}` ({{ inputs.version }})
failed the gate in `{{ outputs.failure.values.task }}`: {{
outputs.failure.values.message }} All executions of this release: {{
kestra.url ?? inputs.kestra_api_url }}/ui/{{ vars.tenant
}}/executions?filters[labels][EQUALS][release_id]={{ inputs.release_id }}
finally:
- id: log_outcome
type: io.kestra.plugin.core.log.Log
description: One line per run whatever happened, including the input-validation
failure and the error path.
message: "Gate for release {{ inputs.release_id }} ({{ inputs.version }}) is
done; filter the Executions page by release_id = {{ inputs.release_id }}
to see the gate and its children."
afterExecution:
- id: notify_outcome
type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
description: |
Speaks on success and on an SLA breach. On 2.0.5 a `MAX_DURATION` breach ends the run at once, without
`errors` or `finally`, so the `release_sla` label set by the SLA is the only trace and this is the hook that reports it.
runIf: "{{ execution.state == 'SUCCESS' or (labels.release_sla ?? '') ==
'breached' }}"
allowFailure: true
url: "{{ secret('SLACK_WEBHOOK_URL') }}"
messageText: >-
{%- if (labels.release_sla ?? '') == 'breached' -%} :rotating_light:
Release gate for `{{ inputs.release_id }}` ran past 10 minutes and was
failed by its SLA; check the staging endpoint and the registries. {%- else
-%} :white_check_mark: Release `{{ inputs.release_id }}` ({{
inputs.version }}) passed the gate: GitHub release, image {{
inputs.container_image }}:{{ inputs.version }} and staging smoke are all
green. Record in KV `release_{{ inputs.release_id }}`. {%- endif %} {{
kestra.url ?? inputs.kestra_api_url }}/ui/{{ vars.tenant }}/executions/{{
flow.namespace }}/{{ flow.id }}/{{ execution.id }}
outputs:
- id: release_record
type: JSON
description: Null-safe. A failed gate returns an empty object here and the
details in the KV failure record.
value: "{{ fromJson(outputs.compose_record.values.record ?? '{}') }}"
- id: release_status
type: STRING
value: "{{ (outputs.compose_record.values.record ?? '') != '' ? 'ready' :
'failed' }}"