diff --git a/_data/argohub-nav.yml b/_data/argohub-nav.yml index 394f6f85e..17e4cbbf1 100644 --- a/_data/argohub-nav.yml +++ b/_data/argohub-nav.yml @@ -255,11 +255,17 @@ - title: Promotion setup guidelines url: "/create-promotion-sequence" - title: Promotion Flows - url: "/promotion-flow" + url: "/promotion-flow" - title: Promotion Policies url: "/promotion-policy" - title: Promotion Workflows - url: "/promotion-workflow" + url: "/promotion-workflow" + - title: Service accounts for Promotion Workflows + url: "/service-accounts-promotion-workflows" + - title: Promotion hooks + url: "/promotion-hooks" + - title: Promotion contexts in promotion hooks + url: "/promotion-context-promotion-workflows" - title: Product promotion settings url: "/product-promotion-props" - title: Promotion entity YAMLs diff --git a/_data/nav.yml b/_data/nav.yml index db8c8e51d..d6f6c23ef 100644 --- a/_data/nav.yml +++ b/_data/nav.yml @@ -434,11 +434,17 @@ - title: Promotion setup guidelines url: "/create-promotion-sequence" - title: Promotion Flows - url: "/promotion-flow" + url: "/promotion-flow" - title: Promotion Policies url: "/promotion-policy" - title: Promotion Workflows url: "/promotion-workflow" + - title: Service accounts for Promotion Workflows + url: "/service-accounts-promotion-workflows" + - title: Promotion hooks + url: "/promotion-hooks" + - title: Promotion contexts in promotion hooks + url: "/promotion-context-promotion-workflows" - title: Product promotion settings url: "/product-promotion-props" - title: Promotion entity YAMLs diff --git a/_docs/promotions/create-promotion-sequence.md b/_docs/promotions/create-promotion-sequence.md index c2094da1e..fca9dee3e 100644 --- a/_docs/promotions/create-promotion-sequence.md +++ b/_docs/promotions/create-promotion-sequence.md @@ -14,7 +14,7 @@ Promotions are a critical part of continuous delivery, enabling you to move chan ## Prerequisites 1. [Configuration Runtime]({{site.baseurl}}/docs/installation/gitops/configuration-runtime/) - The Configuration Runtime is a GitOps Runtime that stores promotion-related entities. + The Configuration Runtime is a GitOps Runtime that stores configuration for GitOps promotion entities. * Designate at least one GitOps Runtime as the Configuration Runtime. * If no GitOps Runtime has been designated as such, Codefresh assigns one of the existing Runtimes. @@ -24,10 +24,12 @@ Promotions are a critical part of continuous delivery, enabling you to move chan 1. [User permissions]({{site.baseurl}}/docs/administration/account-user-management/gitops-abac/) Users need permissions to create Promotion Workflows, configure promotion settings for products, and trigger promotions. + +## Setup tasks 1. [Create environments]({{site.baseurl}}/docs/environments/create-manage-environments/#create-environments) Environments define the starting point and destination of promotions. A promotion requires at least two environments: - * Trigger environment, the source of the changes being promoted + * Trigger Environment, the source of the changes being promoted * Target environment, to which to promote the changes 1. [Create applications]({{site.baseurl}}/docs/deployments/gitops/create-application/#create-an-argo-cd-application) @@ -43,26 +45,39 @@ Promotions are a critical part of continuous delivery, enabling you to move chan 1. [Create Promotion Workflows]({{site.baseurl}}/docs/promotions/promotion-workflow/) Promotion Workflows (Argo Workflows) automate environment-specific tests and validations before and after promotion. - * Create and use Promotion Workflows to run smoke tests, database validation, and other requirements to verify readiness. + * Create Promotion Workflows to run smoke tests, database validation, and any other requirements to verify readiness of each application in an environment. + +1. [Create Promotion Workflows with hooks]({{site.baseurl}}/docs/promotions/promotion-hooks/) + Promotion hooks provide promotion status and custom information for releases and environments during the Promotion Flow. + * Create hooks in Promotion Workflows to implement actions such as Slack notifications + * Define and export promotion contexts in hooks to expose and pass custom parameters such as Jira ID + 1. [Define Promotion Policies]({{site.baseurl}}/docs/promotions/promotion-policy/) Promotion Policies govern promotion behavior for environments enforcing rules, checks, and validations. * Define policies that combine Promotion Workflows with promotion actions such as commits, pull requests * The policy mechanism merges relevant settings from global policies according to priority, enforcing automated governance + 1. [Create Promotion Flows]({{site.baseurl}}/docs/promotions/promotion-flow/) Promotion Flows orchestrate the sequence of actions required to move and deploy changes through multiple environments. * Automatically integrate environments, products, Promotion Workflows, and Promotion Policies into a structured promotion process + * Assign promotion hooks to track release and environment statuses for product releases * Reuse Promotion Flows across products for consistent and reliable promotions + + 1. [Customize promotions for products]({{site.baseurl}}/docs/promotions/product-promotion-props/) After setting up promotion entities, configure additional promotion settings at the product level. * Promotion Templates to define attributes to be promoted across the product's applications * Promotion Flows valid for the product and trigger conditions for each flow +## Trigger and monitor promotions + 1. [Trigger promotions]({{site.baseurl}}/docs/promotions/trigger-promotions/) Trigger the promotion manually or automatically. - + + 1. [Monitor promotion releases for products]({{site.baseurl}}/docs/promotions/product-releases/) Monitor deployment progress as applications move through the promotion sequence. * Use the Releases feature for products to monitor deployments diff --git a/_docs/promotions/product-releases.md b/_docs/promotions/product-releases.md index 560384eee..4c576d68d 100644 --- a/_docs/promotions/product-releases.md +++ b/_docs/promotions/product-releases.md @@ -7,12 +7,11 @@ toc: true - +## Releases for promotions in GitOps Releases in Codefresh GitOps offer a consolidated view of the deployment lifecycle for a product as it progresses through environments during a promotion. They enable you to track, visualize, and analyze changes from the initial trigger to the final deployment, providing comprehensive insights for all stakeholders. A release is automatically created whenever a promotion is triggered for a product, either manually or through an automated flow. This ensures every change is documented and linked to its promotion lifecycle, giving teams complete visibility into their deployment processes. -## Releases in GitOps In the context of GitOps, a release captures the progression of a product as it is promoted through environments. The release reflects the collective state of all environments and workflows involved in deploying a change, from the initial trigger to the final target environment, whether production or another specified target. @@ -28,7 +27,7 @@ max-width="60%" %} ### Why Releases matter -Whether you are a product manager or an application developer, Releases offer: +Whether you are a product manager or an application developer, releases offer: * Lifecycle visualization: Clearly track the deployment lifecycle of a product * Integrated change list: Access a unified list of changes leading to a deployment * Deployment status: Monitor ongoing deployments and quickly identify issues @@ -64,7 +63,7 @@ There are two key aspects of tracking deployments for a product through releases ##### Release promotion flow Track the release visually to monitor its progression through each phase of the promotion lifecycle across environments. -Specific Release views centralizes all information, allowing you to: +Release views centralizes all information, allowing you to: * Identify and resolve deployment issues without switching between tools * Access everything you need to troubleshoot errors in one place. @@ -82,7 +81,7 @@ Release notes compile changes from various sources into a single view, enabling See [Analyze change history in Release Notes](#analyze-change-history-in-release-notes). -## View Releases for products +## View releases for products The Releases tab for a product displays the releases for that product, whether successful or failed. @@ -145,7 +144,7 @@ max-width="60%" The header in the Releases page summarizes the change that triggered the promotion, the overall status of the release, and the count of failed, successful, running, and pending environments. >**NOTE:** -The commit details are always for the trigger environment that initiated the promotion. +The commit details are always for the Trigger Environment that initiated the promotion. {% include image.html @@ -186,8 +185,8 @@ max-width="60%" ## Environments in product releases -The graphical view of the different environments defined in the Promotion Flo allows you to: -* Understand the interconnections between the environments, whether sequential or parallel. +The graphical view of the different environments defined in the Promotion Flow allows you to: +* Understand the interconnections between the environments, whether sequential or parallel * Visualize the dependencies between environments to see how changes propagate through the deployment process Each environment is color-coded to indicate the overall status of the promotion for that environment. @@ -253,8 +252,9 @@ If there is an update that triggers a Pre- or Post-Action Workflow within an env For example, if an update in the `staging` environment triggers the `echo-pre-action` Pre-Action Workflow, and a later update in the same environment also triggers the same `echo-pre-action` Pre-Action Workflow, the earlier instance is terminated, and the later instance continues to run. +## Promotion Hooks in product release +The **Show/Hide Hooks** toggle button in the Release view displays/hides the [promotion hooks]({{site.baseurl}}/docs/promotions/promotion-hooks/) assigned to the Promotion Flow. - ## Promotion Workflows in product releases diff --git a/_docs/promotions/promotion-components.md b/_docs/promotions/promotion-components.md index 35d788584..3202d5ff2 100644 --- a/_docs/promotions/promotion-components.md +++ b/_docs/promotions/promotion-components.md @@ -98,12 +98,18 @@ These entities provide additional control and automation, enabling advanced mult Users with ABAC permissions Promotion settings for products - + Promotion Workflow - An Argo Workflow which runs tests and validations during promotion for each environment. Promotion Workflows can include smoke tests, rollback mechanisms, database validation checks, performance checks, and more. + An Argo Workflow which runs tests and validations during promotion for each application within an environment. Promotion Workflows can include smoke tests, rollback mechanisms, database validation checks, performance checks, and more. Users with ABAC permissions Promotion Workflows + + Promotion hooks + Promotion hooks are configured in Promotion Workflows to run at the start or end of a product release, or at the start or end of promotions in environments. Promotion hooks can include notifications and actions such as sending Slack messages or custom issue-tracking information based on the status of the promotion for release or environment. + Users with ABAC permissions + Promotion Workflows + Promotion Policy Defines promotion behavior for environments by combining Promotion Workflows (tests and validations), with the promotion action such as commits or pull requests. diff --git a/_docs/promotions/promotion-context-promotion-workflows.md b/_docs/promotions/promotion-context-promotion-workflows.md new file mode 100644 index 000000000..93b6c1db3 --- /dev/null +++ b/_docs/promotions/promotion-context-promotion-workflows.md @@ -0,0 +1,427 @@ +--- +title: "Promotion contexts for promotion hooks" +description: "Use promotion contexts to expose custom parameters to hooks in Promotion Flows" +group: promotions +toc: true +--- + + +{{site.data.callout.callout_tip}} +Available as part of the early access program. +{{site.data.callout.end}} + +## About promotion contexts + +Promotion Workflows with hooks in Codefresh GitOps have access to a standard set of [default parameters]({{site.baseurl}}/docs/promotions/promotion-hooks/#default-arguments-in-promotion-hooks), such as the release ID, current release version, product, and commit SHA. When you define these parameters in the hook as input parameters, their values are dynamically retrieved from the ongoing promotion. + +Because promotion hooks run within GitOps Runtimes in your own clusters, custom parameters such as Jira ticket IDs, approver names, or Slack channel names are not automatically exposed to the promotion process. To use these custom parameters in hooks, you have two options: +* Define the custom parameters and their values manually in the workflow +* Use a **promotion context** for a more flexible and dynamic approach + +A **promotion context** is a user-defined JSON object that allows you to pass custom values between promotion hooks in the same Promotion Flow. See [Creating and exporting a promotion context](#creating-and-exporting-a-promotion-context) and [Example of Promotion Workflow with promotion context](#example-of-promotion-workflow-with-promotion-context). + +Defining a promotion context with the custom parameters and then **exporting the context** makes these custom values available to all subsequent hooks in the same Promotion Flow. Each hook can access and use the values from the promotion context as needed. +Using promotion contexts enables scenarios like notifying specific Slack channels or linking Jira tickets to releases. See [How promotion context works during execution](#how-promotion-context-works-during-execution). + +To see a practical example, follow the [Walkthrough: Using promotion hooks in Promotion Flows to handle promotion failures](#walkthough-using-promotion-hooks-in-promotion-flows-to-handle-promotion-failures), where you create different Promotion Workflows with hooks, define a promotion context in a workflow, and assign hooks at different stages of the Promotion Flow. + + +## Creating and exporting a promotion context +You can use any method to create a promotion context as a JSON object and define the parameters you need. +The key step is **exporting the promotion context**, as this makes its content available to the Promotion Workflow. The content is saved in the platform. + +When you export the promotion context, `name.outputs.parameters` must be set to `PROMOTION_CONTEXT` and _cannot be changed_. See [Example of Promotion Workflow with promotion context](#example-of-promotion-workflow-with-promotion-context). + + + +## Example of Promotion Workflow with promotion context +The example creates a promotion context `PROMOTION_CONTEXT` as a JSON object and exports it as an output parameter. +* The promotion context defines `JIRA_ISSUE_SOURCE_FIELD` and `JIRA_BASE_URL` +* Writes the context to a file `/tmp/promotion-context.txt` +* Adds `PROMOTION_CONTEXT` to `outputs.parameters.name`, defines `globalName` as the name of the promotion context, and in `valueFrom.path` specifies the file path where the promotion context JSON was saved for GitOps Cloud to retrieve and pass on to subsequent Promotion Workflows. + + +```yaml +... +spec: +... + - name: set-promotion-context + serviceAccountName: hook + inputs: + parameters: + - name: JIRA_ISSUE_SOURCE_FIELD + - name: JIRA_BASE_URL + script: + image: alpine + command: + - sh + source: | + export JIRA_ISSUE_BASE_URL="{{inputs.parameters.JIRA_BASE_URL}}" + export JIRA_ISSUE_SOURCE_FIELD="{{inputs.parameters.JIRA_ISSUE_SOURCE_FIELD}}" + PROMOTION_CONTEXT=$(echo "{\"JIRA_ISSUE_URL\": \"${JIRA_ISSUE_BASE_URL}/browse/${JIRA_ISSUE_SOURCE_FIELD}\"}") + echo "$PROMOTION_CONTEXT" > /tmp/promotion-context.txt + outputs: + parameters: + - name: PROMOTION_CONTEXT # cannot be changed + globalName: PROMOTION_CONTEXT # name of promotion context + valueFrom: + path: /tmp/promotion-context.txt +... +``` + +## How promotion context works during execution + +When a hook exports a promotion context, the promotion mechanism passes the parameters defined within the context to all subsequent hooks in the Promotion Flow. regardless of whether these hooks include promotion contexts. The promotion context is saved in the GitOps Cloud platform. + +This ensures: +* Context values persist across environments and clusters +* If a hook redefines a parameter already in the context, the new value takes precedence + + +##### Triggering the first promotion hook +When the Promotion Flow is triggered and a product release is created, the promotion mechanism: +* Passes the default input parameters defined (release ID, commit SHA for example) to all hooks configured for the Promotion Flow +* Initializes the promotion context, if defined and exported, with custom values + +##### Triggering subsequent promotion hooks +As the Flow progresses, the promotion mechanism: +* Retrieves the promotion context exported by the previous hook +* Passes the promotion context automatically to the next hook +* If the current hook defines one or more of the parameters from the promotion context as input parameters, their values are taken from the context +* If the current hook also exports a promotion context with the same parameter, the value from the current hook’s promotion context overrides the value from the previous context + + + +{% include +image.html +lightbox="true" +file="/images/gitops-promotions/hooks/promotion-context-behavior.png" +url="/images/gitops-promotions/hooks/promotion-context-behavior.png" +alt="Promotion context shared across promotion hooks in Promotion Flow" +caption="Promotion context shared across promotion hooks in Promotion Flow" +max-width="60%" +%} + + +## Walkthrough: Using promotion hooks in Promotion Flows to handle promotion failures + +Promotion hooks are designed to take action or provide information related to a release and its environments when a promotion is triggered. +In this walkthrough, you'll see how to create and export a promotion context, and create promotion hooks and use the promotion context to handle promotion failures, ensuring that stakeholders are notified with the right information—without needing to monitor the release manually. + +This walkthrough covers: +* [Creating a Promotion Workflow template with a generic promotion context](#create-promotion-workflow-template-with-generic-promotion-context) +* [Creating Promotion Workflows with hooks](#create-promotion-workflows-with-hooks) +* [Assigning hooks in Promotion Flow](#assign-hooks-to-promotion-flow) +* [Triggering hooks in Promotion Flow](#result-of-triggering-hooks-1-and-2-work-in-the-promotion-flow) + +### Create Promotion Workflow template with generic promotion context + +This Promotion Workflow template: +* Defines a generic promotion context as a key-value map in JSON format. +* Uses a single parameter, `context-params`, which is a JSON string of arbitrary keys and values, such as metadata for the promotion, Jira ticket references, base URLs. +* Exports the promotion context as `PROMOTION_CONTEXT`, ensuring that it's available to any promotion hook which references it. + +##### Example YAML + +```yaml +apiVersion: argoproj.io/v1alpha1 +kind: WorkflowTemplate +metadata: + name: set-promotion-context + annotations: + version: 0.0.1 + codefresh.io/workflow-origin: promotion +spec: + entrypoint: generate-context + templates: + - name: generate-context + serviceAccountName: hook + inputs: + parameters: + - name: context-params + description: JSON string of key-value pairs + # Example: '{"JIRA_ISSUE_SOURCE_FIELD": "ABC-123", "JIRA_BASE_URL": "https://jira.example.com"}' + script: + image: alpine + command: [sh] + source: | + echo '{{inputs.parameters.context-params}}' > /tmp/context.json + CONTEXT_JSON=$(cat /tmp/context.json) + + # Output the context as is + echo "$CONTEXT_JSON" > /tmp/promotion-context.txt + outputs: + parameters: + - name: PROMOTION_CONTEXT + globalName: PROMOTION_CONTEXT + valueFrom: + path: /tmp/promotion-context.txt +``` + + +### Create Promotion Workflows with hooks + +#### Hook 1: Create Jira ticket on promotion failure and export Jira issue URL through promotion context +This hook performs two main actions: +* Creates a Jira issue when a promotion fails. +* References the exports a promotion context that stores the URL of the created Jira issue, making it available to later hooks in the same Promotion Flow. + + +{: .table .table-bordered .table-hover} +| Hook 1 feature | Description | +|-----------------------------|---------------------------------------------------------------------------------------------------| +| **Two-step DAG structure** | The hook defines a Directed Acyclic Graph (DAG) with two steps: `create-issue` followed by `set-promotion-context`, which depends on successful Jira issue creation. | +| **Jira issue creation** | The `create-issue` step runs a container that creates a Jira issue and outputs its key or ID. | +| **Referenced template** | The `set-promotion-context` step uses a reusable WorkflowTemplate named `set-promotion-context`, referencing its `generate-context` template. | +| **Promotion context setup** | The `set-promotion-context` step passes a `context-params` JSON object with a dynamic Jira field value (`JIRA_ISSUE_SOURCE_FIELD`) from `create-issue` and a static base URL (`JIRA_ISSUE_URL`). It outputs this object as `PROMOTION_CONTEXT`. | +| **Global sharing of context** | The exported `PROMOTION_CONTEXT` is globally accessible to any subsequent hook in the Promotion Flow. | + + + + +##### Example YAML +```yaml +apiVersion: argoproj.io/v1alpha1 +kind: WorkflowTemplate +metadata: + name: jira-open-bug + annotations: + codefresh.io/workflow-origin: promotion + version: 0.0.1 + +spec: + serviceAccountName: hook + entrypoint: main-dag + templates: + - name: main-dag + dag: + tasks: + - name: create-issue + template: create-issue + - name: set-promotion-context + templateRef: + name: set-promotion-context + template: generate-context + depends: "create-issue.Succeeded" + arguments: + parameters: + - name: context-params + value: | + { + "JIRA_ISSUE_SOURCE_FIELD": "{{tasks.create-issue.outputs.parameters.JIRA_ISSUE_SOURCE_FIELD}}", + "JIRA_ISSUE_URL": "https://testjira273.atlassian.net" + } + + - name: create-issue + serviceAccountName: hook + retryStrategy: + limit: "3" + retryPolicy: "Always" + backoff: + duration: "5s" + inputs: + parameters: + - name: SLACK_TOKEN + valueFrom: + secretKeyRef: + name: promotions-secrets + key: slack-token + - name: JIRA_ISSUE_URL + value: https://testjira273.atlassian.net + - name: JIRA_USERNAME + value: testjira273@gmail.com + - name: JIRA_API_KEY_SECRET_KEY + default: 'api-key' + - name: JIRA_USERNAME_SECRET_KEY + default: 'username' + - name: ISSUE_PROJECT + default: 'TEST' + - name: ISSUE_SUMMARY + default: 'migration for product release failed' + - name: ISSUE_DESCRIPTION + default: 'fix migration and current db state' + - name: ISSUE_COMPONENTS + default: '' + - name: ISSUE_CUSTOMFIELDS + default: '' + - name: ISSUE_TYPE + default: 'Task' + outputs: + parameters: + - name: JIRA_ISSUE_SOURCE_FIELD + valueFrom: + path: /tmp/JIRA_ISSUE_SOURCE_FIELD + container: + name: main + imagePullPolicy: Always + image: quay.io/codefreshplugins/argo-hub-workflows-jira-versions-0.0.1-images-jira-manager:main + command: + - python + - /jira/jira_issue_manager.py + env: + - name: JIRA_BASE_URL + value: '' + - name: JIRA_USERNAME + value: '' + - name: JIRA_API_SECRET_KEY + value: '' + - name: ACTION + value: 'issue_create' + - name: ISSUE_PROJECT + value: '' + - name: ISSUE_SUMMARY + value: '' + - name: ISSUE_DESCRIPTION + value: '' + - name: ISSUE_COMPONENTS + value: '' + - name: ISSUE_CUSTOMFIELDS + value: '' + - name: ISSUE_TYPE + value: '' + volumeMounts: + - name: promotion-context + mountPath: /tmp + volumes: + - name: promotion-context + emptyDir: {} + +``` +

