diff --git a/_data/nav.yml b/_data/nav.yml index 81ba0b8e1..650efe5a6 100644 --- a/_data/nav.yml +++ b/_data/nav.yml @@ -388,6 +388,8 @@ url: "/secrets-store" - title: Public logs and status badges url: "/build-status" + - title: Pipeline specifications + url: "/specifications" - title: Steps in pipelines url: "/steps" sub-pages: diff --git a/_docs/integrations/codefresh-api.md b/_docs/integrations/codefresh-api.md index 55d43d453..8147c8b42 100644 --- a/_docs/integrations/codefresh-api.md +++ b/_docs/integrations/codefresh-api.md @@ -267,336 +267,342 @@ spec: ## Full pipeline specification -If you don't want to create a pipeline from an existing one, you can also create your own YAML from scratch. -The following sections contain an explanation of the fields. +In Codefresh, every pipeline is defined by a pipeline schema, a JSON representation of its structure and settings. The schema includes information about pipeline steps, triggers, variables, and other configuration details. + +You can manage the pipeline schema in two ways: + +* **Visually in the Codefresh UI by editing the pipeline** + See [Account-level settings for pipelines]({{site.baseurl}}/docs/pipelines/configuration/pipeline-settings/). + See [Pipeline settings]({{site.baseurl}}/docs/pipelines/pipelines/#pipeline-settings/). + + +* **Programmatically via the Codefresh API by retrieving and updating the schema** + Described here. + + >**NOTE** Codefresh automatically generates additional fields, usually fields with dates and internal ID numbers. While you cannot edit these fields, you can view them by exporting the pipeline. -### Top level fields + +### .version {: .table .table-bordered .table-hover} -| Field name | Parent field | Type | Value | -| -------------- | ---------------------------- |-------------------------| -------------------------| -| `version` | | string | Always `'1.0'` | -| `kind` | | string | Always `pipeline` | -| `metadata` | | object | Holds various meta-information | -| `spec` | | object | Holds the pipeline definition and other related information | +| Field | Description | Type | Required/Optional | +| -------------- | ---------------------------- |-----------| -------------------------| +| `.version` | The version of the pipeline schema, always set to `'1.0'`. | string | Required | -### Metadata fields +### .kind {: .table .table-bordered .table-hover} -| Field name | Parent field | Type | Value | -| -------------- | ---------------------------- |-------------------------| -------------------------| -| `name` | `metadata` | string | the full pipeline name should be formatted `project_name/pipeline_name` | -| `project` | `metadata` | string | the project that contains this pipeline | -| `originalYamlString` | `metadata` | string | the full contents of the pipeline editor. Only kept for archival purposes | -| `labels` | `metadata` | object | Holds the `tags` array | -| `tags` | `labels` | array | A list of [access control tags]({{site.baseurl}}/docs/administration/account-user-management/access-control/#marking-pipelines-with-policy-attributes) for this pipeline | -| `description` | `metadata` | string | Human readable description of the pipeline | -| `isPublic ` | `metadata` | boolean | If true, the pipeline logs [will be public]({{site.baseurl}}/docs/pipelines/configuration/build-status/) even for non-authenticated users | -| `template ` | `metadata` | boolean | If true, this pipeline will be listed as a template when creating a new pipeline | - -Example of metadata: -`Pipeline Spec` -{% highlight yaml %} -{% raw %} -version: '1.0' -kind: pipeline -metadata: - name: project_name/pipeline_name - project: project_name - labels: - tags: - - tag1 - - tag2 - description: pipeline description here - isPublic: false - template: - isTemplate: false -{% endraw %} -{% endhighlight %} +| Field | Description | Type | Required/Optional | +| -------------- | ---------------------------- |-----------| -------------------------| +| `.kind` | The kind object type for the schema and is always set to `pipeline`. | string | Required | -### Spec fields +### .metadata {: .table .table-bordered .table-hover} -| Field name | Parent field | Type | Value | -| -------------- | ---------------------------- |-------------------------| -------------------------| -| `steps` | `spec` | object | The [pipeline steps]({{site.baseurl}}/docs/pipelines/steps/) to be executed | -| `stages` | `spec` | array | The [pipeline stages]({{site.baseurl}}/docs/pipelines/stages/) for a better visual overview | -| `variables` | `spec` | array | List of variables defined in the pipeline itself | -| `contexts` | `spec` | array | Variable sets imported from [shared configuration]({{site.baseurl}}/docs/pipelines/configuration/shared-configuration/) | -| `runtimeEnvironment` | `spec` | array | where to execute this pipeline | -| `terminationPolicy ` | `spec` | array | Termination settings of this pipeline | -| `concurrency ` | `spec` | number | How many instances of this pipeline [can run at the same time]({{site.baseurl}}/docs/pipelines/pipelines/#policies) | -| `triggerConcurrency ` | `spec` | number | How many instances of this pipeline can run at the same time per trigger | -| `branchConcurrency ` | `spec` | number | How many instances of this pipeline can run at the same time per branch | -| `externalResources ` | `spec` | array | Optional external files available to this pipeline | -| `triggers` | `spec` | array | a list of [Git triggers]({{site.baseurl}}/docs/pipelines/triggers/git-triggers/) that affect this pipeline | -| `options` | `spec` | object | Extra options for the pipeline | -| `enableNotifications` | `options` | boolean | if false the pipeline will not send notifications to [Slack]({{site.baseurl}}/docs/integrations/notifications/slack-integration/) and status updates back to the Git provider | - -### Pipeline variables - -The `variables` array has entries with the following fields: + +| Field | Description | Type | Required/Optional | +| -------------- | ---------------------------- |-----------| -------------------------| +| `metadata.id` | The ID of the pipeline. The ID is generated when the pipeline is created. Available in **Pipeline > Settings > General > Pipeline ID**. | string | Optional | +| `metadata.name` | The full path to the pipeline, including the name of the project to which the pipeline belongs, in the format `/`. For example, `marvel/smoke-tests` | string | Required | +| `metadata.shortName` | The name of the pipeline without the ``. For example, `smoke-tests`. | string | Optional | +| `metadata.revision` | Automatically updated for each update of the pipeline. Default is `0`. | integer | Optional | +| `metadata.isPublic` | Determines if public logs are enabled or disabled for the pipeline. By default, public logs are disabled.
When set to `true`, clicking the build badge allows all users with access to the pipeline to also view the build logs, even if they are not logged into Codefresh. See [Public build logs]({{site.baseurl}}//docs/pipelines/configuration/build-status/#public-build-logs).| boolean | Optional | +| `metadata.description` | A meaningful description of the pipeline. | string | Optional | +| `metadata.labels` | The parent object for `metadata.labelKeys` defining the `tags` assigned to the pipeline. | object | Optional | +| `metadata.labelKeys` | The tag or tags to assign to the pipeline. The tags are used to define [RBAC rules]({{site.baseurl}}/docs/administration/account-user-management/access-control/#marking-pipelines-with-policy-attributes) for this pipeline. | string | Optional | +| `metadata.created_at` | The date and time at which the pipeline was created, in ISO 8601 format.
For example, `2024-09-18T16:43:16.751+00:00`.| date | Optional | +| `metadata.updated_at` | The date and time at which the pipeline was last updated, in ISO 8601 format.
For example, `2024-10-18T10:43:16.751+00:00`.| date | Optional | +| `metadata.accountId` | The ID of the account to which the pipeline belongs.
For example, `65c5386d7b71f25b3bbb8006`. The account ID is available by clicking the Settings icon in the toolbar, in **Organization Information > General**.| objectId | Optional | +| `metadata.originalYamlString` | The full content of the `Inline YAML` pipeline editor, either with only the default settings or with user-defined settings. | string | Optional | +| `metadata.projectId` | The ID of the project to which the pipeline belongs. | obejctId | Optional | +| `metadata.project` | The name of the project to which the pipeline belongs. | string | Optional | +| `metadata.template` | Determines if the pipeline is designated and available as a template when creating a new pipeline. | | | +| `metadata.template.isTemplate` | When set to `true`, the pipeline name is displayed in the Pipeline Template list. | boolean | Optional | +| `metadata.template.generatedFrom` | The ID of the template pipeline from which the pipeline is created. | objectId | Optional | +| `metadata.executionContextId` | The name of the specific execution context to use for the pipeline to makes API calls to the pipeline.
See [Pipeline execution context]({{site.baseurl}}/docs/administration/account-user-management/pipeline-execution-context/). | string | Optional | + + + +### .spec {: .table .table-bordered .table-hover} -| Field name | Parent field | Type | Value | -| -------------- | ---------------------------- |-------------------------| -------------------------| -| `key` | `variables` | string | Name of the variable | -| `value` | `variables` | string | Raw value | -| `encrypted` | `variables` | boolean | if true the value is stored encrypted | +| Field | Description | Type | Required/Optional | +| -------------- | ---------------------------- |-----------| -------------------------| +| `spec.scopes` | The custom API scopes controlling access to the pipeline. Configuring custom scopes will override the account-level defaults for this pipeline. | array of strings | Optional | +| `spec.scopeSnapshot` | The ID of the scope snapshot. | string | Optional | +| `spec.permitRestartFromFailedSteps` | Determines if users can restart the pipeline from the failed step, instead of from the beginning of the pipeline.
Leave empty to inherit the account-level setting.
When set to `true`, users can restart the pipeline from the failed step.
See [Restarting a failed pipeline]({{site.baseurl}}/docs/pipelines/monitoring-pipelines/#restarting-the-pipeline).| boolean | Optional | +| `spec.build_version` | `v1` or `v2` | string | Optional | +| `spec.triggers` | The list of Git triggers defined for the pipeline. For details, see [`spec.triggers`](#spectriggers). | array | Optional | +| `spec.cronTriggers` | The list of Cron or timer-based triggers defined for the pipeline. For details, see [`spec.cronTriggers`](#speccrontriggers). | array | Optional | +| `spec.runtimeEnvironment` | The runtime environment selected for the pipeline and its configuration settings such as memory and CPU. For details, see [`spec.runtimeEnvironments`](#specruntimeenvironment). | object | Optional | +| `spec.requiredAvailableStorage` | The minimum disk space for the pipeline’s build volume in `Gi`.
When defined, Codefresh assigns either a cached disk with sufficient disk space or a new empty disk at the start of the build.
When empty, only the space not allocated for caching is available for the build volume.
See [Set minimum disk space for a pipeline build]({{site.baseurl}}/docs/pipelines/pipelines/#set-minimum-disk-space-for-a-pipeline-build). | string | Optional | +| `spec.lowMemoryWarningThreshold` | The memory-usage threshold for the pipeline's build exceeding which to display banner alerts. Useful to get timely warnings and prevent build failures.
Can be one of the following:{::nomarkdown}
  • WARNING: Displays a banner when memory usage exceeds 70% of the available memory.
  • CRITICAL: Displays a banner when memory usage exceeds 90% of the available memory.
  • REACHED_LIMIT: Displays a banner when memory usage exceeds 100% of the available memory. Setting this threshold means that the pipeline build has already failed when the banner is displayed.
{:/}See also [Set memory usage threshold for pipeline build]({{site.baseurl}}/docs/pipelines/pipelines/#set-memory-usage-threshold-for-pipeline-build).| string | Optional| +| `spec.packId` | Required for SaaS environments. Optional for hybrid environments.
The package identifier based on the resource size. Can be one of the following:{::nomarkdown}
  • 5cd1746617313f468d669013: Small
  • 5cd1746717313f468d669014: Medium
  • 5cd1746817313f468d669015: Large
  • 5cd1746817313f468d669017: Extra large
  • 5cd1746817313f468d669018: XXL
  • 5cd1746817313f468d669020: 4XL
{:/} | string | Required (for SaaS) | +| `spec.context` | Single or multiple comma-separated shared configuration contexts, including shared secrets to add to the pipeline.
See [Shared configuration contexts]({{site.baseurl}}/docs/pipelines/configuration/shared-configuration/). | array | Optional | +| `spec.clustersInfo` | Determines if all or specific Kubernetes clusters are available for the pipeline build. Leave empty to inherit the account-level setting.
See [Select Kubernetes cluster contexts]({{site.baseurl}}/docs/pipelines/pipelines/#select-kubernetes-cluster-contexts). | object | Optional | +| `spec.variables` | The variables defined in the pipeline. See [spec.variables](#specvariables). | array | Optional | +| `spec.specTemplate` | See [spec.specTemplate](#specspectemplate). | object | Optional | +| `spec.steps` | The steps to be executed by the pipeline, as a list of key-value pairs.
See [Steps in pipelines]({{site.baseurl}}/docs/pipelines/steps/). | object | Required | +| `spec.services` | Auto-generated based on the content of `metadata.originalYamlString`.
See [Service containers in pipelines]({{site.baseurl}}/docs/pipelines/service-containers/). | object | Optional | +| `spec.hooks` | Auto-generated based on the content of `metadata.originalYamlString`.
See [Hooks in pipelines]({{site.baseurl}}/docs/pipelines/hooks/).| object | Optional | +| `spec.stages` | The stages into which to group the pipeline's steps.
When defined, each stage is displayed as a separate column in the pipeline's build view.
Stages are only for visualization and do not affect pipeline execution.
See [Grouping steps into stages]({{site.baseurl}}/docs/pipelines/stages/). | array | Optional | +| `spec.mode` | The execution mode for the pipeline. Leave empty to use the default.
Can be one of the following:{::nomarkdown}
  • sequential: The default, executes the steps in the order in which they are listed.
  • parallel: Evaluates all step conditions at the same time and executes those steps that meet the requirements in parallel. Parallel execution mode allows you to order steps in ways not possible with sequential mode.
{:/}See [Advanced workflows for pipelines]({{site.baseurl}}/docs/pipelines/advanced-workflows/). | string | Optional | +| `spec.fail_fast` | Determines pipeline execution behavior in case of step failure. Leave empty to use the default. {::nomarkdown}
  • true: The default, terminates pipeline execution upon step failure. The Build status returns Failed to execute.
  • false: Continues pipeline execution upon step failure. The Build status returns Build completed successfully.
    To change the Build status, set spec.strict_fail_fast to true.
{:/} | boolean | Optional | +| `spec.strict_fail_fast` | Specifies how to report the Build status when `fail_fast` is set to `false`.
**NOTE**:
Requires Runner chart v6.3.9 or higher.

You can set the Build status reporting behavior at the root-level or at the step-level for the pipeline.{::nomarkdown}
  • true:
    • When set at the root-level, returns a Build status of failed when any step in the pipeline with fail_fast=false fails to execute.
    • When set at the step-level, returns a Build status of failed when any step in the pipeline with fail_fast=false and strict_fail_fast=true fails to execute.
  • false:
    • When set at the root-level, returns a Build status of successful when any step in the pipeline with fail_fast=false fails to execute.
    {:/} | +| `spec.concurrency` | The maximum number of concurrent builds for the pipeline, ranging from `0`, the default, to `14`, ????or unlimited. Define the concurrency when your pipeline has only one trigger.
    When set to `0`, freezes execution of the pipeline, switching it to maintenance mode. Use this concurrency setting to modify existing pipelines and freeze execution until you complete the changes. |integer | Optional | +| `spec.triggerConcurrency` | The maximum number of concurrent builds per trigger, ranging from `1-15`, or unlimited. Define the trigger concurrency when your pipeline has multiple triggers. | integer | Optional | +| `spec.branchConcurrency` | The maximum number of concurrent builds per branch, ranging from `1-15`, or unlimited. Define the branch concurrency when your pipeline can run builds on different branches. | integer | Optional | +| `spec.priority` | The priority of the pipeline build, determining the order in which the build is queued. The priority can range from `100` (highest priority), to `-100`(lowest priority), with `0` as the default. | +| `spec.debug.steps.phases` |The phase or stage at which the debug step should run.{::nomarkdown}
    • before: The step runs before the build starts.
    • after: The step runs after the build starts.
    • override: ???.
    {:/} |boolean | Optional | + + + + + +### spec.triggers -Example of variables: +{: .table .table-bordered .table-hover} +| Field | Description | Type | Required/Optional | +| -------------- | ---------------------------- |-----------| -------------------------| +| `spec.triggers.type` | Always set to `git`. | string | Required | +| `spec.triggers.id` | The ObjectID which is auto generated on creating a trigger. | string | Optional | +| `spec.triggers.createdFromRepositoryMigration` | Determines if the trigger was automatically created when migrating repositories. | boolean | Optional | +| `spec.triggers.name` | The user-defined name of the Git trigger. Can have a minimum of one and maximum of 200 characters, including these special characters `/`, `^`, `\`, `S`, `*`, `$`, and without spaces. Regex expressions are also supported. | string | Required| +| `spec.triggers.description` | A meaningful of the Git trigger. Can have a minimum of one and maximum of 150 characters. | string | Optional| +| `spec.triggers.commitStatusTitle` | The title of the commit message when the Git trigger is activated. Can have a minimum of one and maximum of 200 characters. | string | Optional| +| `spec.triggers.contexts` | The variable sets imported from [shared configuration]({{site.baseurl}}/docs/pipelines/configuration/shared-configuration/). |array | Optional | +| `spec.triggers.verified` | Determines if to validate access to the Git repo for which trigger is created.
    When set to `true`, the default, always validates access to the Git repo. |boolean | Optional | +| `spec.triggers.status` | ?? |string | Optional | +| `spec.triggers.repo` | The Git repo to track for this trigger, in the format `/`. |string | Optional | +| `spec.triggers.provider` | The name of the Git provider as defined in the Git integrations set up for pipelines. See [Git provider pipeline integrations]({{site.baseurl}}/docs/integrations/git-providers/| string |Optional | +| `spec.triggers.disabled` | Determines if the Git trigger is enabled for activation or always disabled.
    When set to `true`, the trigger is always disabled and never activated. | boolean | Optional | +| `spec.triggers.skipCommentAuthorAssociationValidation` | ???| boolean | Optional | +| `spec.triggers.events` | The possible list of Git events that can be configured to activate the trigger depending on the Git provider. See [spec.triggers.events](#spectriggersevents). | array | Required | +| `spec.triggers.commentRegex` | Defines if to activate the trigger only if the pull request (PR) comment matches a specific pattern defined by a regular expression (regex). | string | Optional | +| `spec.triggers.branchRegex ` | Defines if to activate the trigger only if the regex expression/string matches the branch name as defined by `branchRegexInput`. | string | Optional| +| `spec.triggers.branchRegexInput` | Defines the type of content used in `branchRegex`, and can be one of the following: {::nomarkdown}
    • regex: Match branch names based on specific patterns.
      For example, `feature/.*` would match any branch that starts with `feature/`.
    • multiselect: Match one or more of the predefined list of branch names.
    • multiselect-exclude: Does not match any of the predefined branch names in the list.
    {:/} | string | Optional | +| `spec.triggers.pullRequestTargetBranchRegex` | ??? | string | Optional | +| `spec.triggers.pullRequestAllowForkEvents` | Determines if the Git trigger is also valid for Git forks.
    When set to `true`, the default, the trigger is also activated for Git repos forked from `spec.triggers.repo`. | boolean | Optional | +| `modifiedFilesGlob` | Defines if to activate the trigger when the changed files match glob expression. Glob expressions can have maximum of 65500/65536 characters, including `' '`| string | Optional | +| `spec.triggers.gerritCIStatusLabels` | The labels indicating the CI status. | array | Optional | +| `spec.triggers.context` | The name of the Git integration to use. | string | Optional | +| `spec.triggers.concurrency` | The maximum number of concurrent builds for this trigger, and can range from `1` (the default), to `15`, or unlimited). Define the trigger concurrency when your pipeline has multiple triggers. | string | Optional | +| `spec.triggers.priority` | The priority for the specific trigger determining the order in which the trigger is executed.
    The priority can range from `100` (highest priority) to `-100` (lowest priority), with `0` as the default. + | integer | Optional | +| `spec.triggers.terminationPolicy` | The options that determine when to terminate the build from the pipeline. See [spec.terminationPolicy](#specterminationpolicy). | integer | Optional | + + + + + + +### spec.triggers.events + +Trigger events depend on and are specific to every Git provider. + +See trigger events for: -`Pipeline Spec` -{% highlight yaml %} -{% raw %} - variables: - - key: my-key - value: my-value - encrypted: false - - key: my-second-variable - value: '*****' - encrypted: true -{% endraw %} -{% endhighlight %} +{: .table .table-bordered .table-hover} +|Git provider | Field | Description | Type | Required/Optional | +|-------------| -------------- | |-----------| -------------------------| +|GitHub | `spec.triggers.events.push` | | string | Required | +| | `spec.triggers.events.push.heads` | | string | Required | +| | `spec.triggers.events.push.tags` | | string | Required | +| | `spec.triggers.events.push.newBranch` | | string | Required | +| | `spec.triggers.events.push.deleteBranch` | | string | Required | +| | `spec.triggers.events.pullrequest` | | string | Required | +| | `spec.triggers.events.pullrequest.opened` | | string | Required | +| | `spec.triggers.events.pullrequest.closed` | | string | Required | +| | `spec.triggers.events.pullrequest.reopened` | | string | Required | +| | `spec.triggers.events.pullrequest.edited` | | string | Required | +| | `spec.triggers.events.pullrequest.assigned` | | string | Required | +| | `spec.triggers.events.pullrequest.unassigned` | | string | Required | +| | `spec.triggers.events.pullrequest.review_requested` | | string | Required | +| | `spec.triggers.events.pullrequest.review_request_removed` | | string | Required | +| | `spec.triggers.events.pullrequest.reviewRequested` | | string | Required | +| | `spec.triggers.events.pullrequest.reviewRequestRemoved` | | string | Required | +| | `spec.triggers.events.pullrequest.submitted.approved` | | string | Required | +| | `spec.triggers.events.pullrequest.submitted.commented` | | string | Required | +| | `spec.triggers.events.pullrequest.submitted.changes_requested` | | string | Required | +| | `spec.triggers.events.pullrequest.pushCommit` | | string | Required | +| | `spec.triggers.events.pullrequest.labeled` | | string | Required | +| | `spec.triggers.events.pullrequest.unlabeled` | | string | Required | +| | `spec.triggers.events.pullrequest.synchronize` | | string | Required | +| | `spec.triggers.events.pullrequest.commentAdded` | | string | Required | +| | `spec.triggers.events.pullrequest.commentAddedUnrestricted` | | string | Required | +|AzureDevOps| `spec.triggers.events.pullrequest.reviewersUpdate` | | string | Required | +| | `spec.triggers.events.pullrequest.statusUpdate` | | string | Required | +| | `spec.triggers.events.pullrequest.reviewerVote` | | string | Required | +| | `spec.triggers.events.pullrequest.created` | | string | Required | +| | `spec.triggers.events.pullrequest.merged` | | string | Required | +| | `spec.triggers.events.pullrequest.unmerged-closed` | | string | Required | +| | `spec.triggers.events.pullrequest.updated` | | string | Required | +| | `spec.triggers.events.release.unpublished` | | string | Required | +| | `spec.triggers.events.release.created` | | string | Required | +| | `spec.triggers.events.release.edited` | | string | Required | +| | `spec.triggers.events.release.deleted` | | string | Required | +| | `spec.triggers.events.release.prereleased` | | string | Required | +| | `spec.triggers.events.release.released` | | string | Required | +|Bitbucket| `spec.triggers.events.pullrequest.created` | | string | Required | +| | `spec.triggers.events.pullrequest.updatedButNoPush` | | string | Required | +| | `spec.triggers.events.pullrequest.deleted` | | string | Required | +| | `spec.triggers.events.pullrequest.fulfilled` | | string | Required | +| | `spec.triggers.events.pullrequest.rejected` | | string | Required | +| | `spec.triggers.events.pullrequest.merged` | | string | Required | +| | `spec.triggers.events.pullrequest.declined` | | string | Required | +| | `spec.triggers.events.pullrequest.comment_created` | | string | Required | +| | `spec.triggers.events.pullrequest.comment_updated` | | string | Required | +| | `spec.triggers.events.pullrequest.comment_deleted` | | string | Required | +| | `spec.triggers.events.pullrequest.approved` | | string | Required | +| | `spec.triggers.events.pullrequest.unapproved` | | string | Required | +|Bitbucket-server | `spec.triggers.events.pullrequest.push_commit` | | string | Required | +| | `spec.triggers.events.pullrequest.needsWork` | | string | Required | +|Gerrit| `spec.triggers.events.change-abandoned` | | string | Required | +| | `spec.triggers.events.change-deleted` | | string | Required | +| | `spec.triggers.events.change-merged` | | string | Required | +| | `spec.triggers.events.change-restored` | | string | Required | +| | `spec.triggers.events.comment-added` | | string | Required | +| | `spec.triggers.events.dropped-output` | | string | Required | +| | `spec.triggers.events.hashtags-changed` | | string | Required | +| |`spec.triggers.events.project-created` | | string | Required | +| | `spec.triggers.events.patchset-created` | | string | Required | +| | `spec.triggers.events.ref-updated` | | string | Required | +| | `spec.triggers.events.reviewer-added` | | string | Required | +| | `spec.triggers.events.reviewer-deleted` | | string | Required | +| | `spec.triggers.events.topic-changed` | | string | Required | +| | `spec.triggers.events.wip-state-changed` | | string | Required | +| | `spec.triggers.events.private-state-changed` | | string | Required | +| | `spec.triggers.events.vote-deleted` | | string | Required | +| | `spec.triggers.events.project-head-update` | | string | Required | + + + +###### +* [GitHub]({{site.baseurl}}/docs/pipelines/triggers/git-triggers/#github-trigger-events) +* [Azure DevOps]({{site.baseurl}}/docs/pipelines/triggers/git-triggers/#azure-devops-trigger-events) +* [BitBucket Cloud]({{site.baseurl}}/docs/pipelines/triggers/git-triggers/#bitbucket-cloud-trigger-events) +* [BitBucket Server]({{site.baseurl}}/docs/pipelines/triggers/git-triggers/#bitbucket-server-trigger-events) +* [GitLab]({{site.baseurl}}/docs/pipelines/triggers/git-triggers/#gitlab-trigger-events) +* [Gerrit]({{site.baseurl}}/docs/pipelines/triggers/git-triggers/#gerrit-trigger-events) + + +### spec.cronTriggers -Encrypted variables cannot be read back by exporting the pipeline. +{: .table .table-bordered .table-hover} +| Field | Description | Type | Required/Optional | +| -------------- | ---------------------------- |-----------| -------------------------| +| `spec.cronTriggers.type` | Always set to `cron`. | string | Required | +| `spec.cronTriggers.id` | The ID of the Cron trigger, automatically generated when created. | string | Optional | +| `spec.cronTriggers.event` | Leave empty. Automatically generated by Codefresh for internal use. | string | Optional | +| `spec.cronTriggers.name` | The user-defined name of the Cron trigger. Can have a minimum of one and maximum of 200 characters. ???? including these special characters `/`, `^`, `\`, `S`, `*`, `$`, and without spaces. Regex expressions are also supported. | string | Required| +| `spec.cronTriggers.message` | The free-text message to be sent as an additional event payload every time the Cron trigger is activated. For example, `Successful ingress tests`.| string | Required| +| `spec.cronTriggers.expression` | The Cron expression that defines the time and frequency of the Cron trigger.
    For example, `0 3 * * 1-5` triggers the pipeline at _3:00 AM every weekday (Monday to Friday)_. | string | Required| +| `spec.cronTriggers.verified` | ?? |boolean | Optional | +| `spec.cronTriggers.disabled ` | Determines if the Cron trigger is enabled for activation.
    By default, set to `false` meaning that it is always enabled.
    To disable the trigger, set to `true`. | boolean | Optional | +| `spec.cronTriggers.status` | ?? |string | Optional | +| `spec.cronTriggers.lastExecutionDate` | T???? |date | Optional | +| `spec.cronTriggers.gitTriggerId` |The ID of the Git trigger to simulate for the pipeline, retrieved from the pipeline for which it is defined.
    To simulate a Git trigger, the pipeline must have at least one Git trigger defined for it.
    See [Git triggers](#git-triggers) in this article.| string |Optional | +| `spec.cronTriggers.branch` | Valid only when a Git trigger is simulated.
    The branch of the repo retrieved from the Git trigger defined in `spec.cronTriggers.gitTriggerId`. | string | Optional | -### Runtime environment -The `runtimeEnvironment` selects the cluster that will execute the pipeline (mostly useful for organizations using the [Codefresh Runner]({{site.baseurl}}/docs/installation/runner/install-codefresh-runner/)). -{: .table .table-bordered .table-hover} -| Field name | Parent field | Type | Value | -| -------------- | ---------------------------- |-------------------------| -------------------------| -| `name` | `runtimeEnvironment` | string | Name the environment as connected by the runner | -| `cpu` | `runtimeEnvironment` | string | CPU share using Kubernetes notation | -| `memory` | `runtimeEnvironment` | string | memory share using Kubernetes notation | -| `dindStorage` | `runtimeEnvironment` | string | storage size using Kubernetes notation | -Example of metadata: -`Pipeline Spec` -{% highlight yaml %} -{% raw %} -runtimeEnvironment: - name: my-aws-runner/cf - cpu: 2000m - memory: 800Mi - dindStorage: nullGi -{% endraw %} -{% endhighlight %} - +| Field | Description | Type | Required/Optional | +| -------------- | ---------------------------- |-----------| -------------------------| +| `spec.runtimeEnvironment.name` | The name of the runtime environment to use for the pipeline. |string | Required | +| `spec.runtimeEnvironment.memory` | The memory threshold for the pipeline using Kubernetes notation. |string | Optional | +| `spec.runtimeEnvironment.cpu` | The number of CPUs to use for the pipeline using Kubernetes notation. |string | Optional | +| `spec.runtimeEnvironment.dindStorage` | The DIND storage size using Kubernetes notation. |string | Optional | +| `spec.runtimeEnvironment.requiredAvailableStorage` | The minimum disk space for the pipeline’s build volume in `Gi`.
    When defined, Codefresh assigns either a cached disk with sufficient disk space or a new empty disk at the start of the build.
    When empty, only the space not allocated for caching is available for the build volume.
    See [Set minimum disk space for a pipeline build]({{site.baseurl}}/docs/pipelines/pipelines/#set-minimum-disk-space-for-a-pipeline-build). | string | Optional | -### External resources -The `externalResources` field is an array of objects that hold [external resource information]({{site.baseurl}}/docs/pipelines/pipelines/#external-resources). +### spec.clustersInfo {: .table .table-bordered .table-hover} -| Field name | Parent field | Type | Value | -| -------------- | ---------------------------- |-------------------------| -------------------------| -| `type` | `externalResources` | string | Only `git` is supported | -| `source` | `externalResources` | string | Source folder or file path in Git repo | -| `context` | `externalResources` | string | Name of Git provider to be used | -| `destination` | `externalResources` | string | Target folder or file path to be copied to | -| `isFolder` | `externalResources` | boolean | if true path is a folder, else it is a single file | -| `repo` | `externalResources` | string | git repository name for the trigger. should be in format of `git_repo_owner/git_repo_name` | -| `revision` | `externalResources` | string | branch name or git hash to checkout | +| Field | Description | Type | Required/Optional | +| -------------- | ---------------------------- |-----------| -------------------------| +| `spec.clustersInfo.injectAll` | When set as `true`, the default, injects all clusters integrated with Codefresh into the pipeline build. | boolean | Optional | +| `spec.clustersInfo.clusters` | Applicable only when `injectAll`is set to `false`.
    One or more comma-separated names of clusters to inject during the pipeline build. For example, `aws`, `eks-prod`. | array | Optional | -`Pipeline Spec` -{% highlight yaml %} -{% raw %} -externalResources: - - type: git - source: /src/sample/venonalog.json - context: my-github-integration - destination: codefresh/volume/helm-sample-app/ - isFolder: false - repo: codefresh-contrib/helm-sample-app - revision: master -{% endraw %} -{% endhighlight %} +### spec.variables + +{: .table .table-bordered .table-hover} +| Field | Description | Type | Required/Optional | +| -------------- | ---------------------------- |-----------| -------------------------| +| `spec.variables.key` | The name of the variable. |string | Required | +| `spec.variables.value` | The value of the variable defined by `spec.variables.key` | string | Required | +| `spec.variables.encrypted` | Determines if to encrypt the stored value of the variable. When set to `false`, the default, variable values are not encrypted.
    To encrypt, set to `true`. | boolean | Optional | -### Git triggers -The `triggers` field is an array of objects that hold [Git trigger information]({{site.baseurl}}/docs/pipelines/triggers/git-triggers/). +### spec.specTemplate {: .table .table-bordered .table-hover} -| Field name | Parent field | Type | Value | -| -------------- | ---------------------------- |-------------------------| -------------------------| -| `name` | `triggers` | string | user defined trigger name | -| `type` | `triggers` | string | Always `git` | -| `repo` | `triggers` | string | git repository name for the trigger. should be in format of `git_repo_owner/git_repo_name` | -| `events` | `triggers` | array | All possible values are documented later. The possible values depend on Git provider | -| `pullRequestAllowForkEvents` | `triggers` | boolean | If this trigger is also applicable to Git forks | -| `commentRegex` | `triggers` | string | Only activate trigger if regex expression matches PR comment | -| `branchRegex ` | `triggers` | string | Only activate trigger if regex expression/string matches branch | -| `branchRegexInput ` | `triggers` | string | Defines what type of content is in `branchRegex`. Possible values are `regex`, `multiselect`, `multiselect-exclude` | -| `provider ` | `triggers` | string | Name of provider as found in Git integrations | -| `modifiedFilesGlob ` | `triggers` | string | Only activate trigger if changed files match glob expression | -| `disabled ` | `triggers` | boolean | if true, trigger will never be activated | -| `options ` | `triggers` | array | Choosing [caching behavior]({{site.baseurl}}/docs/pipelines/pipeline-caching/) of this pipeline | -| `noCache ` | `options` | boolean | if true, docker layer cache is disabled | -| `noCfCache ` | `options` | boolean | if true, extra Codefresh caching is disabled | -| `resetVolume ` | `options` | boolean | if true, all files on volume will be deleted before each execution | -| `context ` | `triggers` | string | Name of git context to use | -| `contexts` | `spec` | array | Variable sets imported from [shared configuration]({{site.baseurl}}/docs/pipelines/configuration/shared-configuration/) | -| `variables` | `triggers` | array | Override variables that were defined in the pipeline level | -| `runtimeEnvironment` | `triggers` | array | Override the runtime environment that was defined in the pipeline level | - -The possible values for the `events` array are the following (only those supported by the Git provider can be actually used) - - * `push.heads` - for push commit - * `push.tags` - for push tag event - * `pullrequest` - any pull request event - * `pullrequest.opened` - pull request opened - * `pullrequest.closed` - pull request closed - * `pullrequest.merged` - pull request merged - * `pullrequest.unmerged-closed` - pull request closed (not merged) - * `pullrequest.reopened` - pull request reopened - * `pullrequest.edited` - pull request edited - * `pullrequest.assigned` - pull request assigned - * `pullrequest.unassigned` - pull request unassigned - * `pullrequest.reviewRequested` - pull request review requested - * `pullrequest.reviewRequestRemoved` - pull request review request removed - * `pullrequest.labeled` - pull request labeled - * `pullrequest.unlabeled` - pull request unlabeled - * `pullrequest.synchronize` - pull request synchronized - * `pullrequest.commentAdded` - pull request comment added (restricted) - * `pullrequest.commentAddedUnrestricted` - Any pull request comment will trigger a build. We recommend using only on private repositories. - * `release` - Git release event - -The `variables` and `runtimeEnvironment` fields have exactly the same format as in the parent pipeline fields but values defined in the trigger will take higher priority. - -Full example: +| Field | Description | Type | Required/Optional | +| -------------- | ---------------------------- |-----------| -------------------------| +| `spec.specTemplate.location` | The location of the source YAML. Can be one of the following:{::nomarkdown}
    • YAML_LOCATION.URL: The default, the URL of the YAML with the pipeline definitions.
    • YAML_LOCATION.GIT: The Git repository with the YAML of the pipeline definitions.
    {:/}| string | Required | +| `spec.specTemplate.context` | The name of the Git integration to use from the pipeline integrations configured. | string | +| `spec.specTemplate.url` | Applicable only when `spec.specTemplate.location` is set to `YAML_LOCATION.URL`.
    The URL of the YAML file. | string | Required | +| `spec.specTemplate.repo` | Applicable only when `spec.specTemplate.location` is set to `YAML_LOCATION.GIT`.
    The Git repository where the pipeline definition YAML is stored, as regex, or in the format, `repoOwner/repoName`. | string | Required | +| `spec.specTemplate.path` | Applicable only when `spec.specTemplate.location` is set to `YAML_LOCATION.GIT`.
    The directory within the repository with the YAML file. | string | Required | +| `spec.specTemplate.revision` | Applicable only when `spec.specTemplate.location` is set to `YAML_LOCATION.GIT`.
    The version of the YAML file to retrieve, based on the Git reference such as the branch, tag, or commit hash.| string | Optional | -`Pipeline Spec` -{% highlight yaml %} -{% raw %} -triggers: - - name: guysalton-codefresh/helm-sample-app - type: git - repo: guysalton-codefresh/helm-sample-app - events: - - push.heads - - pullrequest.commentAdded - pullRequestAllowForkEvents: true - commentRegex: /.*/gi - branchRegex: /^((master|develop)$).*/gi - branchRegexInput: regex - modifiedFilesGlob: /project1/** - provider: github - disabled: false - options: - noCache: false - noCfCache: false - resetVolume: false - verified: true - context: guyGithub - contexts: - - artifactory - variables: - - key: key - value: '*****' - encrypted: true - runtimeEnvironment: - name: docker-desktop/cf - cpu: 400m - memory: 800Mi - dindStorage: nullGi -{% endraw %} -{% endhighlight %} -### Cron triggers +### spec.options + +{: .table .table-bordered .table-hover} +| Field | Description | Type | Required/Optional | +| -------------- | ---------------------------- |-----------| -------------------------| +| `spec.options.noCache` | When set to `false`, the default, use the last build's cache.
    To ignore the last build's cache, set to `true`. Selecting this option may slow down your build.
    See [Last build cache]({{site.baseurl}}/docs/kb/articles/disabling-codefresh-caching-mechanisms/). |boolean | Optional | +| `spec.options.noCfCache` | When set to `false`, the default, uses Docker engine cache for build.
    To ignore Docker engine cache for build, set to `true`.
    See [Docker engine cache]({{site.baseurl}}/docs/kb/articles/disabling-codefresh-caching-mechanisms/). |boolean | Optional | +| `spec.options.resetVolume` | When set to `false`, the default, _does not reset_ the pipeline volume.
    To reset the pipeline volume, set to `true`. This is useful for troubleshooting a build that hangs on the first step.
    See [Hangs on restoring data from pre-existing image]({{site.baseurl}}/docs/kb/articles/restoring-data-from-pre-existing-image-hangs-on/). |boolean | Optional | +| `spec.options.enableNotifications` | When set to `false`, the default, only sends status updates to your Git provider.
    To send email and Slack notifications, in addition to status updates, set to `true`.
    See [Slack notifications]({{site.baseurl}}//docs/integrations/notifications/slack-integration/). |boolean | Optional | +| `spec.options.keepPVCsForPendingApproval` | Determines if PVC volumes are retained when the pipeline is waiting for approval. ????? |boolean | Optional | +| `spec.options.pendingApprovalConcurrencyApplied` | Determines if the pipeline build that is pending approval is counted against the number of concurrent builds defined for the pipeline. By default, left empty.
    See [Define concurrency limits]({{site.baseurl}}/docs/pipelines/steps/approval/#define-concurrency-limits) |boolean | Optional | -The `cronTriggers` field is an array of objects that hold [Cron trigger information]({{site.baseurl}}/docs/pipelines/triggers/cron-triggers/). + +### spec.terminationPolicy {: .table .table-bordered .table-hover} -| Field name | Parent field | Type | Value | -| -------------- | ---------------------------- |-------------------------| -------------------------| -| `event` | `cronTriggers` | string | Leave empty. Automatically generated by Codefresh for internal use. | -| `name` | `cronTriggers` | string | The user-defined name for the Cron trigger. | -| `message` | `cronTriggers` | string |The free-text message to be sent as an additional event payload every time the Cron trigger is activated. For example, `Successful ingress tests` | -| `expression` | `cronTriggers` | string |The Cron expression that defines the time and frequency of the Cron trigger.
    For example, `0 3 * * 1-5` triggers the pipeline at _3:00 AM every weekday (Monday to Friday)_. | -| `disabled ` | `cronTriggers` | boolean | Determines if the Cron trigger is enabled for activation.
    By default, set to `false` meaning that it is always enabled.
    To disable the trigger, set to `true`. | -| `gitTriggerId` | `cronTriggers` | string | The ID of the Git trigger to simulate for the pipeline, retrieved from the pipeline for which it is defined.
    To simulate a Git trigger, the pipeline must have at least one Git trigger defined for it.
    See [Git triggers](#git-triggers) in this article. | -| `branch` | `cronTriggers` | string | Valid only when a Git trigger is simulated.
    The branch of the repo retrieved from the Git trigger defined in `gitTriggerId`. | -| `variables` | `cronTriggers` | array | The environment variables to populate for the pipeline when the Cron trigger is activated. See [Variables in pipelines]({{site.baseurl}}/docs/pipelines/variables/). | -| `options` | `cronTriggers` | array | The behavior override options to implement for the current build. By default all overrides are set to `false`, meaning that the build inherits the default behavior set for the pipeline at the account level.
    Can be any of the following:
    {::nomarkdown}
    • noCfCache: When set to true, ignores Docker engine cache for build. See Docker engine cache
    • noCache: When set to true, ignores the last build's cache. Selecting this option may slow down your build.
      See Last build cache.
    • resetVolume: When set to true, resets the pipeline volume, useful for troubleshooting a build that hangs on the first step.
      See Hangs on restoring data from pre-existing image.
    • enableNotifications: When set to true, sends email and Slack notifications, in addition to status updates to your Git provider.
      See Slack notifications.
    {:/}| - - -`Pipeline Spec example for Cron triggers` -{% highlight yaml %} -{% raw %} -... -cronTriggers: - - name: SSO sync - type: cron, - message: "Sync successfull" - expression: "0 0/1 * 1/1 * *" - gitTriggerId: 64905de8589da959de81d31d - branch: main - variables: [] - options: - noCfCache: false - noCache: false - resetVolume: false - enableNotifications: true - disabled: true - event: cron:codefresh:0 0/1 * 1/1 * *:tests:ecef63b9ed20 - verified: true - status: verified - id: 64ddd8b04fdbcc74cc74fe80 -... -{% endraw %} -{% endhighlight %} +| Field | Description | Type | Required/Optional | +| -------------- | ---------------------------- |-----------| -------------------------| +| `spec.terminationPolicy.type` |Can be one of the following: {::nomarkdown}
    • branch: Terminate builds based on spec.terminationPolicy.ignoreBranch, spec.terminationPolicy.ignoreTrigger, and spec.terminationPolicy.branchName options.
    • annotation: Terminate builds based on spec.terminationPolicy.key and spec.terminationPolicy.value options.
    {:/} |string | Optional | +| `spec.terminationPolicy.event` |Determines how builds for the same pipeline are terminated. Can be one of the following:{::nomarkdown}
    • onCreate: Terminates other builds from the same pipeline when a build is created based on the `type`.
    • onTerminate: Terminates child builds initiated from the same pipeline when the parent build is terminated.
    {:/} | string | Optional | +| `spec.terminationPolicy.ignoreBranch` | Applicable only when `spec.terminationPolicy.type` is set to `branch`.
    When set to `false`, the default, once the build is created, terminates previous builds from the same branch.
    To allow previous builds from the same branch to continue running, set to `true`. |boolean | Optional | +| `spec.terminationPolicy.ignoreTrigger` | Applicable only when `spec.terminationPolicy.type` is set to `branch`.
    When set to `false`, the default, once the build is created, terminates all other builds that are running.
    To allow all running builds to continue, set to `true`. |boolean | Optional | +| `spec.terminationPolicy.branchName` | Applicable only when `spec.terminationPolicy.type` is set to `branch`.
    Once the build is created, terminates previous builds from the specific branch that matches the name defined (NIMA: can it be a regex?) . | string | Optional | +| `spec.terminationPolicy.key` | Applicable only when `spec.terminationPolicy.type` is set to `annotation`.
    Terminates all builds that match the annotation defined in `spec.terminationPolicy.value`. | string | Required | +| `spec.terminationPolicy.value` | Applicable only when `spec.terminationPolicy.type` is set to `annotation`.
    The value defined for `spec.terminationPolicy.key`. |boolean | Optional | -## Using Codefresh from within Codefresh -The Codefresh CLI is also packaged as a [Docker image on its own](https://hub.docker.com/r/codefresh/cli/){:target="\_blank"}. This makes it -very easy to use it from within Codefresh in a [freestyle step]({{site.baseurl}}/docs/pipelines/steps/freestyle/). +### spec.externalResources -For example, you can easily call pipeline B from pipeline A -with the following step: +See [External resources]({{site.baseurl}}/docs/pipelines/pipelines/#external-resources). -`codefresh.yml` of pipeline A -{% highlight yaml %} -{% raw %} -version: '1.0' -steps: - myTriggerStep: - title: triggering another pipeline - image: codefresh/cli - commands: - - 'codefresh run -b=${{CF_BRANCH}}' -t - when: - condition: - all: - validateTargetBranch: '"${{CF_PULL_REQUEST_TARGET}}" == "production"' - validatePRAction: '''${{CF_PULL_REQUEST_ACTION}}'' == ''opened''' -{% endraw %} -{% endhighlight %} +{: .table .table-bordered .table-hover} +| Field | Description | Type | Required/Optional | +| -------------- | ---------------------------- |-----------| -------------------------| +| `spec.externalResources.id` The ID of the external |boolean | Optional | +| `spec.externalResources.type` | Only `git` is supported. |string | Optional | +| `spec.externalResources.source` | The source folder or the file path in the Git repo from which to copy/retrieve the external resource. (NIMA: is there a format to use) | string | Required | +| `spec.externalResources.context` | The name of the Git provider to use for the external resource. |string | Optional | +| `spec.externalResources.destination` |The target folder or the file path to which to copy the external resource. |string | Required | +| `spec.externalResources.isFolder` |Defines if the source external resource is stored in a folder or a file.
    If stored in a folder, set to `true`.
    If the resource is a single file, set to `false`, the default. |boolean | Optional | +| `spec.externalResources.repo` | The Git repository name for the external resource, in the format `git_repo_owner/git_repo_name`. | string | Optional | +| `spec.externalResources.revision` | The name of the branch or git hash to check out. | string | Optional | -This step only calls pipeline B when a pull request is opened for the branch named `production`. -Note that when you use the Codefresh CLI in a pipeline step, it is already configured, authenticated, and ready for use. -No additional authentication is required. ## Related articles [Codefresh API documentation](https://g.codefresh.io/api/){:target="\_blank"}