+ +#### Hook 2: Create a hook that sends a Slack notification +This hook sends a Slack notification when a promotion fails. It uses the promotion context set by the Jira creation hook to include a direct link to the Jira issue in the Slack message. + + +{: .table .table-bordered .table-hover} +| Hook 2 feature | Description | +| -------------- | -------------- | +| **Single-step notification flow** | This hook uses a simple, single `send-message` template to post a Slack message. | +| **Detailed Slack notification** | The Slack message the includes product name, commit SHA, promotion flow name, release URL, release ID, failed environments, error message, and **the Jira ticket URL**. | +| **Dynamic inputs** | Parameters like `PRODUCT_NAME`, `COMMIT_SHA`, `ERROR_MESSAGE`, and `JIRA_ISSUE_URL` are passed dynamically, allowing the message to include real-time promotion failure details. | +| **Simple and reusable Slack template** | The hook uses a standard Slack webhook and a flexible `SLACK_TEXT` format, making it easy to modify for different products or flows without changing the container logic. | +| **Promotion context usage** | The `JIRA_ISSUE_URL` from the promotion context created in the previous hook is injected into the Slack message, linking the notification directly to the Jira ticket for tracking. | + +##### Example YAML +```yaml +apiVersion: argoproj.io/v1alpha1 +kind: WorkflowTemplate +metadata: + name: slack-fail-hook + annotations: + codefresh.io/workflow-origin: promotion + version: 0.0.1 +spec: + arguments: + parameters: + - name: RELEASE_URL + - name: PRODUCT_NAME + - name: COMMIT_SHA + - name: PROMOTION_FLOW_NAME + - name: RELEASE_ID + - name: FAILED_ENVIRONMENTS + value: '[]' + - name: ERROR_MESSAGE + - name: JIRA_ISSUE_URL + serviceAccountName: hook + entrypoint: send-message + templates: + - name: send-message + retryStrategy: + limit: "1" + retryPolicy: "Always" + backoff: + duration: "5s" + inputs: + parameters: + - name: MODE + value: "simple" + - name: SLACK_HOOK_URL + value: https://hooks.slack.com/services/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 + - name: SLACK_TEXT + value: | + 🚨 *Promotion Failed!* 🚨 + *Product:* {{workflow.parameters.PRODUCT_NAME}} + *Trigger Commit Sha:* {{workflow.parameters.COMMIT_SHA}} + *Promotion Flow:* {{workflow.parameters.PROMOTION_FLOW_NAME}} + *Release:* <{{workflow.parameters.RELEASE_URL}}|View Release> + *Release ID:* {{workflow.parameters.RELEASE_ID}} + *Failed Environments:* {{workflow.parameters.FAILED_ENVIRONMENTS}} + *Error Message:* {{workflow.parameters.ERROR_MESSAGE}} + *JIRA Ticket:* {{workflow.parameters.JIRA_ISSUE_URL}} + container: + name: main + imagePullPolicy: Always + image: quay.io/codefreshplugins/argo-hub-slack-send-message:0.0.2-main + command: + - node + - /usr/src/app/index.js + env: + - name: MODE + value: '{{ inputs.parameters.MODE }}' + - name: SLACK_HOOK_URL + value: '{{ inputs.parameters.SLACK_HOOK_URL }}' + - name: SLACK_TEXT + value: '{{ inputs.parameters.SLACK_TEXT }}' + +``` + + +### Assign hooks to Promotion Flow + +The next step is to assign Hook 1 and Hook 2 to different stages of the Promotion Flow. + +Here's an example of the Chart and YAML views of a Promotion Flow with several promotion hooks assigned. The hooks relevant to the examples above are highlighted. + +{% include +image.html +lightbox="true" +file="/images/gitops-promotions/hooks/promotion-flow-hooks-chart-view.png" +url="/images/gitops-promotions/hooks/promotion-flow-hooks-chart-view.png" +alt="Chart view of Promotion Flows with hooks" +caption="Chart view of Promotion Flows with hooks" +max-width="60%" +%} + +{% include +image.html +lightbox="true" +file="/images/gitops-promotions/hooks/promotion-flow-hooks-yaml.png" +url="/images/gitops-promotions/hooks/promotion-flow-hooks-yaml.png" +alt="YAML view of Promotion Flows with hooks" +caption="YAML view of Promotion Flows with hooks" +max-width="60%" +%} + + + +### Result of triggering Hooks 1 and 2 work in the Promotion Flow +The table describes the results when the two hooks are triggered. + + +{: .table .table-bordered .table-hover} +| Step | Action | +|----|------| +| **1** | Promotion fails in `staging` environment | Triggers `On Failure` hook configured for `staging` environment | +| **2** | On Failure Hook 1: `jira-open-bug`| {::nomarkdown}
  1. Creates new Jira issue describing the release failure.
  2. Defines a promotion context including the Jira issue URL
  3. Exports the promotion context to all subsequent hooks in the Promotion Flow, including On Release Failure Hook 2: `slack-fail-hook`.
    4. | +| **3** | Promotion failure for environment triggers On Release Failure | Hook 2: `slack-fail-hook` sends a Slack notification to all stakeholders. The notification includes detailed failure information including the Jira issue URL value and other values available. | + +Here's an example of the Slack notification sent on release failure: + +{% include +image.html +lightbox="true" +file="/images/gitops-promotions/hooks/hook-slack-notification-example.png" +url="/images/gitops-promotions/hooks/hook-slack-notification-example.png" +alt="Example of Slack notification sent on release failure with link to Jira issue URL" +caption="Example of Slack notification sent on release failure with link to Jira issue URL" +max-width="60%" +%} + + + + +## Related articles +[Configure Promotion Workflows]({{site.baseurl}}/docs/promotions/promotion-workflow/) +[Configure hooks in Promotion Workflows]({{site.baseurl}}/docs/promotions/promotion-hooks/) +[Configure Promotion Flows]({{site.baseurl}}/docs/promotions/promotion-flow/) diff --git a/_docs/promotions/promotion-flow.md b/_docs/promotions/promotion-flow.md index 0caec8815..456421204 100644 --- a/_docs/promotions/promotion-flow.md +++ b/_docs/promotions/promotion-flow.md @@ -140,6 +140,7 @@ To ensure a successful promotion, the product must include an application in eac #### Application sync and health status Applications must be **Synced** and **Healthy** for a promotion to succeed. + #### Multiple applications in a target environment If a target environment includes multiple applications for the same product—segmented for example by region, tenant, or other criteria—each application in that environment is updated with changes from the source environment. @@ -149,12 +150,28 @@ Although this behavior may seem intuitive, it’s crucial to recognize that each Adding or deleting files from applications in target environments does not affect the Promotion Flow. The promotion mechanism simply retains the added/deleted files as they are in the target environments. +### Hooks in Promotion Flows +Promotion hooks provide promotion status and custom information for releases and environments during the Promotion Flow. +* Hooks are configured in Promotion Workflows and assigned to start/end of the release or specific environments in the Promotion Flow. +* All hooks receive a default set of arguments to configure actions or notifications based on success or failure. +* Promotion contexts within hooks when exported, expose custom parameters not natively available to the hooks. For example, you can link a Jira issue by creating a promotion context with the Jira ID and exporting it. + ### Promotion Policy settings -For each environment, you can explicitly set the Promotion Policy that defines governs promotion behavior for the environment through the Promotion Action (required), and Pre- and Post-Action Workflows. +For each environment, you can explicitly set the Promotion Policy that defines governs promotion behavior for the environment through the Promotion Action (required), and Pre- and Post-Action Workflows. You can also preview Policy settings by product before the flow is triggered. +{% include +image.html +lightbox="true" +file="/images/gitops-promotions/hooks/promotion-hooks-in-flow.png" +url="/images/gitops-promotions/hooks/promotion-hooks-in-flow.png" +alt="Promotion hooks in Promotion Flow" +caption="Promotion hooks in Promotion Flow" +max-width="60%" +%} + #### Inline vs. global Promotion Policy settings When you create or edit a Promotion Flow, the Flow Builder displays the Pre- and Post-Action Workflows, and the Promotion Action available for selection. @@ -229,7 +246,7 @@ Visually design and create the flow by selecting environments, Promotion Actions * **Flow Timeout**: The maximum duration allowed for the Promotion Flow to complete execution after being triggered, before it is automatically terminated. If not specified, the default timeout is 1 day (24 hours). * **Version**: (Optional) The version of the Promotion Flow. This is manually defined and manually updated, and is useful to indicate changes in the same flow. 1. In **Select Trigger Environment**, click {::nomarkdown}{:/} to see the list of available environments: - * Select an existing environment, select it and click **Add**. + * Select an existing environment and click **Add**. * To create a new environment, click **Add New Environment**. {% include @@ -243,7 +260,7 @@ max-width="50%" %} {:start="5"} -1. Optional. To add a trigger workflow to validate the trigger environment after the change and commit action, mouse over the left of the environment node, and click {::nomarkdown}{:/}, and select a Workflow. +1. Optional. To assign a workflow to validate the trigger environment after the change and commit action, mouse over the left of the environment node, and click {::nomarkdown}{:/}, and select a Workflow. * To apply a trigger workflow from global Promotion Policy settings, click **Account-level Promotion Policy**. * To add a new Promotion Workflow as the trigger workflow, click **Add New Workflow**. @@ -260,7 +277,6 @@ max-width="50%" {:start="6"} 1. To add a target environment to promote to, either sequentially or in parallel, mouse over the right of the environment to add to, click {::nomarkdown}{:/} and then select the environment or environments. The example below shows two environments, `qa` and `staging` as parallel environments to `dev`. - {% include image.html @@ -319,7 +335,9 @@ caption="Add Pre-/Post-Action Workflows" max-width="60%" %} -{:start="10"} +1. To assign promotion hooks to the start or release or to an environment do + +{:start="11"} 1. Click **Save Promotion Flow** on the top-right. The Name and Description are populated from the Settings. The flow's YAML version on the right lists the environment sequence. 1. To confirm, click **Save**. @@ -400,6 +418,7 @@ TBD --> ## Related articles +[Hooks in Promotion Flows]({{site.baseurl}}/docs/promotions/promotion-hooks/) [Trigger promotions]({{site.baseurl}}/docs/promotions/trigger-promotions/) [Tracking product promotions through releases]({{site.baseurl}}/docs/promotions/product-releases/) [Promotions: Setup & configuration guidelines]({{site.baseurl}}/docs/promotions/create-promotion-sequence/) diff --git a/_docs/promotions/promotion-hooks.md b/_docs/promotions/promotion-hooks.md new file mode 100644 index 000000000..27d1bd153 --- /dev/null +++ b/_docs/promotions/promotion-hooks.md @@ -0,0 +1,301 @@ +--- +title: "Configure hooks in Promotion Workflows" +description: "Configure hooks to capture release- and environment-level events in promotion releases" +group: promotions" +toc: true +--- + +{{site.data.callout.callout_tip}} +Available as part of the early access program. +{{site.data.callout.end}} + +## Promotion hooks overview + +Promotion hooks in GitOps Cloud are specialized Promotion Workflows that run at key stages of a product release to provide information on the release and its environments. A product release is created when a Promotion Flow is triggered, either manually or automatically. + +{% include +image.html +lightbox="true" +file="/images/gitops-promotions/hooks/promotion-hooks-in-flow.png" +url="/images/gitops-promotions/hooks/promotion-hooks-in-flow.png" +alt="Promotion hooks in Promotion Flow" +caption="Promotion hooks in Promotion Flow" +max-width="60%" +%} + +Promotion hooks use the same mechanism as standard Promotion Workflows but run with additional context and scope on releases and environments. +Unlike Pre- and Post-Action Promotion Workflows, which operate on each application within environments, promotion hooks run once per release or environment. They are not tied to a specific deployment or application, making them reusable across multiple flows. Promotion hooks enable real-time alerts, custom logic, and actions—without requiring users to monitor the promotion directly in the UI. Teams can stay informed and respond instantly as promotions progress. + + + +##### When are promotion hooks triggered? +Promotion hooks can run at different stages of a product release: +* **Release**: When Promotion Flow trigger creates a product release: + * **On start**: When the release is initiated + * **On success**: When the release completes successfully + * **On failure**: When the release fails +* **Per environment**: When a release transitions through specific environments: + * **On start**: When the promotion reaches an environment + * **On success**: When the promotion completes successfully in an environment + * **On failure**: When the promotion fails in an environment + +See [Assigning promotion hooks in Promotion Flows](#assigning-promotion-hooks-in-promotion-flows). For the YAML specifications of promotion hooks when assigned, see [Promotion Flow YAML]({{site.baseurl}}/docs/promotions/yaml/promotion-flow-crd/). + +##### Use cases for promotion hooks +* Auditing and visibility + Capture details on the entire product release and take action. + +* Notifications and reporting + Get timely alerts and notifications on success and failures alike through familiar channels. Send alerts to Slack, email, or monitoring tools based on release events to be always in the loop instead of having to constantly monitor the promotion release. + +* Integration with external tools + Automate updates to ticketing systems such as Jira, or observability platforms. + +* Approvals from external systems + Handle approvals required from external systems such as ServiceNow by pausing the promotion through a promotion hook when a PR pause is not feasible. + +Explore examples in [Codefresh Hub for Argo](https://codefresh.io/argohub/){:target="\_blank"}. + +##### Arguments in promotion hooks +A default set of arguments are available to all Promotion Workflows with hooks. See [Default arguments in Promotion Workflows with hooks](#default-arguments-for-promotion-hooks). + +## Promotion hooks vs. Pre- and Post-Action Promotion Workflows + +The table lists key differences between Promotion Workflows containing hooks and Promotion (Pre- and Post-Action) Workflows. + +| | **Promotion Workflows** | +| **Feature** | **Promotion Hook Workflows** | **Pre- and Post-Action Workflows** | +|----------------|----------------------|-----------------------------------------------| +| **Purpose** | Provide information on the release. | Provide information on promoted changes in applications within an environment. | +| **Execution** | Run at release start, end (success, failure), or per environment (start, success, failure). | Run for each application in an environment before and after promotion. | +| **Runtime** | Cluster with the Configuration Runtime. | Runtime managing the application. | +| **Scope** | Runs on cluster at release, or once per environment. | Runs per application in the environment. | +| **Effect on promotion** | If a hook fails, the product release fails as well.
    If the release is terminated, the On Fail and On Release Fail hooks, if defined, will run.
    If an On Start or On Success hook fails, the On Fail hook, if defined, will run. | If a workflow fails, the product release fails as well. | + + + + + +## Default arguments in Promotion Workflows with hooks +The table below describes the default arguments that are replaced with values that GitOps Cloud retrieves from the promotion process. +* When you create a Promotion Workflow template from the Codefresh UI, these arguments are automatically defined in `spec.arguments.parameters`. +* When you create a template in Git, you must _manually add these arguments as required inputs_ if you want to use them. + +{: .table .table-bordered .table-hover} +| Parameter | Description | Notes | +| -------------- | -------------- | -------------- | +|`RELEASE_URL` | The URL link to the release associated with the promotion. | All hooks | +|`PRODUCT_NAME` | The name of the product for which the promotion release is running. | All hooks | +|`VERSION` | The version of the current release.| All hooks | +|`COMMIT_SHA` | The unique identifier (SHA) of the commit, generated by Git, that triggered the promotion and created the release.| All hooks | +|`PROMOTION_FLOW_NAME` | The name of the Promotion Flow triggered for the release. | All hooks | +|`RELEASE_ID` | The unique identifier of the release. | All hooks | +|`ERROR_MESSAGE` | The system-generated error message identifying the reason why the release failed to complete. For example, `Product release was automatically terminated because the workflow state remained unknown`. | OnFailed hooks only | +|`FAILED_ENVIRONMENTS` | The environment or environments which failed in the release with this information: {::nomarkdown}