From 800fb99bafb39955444b508383b7e476ce8c8804 Mon Sep 17 00:00:00 2001 From: NimRegev Date: Thu, 12 Sep 2024 12:13:58 +0300 Subject: [PATCH 01/15] Add new topic for pipeline specs Created new topic for pipeline specs in pipeline bucket; added outline structure for topic --- _data/nav.yml | 2 + _docs/pipelines/specifications.md | 66 +++++++++++++++++++++++++++++++ 2 files changed, 68 insertions(+) create mode 100644 _docs/pipelines/specifications.md diff --git a/_data/nav.yml b/_data/nav.yml index 81ba0b8e1..c359c57f7 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/pipelines/specifications.md b/_docs/pipelines/specifications.md new file mode 100644 index 000000000..ed23f626e --- /dev/null +++ b/_docs/pipelines/specifications.md @@ -0,0 +1,66 @@ +--- +title: "Pipeline specifications" +description: "Complete schema for pipelines" +group: pipelines +toc: true +--- + + + + +## .version + +{: .table .table-bordered .table-hover} +| Field | Description | Type | Value | +| -------------- | ---------------------------- |-----------| -------------------------| +| `.version` | The version of the pipeline schema and is always a fixed version. | string | `1.0` | + +## .kind +{: .table .table-bordered .table-hover} +| Field | Description | Type | Value | +| -------------- | ---------------------------- |-----------| -------------------------| +| `.kind` | The kind object type for the schema and is always set to `pipeline`. | string | `pipeline'` | + +## .metadata + +{: .table .table-bordered .table-hover} +| Field | Description | Type | Value | +| -------------- | ---------------------------- |-----------| -------------------------| +| `.kind` | The object type for the schema and is always set to `pipeline`. | string | `pipeline'` | + + + +## .spec + +### .spec fields + + +### spec.triggers + + +### spec.triggers.events + + +### spec.cronTriggers + +### spec.runtimeEnvironment + +### spec.lowMemoryWarningThreshold + + +### spec.requiredAvailableStorage + +### spec.clustersInfo + +### spec.variables + + +### spec.specTemplate + + +### spec.debug.steps + + + + + From fd7a2608c8d1c8d89d982a6bd06eb1cdb5417f98 Mon Sep 17 00:00:00 2001 From: NimRegev Date: Sun, 15 Sep 2024 14:16:26 +0300 Subject: [PATCH 02/15] Update specifications.md Added new table for metadata specs with initial set of descriptions --- _docs/pipelines/specifications.md | 1 - 1 file changed, 1 deletion(-) diff --git a/_docs/pipelines/specifications.md b/_docs/pipelines/specifications.md index ed23f626e..762d01e84 100644 --- a/_docs/pipelines/specifications.md +++ b/_docs/pipelines/specifications.md @@ -7,7 +7,6 @@ toc: true - ## .version {: .table .table-bordered .table-hover} From e6263c847fe474042685e5b88a525532e9f4ffd9 Mon Sep 17 00:00:00 2001 From: NimRegev Date: Sun, 15 Sep 2024 15:42:05 +0300 Subject: [PATCH 03/15] Update nav.yml Fixed alignment error --- _data/nav.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_data/nav.yml b/_data/nav.yml index c359c57f7..650efe5a6 100644 --- a/_data/nav.yml +++ b/_data/nav.yml @@ -389,7 +389,7 @@ - title: Public logs and status badges url: "/build-status" - title: Pipeline specifications - url: "/specifications" + url: "/specifications" - title: Steps in pipelines url: "/steps" sub-pages: From d680f2f3006e55898fad2513312ded9e137586af Mon Sep 17 00:00:00 2001 From: NimRegev Date: Sun, 15 Sep 2024 15:57:34 +0300 Subject: [PATCH 04/15] Update specifications.md --- _docs/pipelines/specifications.md | 36 +++++++++++++++++++++++++------ 1 file changed, 30 insertions(+), 6 deletions(-) diff --git a/_docs/pipelines/specifications.md b/_docs/pipelines/specifications.md index 762d01e84..dd677f088 100644 --- a/_docs/pipelines/specifications.md +++ b/_docs/pipelines/specifications.md @@ -10,22 +10,46 @@ toc: true ## .version {: .table .table-bordered .table-hover} -| Field | Description | Type | Value | +| Field | Description | Type | Required/Optional | | -------------- | ---------------------------- |-----------| -------------------------| -| `.version` | The version of the pipeline schema and is always a fixed version. | string | `1.0` | +| `.version` | The version of the pipeline schema and is always set to `1.0`. | string | ?? | ## .kind {: .table .table-bordered .table-hover} -| Field | Description | Type | Value | +| Field | Description | Type | Required/Optional | | -------------- | ---------------------------- |-----------| -------------------------| -| `.kind` | The kind object type for the schema and is always set to `pipeline`. | string | `pipeline'` | +| `.kind` | The kind object type for the schema and is always set to `pipeline`. | string | ?? | ## .metadata {: .table .table-bordered .table-hover} -| Field | Description | Type | Value | +| Field | Description | Type | Required/Optional | | -------------- | ---------------------------- |-----------| -------------------------| -| `.kind` | The object type for the schema and is always set to `pipeline`. | string | `pipeline'` | +| `metadata.id` | The ID of the pipeline. | string | `????'` | +| `metadata.name` | The full path to the pipeline, including the name of the project to which the pipeline belongs, in the format `project_name/pipeline_name`. | string | Required | +| `metadata.shortName` | The name of the pipeline ???. | string | Optional | +| `metadata.revision` | The ???. | 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. (NIMA: is there a a max limit) | string | Optional | +| `metadata.labels` | The parent object for `metadata.labelKeys` defining the `tags` assigned to the pipeline. ???? | object | Optional | +| `metadata.labelKeys` | The tags ????/ is this the same as `tags`? A list of [access control tags]({{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 the format ????/ | date | Optional | +| `metadata.updated_at` | The date and time at which the pipeline YAML was updated, in the format ????/ | date | Optional | +| `metadata.accountId` | The ID of the account to which the pipeline belongs. ????/ | obejctId | Optional | +| `metadata.originalYamlString` | ?????the full contents of the pipeline editor. Only kept for archival purposes | 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 available as a template when creating a new pipeline.
When set to `true`, the pipeline name is displayed in the Pipeline Template list. | boolean | Optional | +| `metadata.template.isTemplate` | When set to `true`, the pipeline name is displayed in the Pipeline Template list. | boolean | Optional | +| `metadata.template.generatedFrom` |????? When set to `true`, the pipeline name is displayed in the Pipeline Template list. | boolean | Optional | +| `metadata.executionContextId` | ???The ID of the specific execution context to use for the pipeline to makes API calls to the pipeline.
If there are no execution contexts created for the pipeline, the default execution context is used. (NIMA: is this the CF provided one? what are the implications - that it allows all API calls or minimal ones?).
See [Pipeline execution context]({{site.baseurl}}/docs/administration/account-user-management/pipeline-execution-context/). | string | Required???? | + + + + + + + From b4f502a2ea6c1e9ff8b36aae780d96f6f4f9a77b Mon Sep 17 00:00:00 2001 From: NimRegev Date: Tue, 17 Sep 2024 16:44:37 +0300 Subject: [PATCH 05/15] Update specifications.md Started with descriptions for specs --- _docs/pipelines/specifications.md | 41 ++++++++++++++++++++++++++++++- 1 file changed, 40 insertions(+), 1 deletion(-) diff --git a/_docs/pipelines/specifications.md b/_docs/pipelines/specifications.md index dd677f088..1aefbba2a 100644 --- a/_docs/pipelines/specifications.md +++ b/_docs/pipelines/specifications.md @@ -55,7 +55,46 @@ toc: true ## .spec -### .spec fields +{: .table .table-bordered .table-hover} +| Field | Description | Type | Required/Optional | +| -------------- | ---------------------------- |-----------| -------------------------| +| `spec.scopes` | ??? | string | `????'` | +| `spec.scopeSnapshot` | The ID of the pipeline. | string | `????'` | +| `spec.permitRestartFromFailedSteps` | Determines if users can restart a failed pipeline from the failed step, instead of from the beginning of the pipeline.
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` | ??? | string | Optional | +| `spec.triggers` | The list of Git triggers defined for the pipeline. For details, see [`spec.triggers](#spectriggers). | array | ??? | +| `spec.cronTriggers` | The list of Cron or timer-based triggers defined for the pipeline. For details, see [`spec.cronTriggers](#speccrontriggers). | array | `????'` | +| `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.lowMemoryWarningThreshold` | The memory-usage threshold for the pipelines 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` | ??? | string | `????'` | +| `spec.requiredAvailableStorage` | ???The minimum disk space for the pipeline’s build volume.
    When defined, Codefresh assigns either a cached disk with sufficient disk space or a new empty disk at the start of the build. Otherwise, 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). (NIMA: is there a default min and max? is it the same as the UI?) | string | Optional | +| `spec.contexts` | ?? The The ID of the pipeline. | string | `????'` | +| `spec.clustersInfo` | Determines if all (`injectAll`) or specific (`clusters`) Kubernetes cluster contexts are available for the pipeline build.
    See [Select Kubernetes cluster contexts]({{site.baseurl}}/docs/pipelines/pipelines/#select-kubernetes-cluster-contexts). | object | Optional | +| `spec.clustersInfo.injectAll` | When set as `true` (NIMA is this 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 | +| `spec.variablesSchema` | The ID of the pipeline. | string | `????'` | +| `spec.variables` | The ID of the pipeline. | string | `????'` | +| `spec.specTemplate` | The ID of the pipeline. | string | `????'` | +| `spec.steps` | The steps to be executed by the pipeline, as a list of key-values pairs.
    See [Steps in pipelines]({{site.baseurl}}/docs/pipelines/steps/). | object | Required | +| `spec.services` | The ID of the pipeline. | string | `????'` | +| `spec.hooks` | The ID of the pipeline. | string | `????'` | +| `spec.stages` | The ID of the pipeline. | string | `????'` | +| `spec.mode` | The ID of the pipeline. | string | `????'` | +| `spec.fail_fast` | The ID of the pipeline. | string | `????'` | +| `spec.strict_fail_fast` | The ID of the pipeline. | string | `????'` | +| `spec.success_criteria` | The ID of the pipeline. | string | `????'` | +| `spec.options` | The ID of the pipeline. | string | `????'` | +| `spec.concurrency` | The ID of the pipeline. | string | `????'` | +| `spec.triggerConcurrency` | The ID of the pipeline. | string | `????'` | +| `spec.branchConcurrency` | The ID of the pipeline. | string | `????'` | +| `spec.priority` | The ID of the pipeline. | string | `????'` | +| `spec.terminationPolicy` | The ID of the pipeline. | string | `????'` | +| `spec.externalResources` | The ID of the pipeline. | string | `????'` | +| `spec.debug` | The ID of the pipeline. | string | `????'` | +| `spec.serviceAccount` | The ID of the pipeline. | string | `????'` | + + + ### spec.triggers From e671f8ceca2f359d26e98d5786be416e712f40c0 Mon Sep 17 00:00:00 2001 From: Luke Goodfellow <107487942+lukasmagik@users.noreply.github.com> Date: Tue, 17 Sep 2024 13:28:27 -0700 Subject: [PATCH 06/15] updated some fields to the pipeline spec --- _docs/pipelines/specifications.md | 56 +++++++++++-------------------- 1 file changed, 19 insertions(+), 37 deletions(-) diff --git a/_docs/pipelines/specifications.md b/_docs/pipelines/specifications.md index 1aefbba2a..7eb797fe6 100644 --- a/_docs/pipelines/specifications.md +++ b/_docs/pipelines/specifications.md @@ -10,65 +10,61 @@ toc: true ## .version {: .table .table-bordered .table-hover} + | Field | Description | Type | Required/Optional | | -------------- | ---------------------------- |-----------| -------------------------| -| `.version` | The version of the pipeline schema and is always set to `1.0`. | string | ?? | +| `.version` | The version of the pipeline schema and is always set to `'1.0'`. | string | Required | ## .kind + {: .table .table-bordered .table-hover} + | Field | Description | Type | Required/Optional | | -------------- | ---------------------------- |-----------| -------------------------| -| `.kind` | The kind object type for the schema and is always set to `pipeline`. | string | ?? | +| `.kind` | The kind object type for the schema and is always set to `pipeline`. | string | Required | ## .metadata {: .table .table-bordered .table-hover} + | Field | Description | Type | Required/Optional | | -------------- | ---------------------------- |-----------| -------------------------| -| `metadata.id` | The ID of the pipeline. | string | `????'` | +| `metadata.id` | The ID of the pipeline. | string | Optional | | `metadata.name` | The full path to the pipeline, including the name of the project to which the pipeline belongs, in the format `project_name/pipeline_name`. | string | Required | | `metadata.shortName` | The name of the pipeline ???. | string | Optional | | `metadata.revision` | The ???. | 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.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. (NIMA: is there a a max limit) | string | Optional | | `metadata.labels` | The parent object for `metadata.labelKeys` defining the `tags` assigned to the pipeline. ???? | object | Optional | -| `metadata.labelKeys` | The tags ????/ is this the same as `tags`? A list of [access control tags]({{site.baseurl}}/docs/administration/account-user-management/access-control/#marking-pipelines-with-policy-attributes) for this pipeline | | string | Optional | +| `metadata.labelKeys` | The tags ????/ is this the same as `tags`? A list of [access control tags]({{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 the format ????/ | date | Optional | | `metadata.updated_at` | The date and time at which the pipeline YAML was updated, in the format ????/ | date | Optional | | `metadata.accountId` | The ID of the account to which the pipeline belongs. ????/ | obejctId | Optional | | `metadata.originalYamlString` | ?????the full contents of the pipeline editor. Only kept for archival purposes | 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 available as a template when creating a new pipeline.
    When set to `true`, the pipeline name is displayed in the Pipeline Template list. | boolean | Optional | +| `metadata.template` | ????Determines if the pipeline is available as a template when creating a new pipeline.
    When set to `true`, the pipeline name is displayed in the Pipeline Template list. | boolean | Optional | | `metadata.template.isTemplate` | When set to `true`, the pipeline name is displayed in the Pipeline Template list. | boolean | Optional | | `metadata.template.generatedFrom` |????? When set to `true`, the pipeline name is displayed in the Pipeline Template list. | boolean | Optional | -| `metadata.executionContextId` | ???The ID of the specific execution context to use for the pipeline to makes API calls to the pipeline.
    If there are no execution contexts created for the pipeline, the default execution context is used. (NIMA: is this the CF provided one? what are the implications - that it allows all API calls or minimal ones?).
    See [Pipeline execution context]({{site.baseurl}}/docs/administration/account-user-management/pipeline-execution-context/). | string | Required???? | - - - - - - - - - +| `metadata.executionContextId` | ???The ID of the specific execution context to use for the pipeline to makes API calls to the pipeline.
    If there are no execution contexts created for the pipeline, the default execution context is used. (NIMA: is this the CF provided one? what are the implications - that it allows all API calls or minimal ones?).
    See [Pipeline execution context]({{site.baseurl}}/docs/administration/account-user-management/pipeline-execution-context/). | string | Optional | ## .spec {: .table .table-bordered .table-hover} + | Field | Description | Type | Required/Optional | | -------------- | ---------------------------- |-----------| -------------------------| -| `spec.scopes` | ??? | string | `????'` | -| `spec.scopeSnapshot` | The ID of the pipeline. | string | `????'` | +| `spec.scopes` | ??? | string | Optional | +| `spec.scopeSnapshot` | The ID of the pipeline. | string | Optional | | `spec.permitRestartFromFailedSteps` | Determines if users can restart a failed pipeline from the failed step, instead of from the beginning of the pipeline.
    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` | ??? | string | Optional | -| `spec.triggers` | The list of Git triggers defined for the pipeline. For details, see [`spec.triggers](#spectriggers). | array | ??? | -| `spec.cronTriggers` | The list of Cron or timer-based triggers defined for the pipeline. For details, see [`spec.cronTriggers](#speccrontriggers). | array | `????'` | -| `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.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.lowMemoryWarningThreshold` | The memory-usage threshold for the pipelines 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` | ??? | string | `????'` | +| `spec.packId` | SAAS Only (`5cd1746617313f468d669013` for Small, `5cd1746717313f468d669014` for Medium, `5cd1746817313f468d669015` for Large, `5cd1746817313f468d669017` for XL, `5cd1746817313f468d669018` for XXL, `5cd1746817313f468d669020` for 4XL) | string | Required for SAAS
      Optional for Hybrid | | `spec.requiredAvailableStorage` | ???The minimum disk space for the pipeline’s build volume.
      When defined, Codefresh assigns either a cached disk with sufficient disk space or a new empty disk at the start of the build. Otherwise, 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). (NIMA: is there a default min and max? is it the same as the UI?) | string | Optional | -| `spec.contexts` | ?? The The ID of the pipeline. | string | `????'` | +| `spec.contexts` | A list of strings representing the names of that [shared configuration]({{site.baseurl}}/docs/pipelines/configuration/shared-configuration/) to be added to the pipeline | Array of strings | Optional | | `spec.clustersInfo` | Determines if all (`injectAll`) or specific (`clusters`) Kubernetes cluster contexts are available for the pipeline build.
      See [Select Kubernetes cluster contexts]({{site.baseurl}}/docs/pipelines/pipelines/#select-kubernetes-cluster-contexts). | object | Optional | | `spec.clustersInfo.injectAll` | When set as `true` (NIMA is this 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 | @@ -93,36 +89,22 @@ toc: true | `spec.debug` | The ID of the pipeline. | string | `????'` | | `spec.serviceAccount` | The ID of the pipeline. | string | `????'` | - - - - ### spec.triggers - ### spec.triggers.events - ### spec.cronTriggers ### spec.runtimeEnvironment ### spec.lowMemoryWarningThreshold - ### spec.requiredAvailableStorage ### spec.clustersInfo ### spec.variables - ### spec.specTemplate - ### spec.debug.steps - - - - - From 19f2eb92e878d8a77780890bcc5dfe718fbe6f1b Mon Sep 17 00:00:00 2001 From: Luke Goodfellow <107487942+lukasmagik@users.noreply.github.com> Date: Wed, 18 Sep 2024 10:58:28 -0700 Subject: [PATCH 07/15] updating fields for pipeline spec --- _docs/pipelines/specifications.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/_docs/pipelines/specifications.md b/_docs/pipelines/specifications.md index 7eb797fe6..178994758 100644 --- a/_docs/pipelines/specifications.md +++ b/_docs/pipelines/specifications.md @@ -31,22 +31,22 @@ toc: true | -------------- | ---------------------------- |-----------| -------------------------| | `metadata.id` | The ID of the pipeline. | string | Optional | | `metadata.name` | The full path to the pipeline, including the name of the project to which the pipeline belongs, in the format `project_name/pipeline_name`. | string | Required | -| `metadata.shortName` | The name of the pipeline ???. | string | Optional | -| `metadata.revision` | The ???. | integer | Optional | +| `metadata.shortName` | The name of the pipeline without the `project_name/` | string | Optional | +| `metadata.revision` | An auto updated value 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. (NIMA: is there a a max limit) | string | Optional | | `metadata.labels` | The parent object for `metadata.labelKeys` defining the `tags` assigned to the pipeline. ???? | object | Optional | -| `metadata.labelKeys` | The tags ????/ is this the same as `tags`? A list of [access control tags]({{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 the format ????/ | date | Optional | -| `metadata.updated_at` | The date and time at which the pipeline YAML was updated, in the format ????/ | date | Optional | -| `metadata.accountId` | The ID of the account to which the pipeline belongs. ????/ | obejctId | Optional | -| `metadata.originalYamlString` | ?????the full contents of the pipeline editor. Only kept for archival purposes | string | Optional | +| `metadata.labelKeys` | The tags ????/ is this the same as `tags`? A list of [access control tags]({{site.baseurl}}/docs/administration/account-user-management/access-control/#marking-pipelines-with-policy-attributes) for this pipeline (NIMA: Im not seeing this in the DB when adding tags.) | string | Optional | +| `metadata.created_at` | The date and time at which the pipeline was created in the format ????/ (2024-09-18T16:43:16.751+00:00 which is ISO 8601 format) | date | Optional | +| `metadata.updated_at` | The date and time at which the pipeline was updated, in the format ????/ (2024-09-18T16:43:16.751+00:00 which is ISO 8601 format) | date | Optional | +| `metadata.accountId` | The ID of the account to which the pipeline belongs. (ex: `65c5386d7b71f25b3bbb8006`) | obejctId | Optional | +| `metadata.originalYamlString` | The full contents of the pipeline editor (In-line yaml). ???? | 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 available as a template when creating a new pipeline.
      When set to `true`, the pipeline name is displayed in the Pipeline Template list. | boolean | Optional | | `metadata.template.isTemplate` | When set to `true`, the pipeline name is displayed in the Pipeline Template list. | boolean | Optional | -| `metadata.template.generatedFrom` |????? When set to `true`, the pipeline name is displayed in the Pipeline Template list. | boolean | Optional | -| `metadata.executionContextId` | ???The ID of the specific execution context to use for the pipeline to makes API calls to the pipeline.
      If there are no execution contexts created for the pipeline, the default execution context is used. (NIMA: is this the CF provided one? what are the implications - that it allows all API calls or minimal ones?).
      See [Pipeline execution context]({{site.baseurl}}/docs/administration/account-user-management/pipeline-execution-context/). | string | Optional | +| `metadata.template.generatedFrom` | The ID of the template pipeline where the pipeline was created from. ???? | objectId | Optional | +| `metadata.executionContextId` | The name of the specific execution context to use for the pipeline to makes API calls to the pipeline.
      If there are no execution contexts created for the pipeline, the default execution context is used. (NIMA: is this the CF provided one? what are the implications - that it allows all API calls or minimal ones?).
      See [Pipeline execution context]({{site.baseurl}}/docs/administration/account-user-management/pipeline-execution-context/). | string | Optional | ## .spec @@ -54,10 +54,10 @@ toc: true | Field | Description | Type | Required/Optional | | -------------- | ---------------------------- |-----------| -------------------------| -| `spec.scopes` | ??? | string | Optional | -| `spec.scopeSnapshot` | The ID of the pipeline. | string | Optional | +| `spec.scopes` | Custom API Scopes that the Pipeline will use. 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 a failed pipeline from the failed step, instead of from the beginning of the pipeline.
      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` | ??? | string | 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 | From 0ad02e768d7315161e16ca4c34d9b8985259a013 Mon Sep 17 00:00:00 2001 From: NimRegev Date: Thu, 19 Sep 2024 10:29:48 +0300 Subject: [PATCH 08/15] Update specifications.md Added descriptions for spec fields --- _docs/pipelines/specifications.md | 55 +++++++++++++++++-------------- 1 file changed, 31 insertions(+), 24 deletions(-) diff --git a/_docs/pipelines/specifications.md b/_docs/pipelines/specifications.md index 178994758..a6bfd3eee 100644 --- a/_docs/pipelines/specifications.md +++ b/_docs/pipelines/specifications.md @@ -37,9 +37,9 @@ toc: true | `metadata.description` | A meaningful description of the pipeline. (NIMA: is there a a max limit) | string | Optional | | `metadata.labels` | The parent object for `metadata.labelKeys` defining the `tags` assigned to the pipeline. ???? | object | Optional | | `metadata.labelKeys` | The tags ????/ is this the same as `tags`? A list of [access control tags]({{site.baseurl}}/docs/administration/account-user-management/access-control/#marking-pipelines-with-policy-attributes) for this pipeline (NIMA: Im not seeing this in the DB when adding tags.) | string | Optional | -| `metadata.created_at` | The date and time at which the pipeline was created in the format ????/ (2024-09-18T16:43:16.751+00:00 which is ISO 8601 format) | date | Optional | -| `metadata.updated_at` | The date and time at which the pipeline was updated, in the format ????/ (2024-09-18T16:43:16.751+00:00 which is ISO 8601 format) | date | Optional | -| `metadata.accountId` | The ID of the account to which the pipeline belongs. (ex: `65c5386d7b71f25b3bbb8006`) | obejctId | 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-18T16:43:16.751+00:00.| date | Optional | +| `metadata.accountId` | The ID of the account to which the pipeline belongs.
      For example, `65c5386d7b71f25b3bbb8006`.| obejectId | Optional | | `metadata.originalYamlString` | The full contents of the pipeline editor (In-line yaml). ???? | 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 | @@ -62,32 +62,32 @@ toc: true | `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.lowMemoryWarningThreshold` | The memory-usage threshold for the pipelines 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` | SAAS Only (`5cd1746617313f468d669013` for Small, `5cd1746717313f468d669014` for Medium, `5cd1746817313f468d669015` for Large, `5cd1746817313f468d669017` for XL, `5cd1746817313f468d669018` for XXL, `5cd1746817313f468d669020` for 4XL) | string | Required for SAAS
        Optional for Hybrid | +| `spec.packId` | Applicable to SaaS environments. Optional for hybrid environments.
        The package identifer based on the resource size: (NIMA: is it the number they need to specify or the size as in the UI?) (`5cd1746617313f468d669013` for Small, `5cd1746717313f468d669014` for Medium, `5cd1746817313f468d669015` for Large, `5cd1746817313f468d669017` for XL, `5cd1746817313f468d669018` for XXL, `5cd1746817313f468d669020` for 4XL) | string | Required for SaaS | | `spec.requiredAvailableStorage` | ???The minimum disk space for the pipeline’s build volume.
        When defined, Codefresh assigns either a cached disk with sufficient disk space or a new empty disk at the start of the build. Otherwise, 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). (NIMA: is there a default min and max? is it the same as the UI?) | string | Optional | | `spec.contexts` | A list of strings representing the names of that [shared configuration]({{site.baseurl}}/docs/pipelines/configuration/shared-configuration/) to be added to the pipeline | Array of strings | Optional | | `spec.clustersInfo` | Determines if all (`injectAll`) or specific (`clusters`) Kubernetes cluster contexts are available for the pipeline build.
        See [Select Kubernetes cluster contexts]({{site.baseurl}}/docs/pipelines/pipelines/#select-kubernetes-cluster-contexts). | object | Optional | | `spec.clustersInfo.injectAll` | When set as `true` (NIMA is this 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 | -| `spec.variablesSchema` | The ID of the pipeline. | string | `????'` | -| `spec.variables` | The ID of the pipeline. | string | `????'` | -| `spec.specTemplate` | The ID of the pipeline. | string | `????'` | -| `spec.steps` | The steps to be executed by the pipeline, as a list of key-values pairs.
        See [Steps in pipelines]({{site.baseurl}}/docs/pipelines/steps/). | object | Required | -| `spec.services` | The ID of the pipeline. | string | `????'` | -| `spec.hooks` | The ID of the pipeline. | string | `????'` | -| `spec.stages` | The ID of the pipeline. | string | `????'` | -| `spec.mode` | The ID of the pipeline. | string | `????'` | -| `spec.fail_fast` | The ID of the pipeline. | string | `????'` | -| `spec.strict_fail_fast` | The ID of the pipeline. | string | `????'` | -| `spec.success_criteria` | The ID of the pipeline. | string | `????'` | -| `spec.options` | The ID of the pipeline. | string | `????'` | -| `spec.concurrency` | The ID of the pipeline. | string | `????'` | -| `spec.triggerConcurrency` | The ID of the pipeline. | string | `????'` | -| `spec.branchConcurrency` | The ID of the pipeline. | string | `????'` | -| `spec.priority` | The ID of the pipeline. | string | `????'` | -| `spec.terminationPolicy` | The ID of the pipeline. | string | `????'` | -| `spec.externalResources` | The ID of the pipeline. | string | `????'` | -| `spec.debug` | The ID of the pipeline. | string | `????'` | -| `spec.serviceAccount` | The ID of the pipeline. | string | `????'` | +| `spec.variablesSchema` | ??? | string | `????'` | +| `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-values pairs.(NIMA: need to add more info)
        See [Steps in pipelines]({{site.baseurl}}/docs/pipelines/steps/). | object | Required | +| `spec.services` | ??? | object | Optional | +| `spec.hooks` | ?? | object | Optional | +| `spec.stages` | The stages into which to group the pipeline's steps. In the pipeline's build view, each stage is displayed as a separate column.
        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, and 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. {::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.
            • When set at the step-level, returns a Build status of successful when any step in the pipeline with fail_fast=false fails to execute.
          {:/}
          **NOTES**:
          `strict_fail_fast` does not impact the Build status reported for parallel steps with `fail_fast` enabled. Even if a child step fails, the parallel step itself is considered successful. See also [Handling error conditions in a pipeline]({{site.baseurl}}/docs/pipelines/advanced-workflows/#handling-error-conditions-in-a-pipeline). | ??? | Optional | +| `spec.success_criteria` | ????? | string | `????'` | +| `spec.options` | Advanced options controlling pipeline execution behavior.(NIMA: what happens when not defined? takes the default for each option?)
          See [spec.options](#specoptions). | optionsSchema??? | Optional | +| `spec.concurrency` | The maximum number of builds that can run simultaneously for the pipeline, and can range from `0` (the default), to `14`, or `unlimited`.
          A concurrency of `0` freezes execution of the pipeline, switching it to maintenance mode.
          . Useful when your pipeline has only one trigger. | integer | Optional | +| `spec.triggerConcurrency` | The maximum number of concurrent builds than can run _per trigger defined for the pipeline_.
          Can range from `1` (the default), to `15`, or `unlimited`.
          Useful when your pipeline has multiple triggers. | integer | Optional | +| `spec.branchConcurrency` | The maximum number of concurrent builds than can run _per branch defined for the pipeline_.
          Can range from `1` (the default), to `15`, or `unlimited`.
          Useful when your pipeline builds different branches. | integer | Optional | +| `spec.priority` | ??? | string | `????'` | +| `spec.terminationPolicy` | Determines how and when the pipeline build should terminate. See [spec.terminationPolicy](#specterminationpolicy) | ??? | ?? | +| `spec.externalResources` | The external files, such as scripts or other resources available to the pipeline.
          When defined, they are automatically retrieved and available when the pipeline starts execution.
          See [spec.externalResources](#specexternalresources). | array | Optional | +| `spec.debug` | ???? | string | Optional?? | +| `spec.serviceAccount` | ???The service account to use for authentication in ECR integrations for this pipeline. | string | Optional | ### spec.triggers @@ -107,4 +107,11 @@ toc: true ### spec.specTemplate +### spec.options + +### spec.terminationPolicy + +### spec.externalResources +See [External resources]({{site.baseurl}}/docs/pipelines/pipelines/#external-resources). + ### spec.debug.steps From d4faa0b50c8ddbd3774b768ebaec9244948f867b Mon Sep 17 00:00:00 2001 From: Luke Goodfellow <107487942+lukasmagik@users.noreply.github.com> Date: Thu, 19 Sep 2024 11:51:09 -0700 Subject: [PATCH 09/15] added comments --- _docs/pipelines/specifications.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/_docs/pipelines/specifications.md b/_docs/pipelines/specifications.md index a6bfd3eee..9ef2abd3a 100644 --- a/_docs/pipelines/specifications.md +++ b/_docs/pipelines/specifications.md @@ -68,25 +68,25 @@ toc: true | `spec.clustersInfo` | Determines if all (`injectAll`) or specific (`clusters`) Kubernetes cluster contexts are available for the pipeline build.
          See [Select Kubernetes cluster contexts]({{site.baseurl}}/docs/pipelines/pipelines/#select-kubernetes-cluster-contexts). | object | Optional | | `spec.clustersInfo.injectAll` | When set as `true` (NIMA is this 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 | -| `spec.variablesSchema` | ??? | string | `????'` | +| `spec.variablesSchema` | ??? (NIMA: I THINK THIS CAN BE REMOVED) | string | `????'` | | `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-values pairs.(NIMA: need to add more info)
          See [Steps in pipelines]({{site.baseurl}}/docs/pipelines/steps/). | object | Required | -| `spec.services` | ??? | object | Optional | -| `spec.hooks` | ?? | object | Optional | -| `spec.stages` | The stages into which to group the pipeline's steps. In the pipeline's build view, each stage is displayed as a separate column.
          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, and 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. {::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.
              • When set at the step-level, returns a Build status of successful when any step in the pipeline with fail_fast=false fails to execute.
            {:/}
            **NOTES**:
            `strict_fail_fast` does not impact the Build status reported for parallel steps with `fail_fast` enabled. Even if a child step fails, the parallel step itself is considered successful. See also [Handling error conditions in a pipeline]({{site.baseurl}}/docs/pipelines/advanced-workflows/#handling-error-conditions-in-a-pipeline). | ??? | Optional | -| `spec.success_criteria` | ????? | string | `????'` | -| `spec.options` | Advanced options controlling pipeline execution behavior.(NIMA: what happens when not defined? takes the default for each option?)
            See [spec.options](#specoptions). | optionsSchema??? | Optional | +| `spec.steps` | (**NIMA: THIS IS AUTOGENERATED**) The steps to be executed by the pipeline, as a list of key-values pairs.(NIMA: need to add more info )
            See [Steps in pipelines]({{site.baseurl}}/docs/pipelines/steps/). | object | Required | +| `spec.services` | ??? (**NIMA: THIS IS AUTOGENERATED**) | object | Optional | +| `spec.hooks` | ?? (**NIMA: THIS IS AUTOGENERATED**) | object | Optional | +| `spec.stages` | (**NIMA: THIS IS AUTOGENERATED**) The stages into which to group the pipeline's steps. In the pipeline's build view, each stage is displayed as a separate column.
            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` | (**NIMA: THIS IS AUTOGENERATED**) The execution mode for the pipeline, and 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` | (**NIMA: THIS IS AUTOGENERATED**) Determines pipeline execution behavior in case of step failure. {::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` | (**NIMA: THIS IS AUTOGENERATED**) 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.
                • When set at the step-level, returns a Build status of successful when any step in the pipeline with fail_fast=false fails to execute.
              {:/}
              **NOTES**:
              `strict_fail_fast` does not impact the Build status reported for parallel steps with `fail_fast` enabled. Even if a child step fails, the parallel step itself is considered successful. See also [Handling error conditions in a pipeline]({{site.baseurl}}/docs/pipelines/advanced-workflows/#handling-error-conditions-in-a-pipeline). | ??? | Optional | +| `spec.success_criteria` | ????? (**NIMA: NOT SURE WHAT THIS IS - MAYBE AUTOGENERATED**) | string | `????'` | +| `spec.options` | Advanced options controlling pipeline execution behavior.(NIMA: what happens when not defined? takes the default for each option? (**NIMA: WILL TAKE THE DEFAULTS FOR EACH OPTION WHEN NOT DEFINED**))
              See [spec.options](#specoptions). | optionsSchema??? | Optional | | `spec.concurrency` | The maximum number of builds that can run simultaneously for the pipeline, and can range from `0` (the default), to `14`, or `unlimited`.
              A concurrency of `0` freezes execution of the pipeline, switching it to maintenance mode.
              . Useful when your pipeline has only one trigger. | integer | Optional | | `spec.triggerConcurrency` | The maximum number of concurrent builds than can run _per trigger defined for the pipeline_.
              Can range from `1` (the default), to `15`, or `unlimited`.
              Useful when your pipeline has multiple triggers. | integer | Optional | | `spec.branchConcurrency` | The maximum number of concurrent builds than can run _per branch defined for the pipeline_.
              Can range from `1` (the default), to `15`, or `unlimited`.
              Useful when your pipeline builds different branches. | integer | Optional | | `spec.priority` | ??? | string | `????'` | | `spec.terminationPolicy` | Determines how and when the pipeline build should terminate. See [spec.terminationPolicy](#specterminationpolicy) | ??? | ?? | | `spec.externalResources` | The external files, such as scripts or other resources available to the pipeline.
              When defined, they are automatically retrieved and available when the pipeline starts execution.
              See [spec.externalResources](#specexternalresources). | array | Optional | -| `spec.debug` | ???? | string | Optional?? | +| `spec.debug` | ???? (**NIMA: THIS IS AUTOGENERATED WHEN USERS START USING DEBUG IN THE UI - CAN BE DEFINED HERE IF USERS WANTS**) | string | Optional?? | | `spec.serviceAccount` | ???The service account to use for authentication in ECR integrations for this pipeline. | string | Optional | ### spec.triggers @@ -112,6 +112,7 @@ toc: true ### spec.terminationPolicy ### spec.externalResources + See [External resources]({{site.baseurl}}/docs/pipelines/pipelines/#external-resources). ### spec.debug.steps From 7ecb4c71973d904f2bc6ee12a59223ccf59c4be8 Mon Sep 17 00:00:00 2001 From: NimRegev Date: Sun, 22 Sep 2024 17:32:16 +0300 Subject: [PATCH 10/15] Update specifications.md Added descriptions for git, cron, options schema etc --- _docs/pipelines/specifications.md | 110 ++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) diff --git a/_docs/pipelines/specifications.md b/_docs/pipelines/specifications.md index 9ef2abd3a..8de66489d 100644 --- a/_docs/pipelines/specifications.md +++ b/_docs/pipelines/specifications.md @@ -91,26 +91,136 @@ toc: true ### spec.triggers +{: .table .table-bordered .table-hover} +| Field | Description | Type | Required/Optional | +| -------------- | ---------------------------- |-----------| -------------------------| +| `spec.triggers.type` | Always set to `git`. | string | Required | +| `spec.triggers.id` | ???? | ??? | Optional | +| `spec.triggers.createdFromRepositoryMigration` | Determines if the trigger was automatically created when migrating repositories. Deprecated??? | 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` | ?? |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. (NIMA: assum default is False; why or when would you set it to true?) | 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). ??? NIMA: see what the special characters mean int he schema | 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` | ?????| array | Optional | +| `spec.triggers.context` | The name of the Git integration to use????. NIMA what happens when not specified? | 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` | ??? Default 0, min -100, max 100 | integer | Optional | +| `spec.triggers.terminationPolicy` | ??? | integer | Optional | + + + + +Build Termination: Options that determine when a build from the pipeline should terminate: +Once a build is created terminate previous builds from the same branch +Once a build is created terminate previous builds only from a specific branch (name matches a regular expression) +Once a build is created, terminate all other running builds +Once a build is terminated, terminate all child builds initiated from it + + ### spec.triggers.events ### spec.cronTriggers +{: .table .table-bordered .table-hover} +| Field | Description | Type | Required/Optional | +| -------------- | ---------------------------- |-----------| -------------------------| +| `spec.cronTriggers.type` | Always set to `cron`. | string | Required | +| `spec.cronTriggers.id` | ???? | ??? | 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 | + + + + + + + ### spec.runtimeEnvironment +{: .table .table-bordered .table-hover} +| Field | Description | Type | Required/Optional | +| -------------- | ---------------------------- |-----------| -------------------------| +| `spec.runtimeEnvironment.name` | The name of the runtime environment to use for the pipeline. NIMA: does this override the account-level setting? Or must it one of those REs allowed for the pipeline? Should I add it's also based on permissions? |string | Required | +| `spec.runtimeEnvironment.memory` | The memory threshold for the pipeline. memory share using Kubernetes notation NIMA: does this override the account-level setting? Must it one of those in the UI? |string | Optional | +| `spec.runtimeEnvironment.cpu` | The number of CPUs to use for the pipeline. CPU share using Kubernetes notation ??? NIMA: does this override the account-level setting? Or must it one of those in the UI?|string | Optional | +| `spec.runtimeEnvironment.dindStorage` | storage size using Kubernetes notation |string | Optional | ### spec.lowMemoryWarningThreshold +part of param description ### spec.requiredAvailableStorage +??? ### spec.clustersInfo +in parameter description; need to decide if to move here with more details ### spec.variables +{: .table .table-bordered .table-hover} +| Field | Description | Type | Required/Optional | +| -------------- | ---------------------------- |-----------| -------------------------| +| `spec.variables.key` | The name of the variabl. |string | Required | +| `spec.variables.value` | ????| string | Raw value | +| `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 | + ### spec.specTemplate +{: .table .table-bordered .table-hover} +| Field | Description | Type | Required/Optional | +| -------------- | ---------------------------- |-----------| -------------------------| +| `spec.specTemplate.location` | ??? |string | Required | +| `spec.specTemplate.context` | ????| string | | +| `spec.specTemplate.url` | ?????| string | Optional | +| `spec.specTemplate.repo` | ?????| string | Optional | +| `spec.specTemplate.path` | ?????| string | Optional | +| `spec.specTemplate.revision` | ?????| string | Optional | + ### 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. NIMA: what happns then?
              See [Define concurrency limits]({{site.baseurl}}/docs/pipelines/steps/approval/#define-concurrency-limits) |boolean | Optional | + + ### spec.terminationPolicy +{: .table .table-bordered .table-hover} +| Field | Description | Type | Required/Optional | +| -------------- | ---------------------------- |-----------| -------------------------| +| `spec.terminationPolicy.type` |??? |boolean | Optional | +| `spec.terminationPolicy.event` |??? |boolean | Optional | +| `spec.terminationPolicy.ignoreBranch` |??? |boolean | Optional | +| `spec.terminationPolicy.ignoreTrigger` |??? |boolean | Optional | +| `spec.terminationPolicy.branchName` |??? |boolean | Optional | +| `spec.terminationPolicy.key` |??? |boolean | Optional | +| `spec.terminationPolicy.value` |??? |boolean | Optional | + ### spec.externalResources See [External resources]({{site.baseurl}}/docs/pipelines/pipelines/#external-resources). From 78ddc70e98c35fc17b7423601e8443a9d517c8d1 Mon Sep 17 00:00:00 2001 From: NimRegev Date: Mon, 23 Sep 2024 17:51:01 +0300 Subject: [PATCH 11/15] Update specifications.md --- _docs/pipelines/specifications.md | 44 ++++++++++++++++++++++++++----- 1 file changed, 38 insertions(+), 6 deletions(-) diff --git a/_docs/pipelines/specifications.md b/_docs/pipelines/specifications.md index 8de66489d..de0e99e5a 100644 --- a/_docs/pipelines/specifications.md +++ b/_docs/pipelines/specifications.md @@ -118,20 +118,27 @@ toc: true | `spec.triggers.context` | The name of the Git integration to use????. NIMA what happens when not specified? | 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` | ??? Default 0, min -100, max 100 | integer | Optional | -| `spec.triggers.terminationPolicy` | ??? | integer | Optional | +| `spec.triggers.terminationPolicy` | The options that determine when to terminate the build from the pipeline. See [spec.terminationPolicy](#specterminationpolicy). | integer | Optional | + -Build Termination: Options that determine when a build from the pipeline should terminate: -Once a build is created terminate previous builds from the same branch -Once a build is created terminate previous builds only from a specific branch (name matches a regular expression) -Once a build is created, terminate all other running builds -Once a build is terminated, terminate all child builds initiated from it ### spec.triggers.events +Trigger events depend on and are specific to every Git provider. + +See trigger events for: +* [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 {: .table .table-bordered .table-hover} | Field | Description | Type | Required/Optional | @@ -221,8 +228,33 @@ in parameter description; need to decide if to move here with more details | `spec.terminationPolicy.key` |??? |boolean | Optional | | `spec.terminationPolicy.value` |??? |boolean | Optional | + + +Build Termination: +Once a build is created terminate previous builds from the same branch +Once a build is created terminate previous builds only from a specific branch (name matches a regular expression) +Once a build is created, terminate all other running builds +Once a build is terminated, terminate all child builds initiated from it + ### spec.externalResources See [External resources]({{site.baseurl}}/docs/pipelines/pipelines/#external-resources). +{: .table .table-bordered .table-hover} +| Field | Description | Type | Required/Optional | +| -------------- | ---------------------------- |-----------| -------------------------| +| `spec.externalResources.id` |??? |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. (NIMA: is there a format to use) |string | Required | +| `spec.externalResources.isFolder` |??? |Defines if the external resource (source or destination??) 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`. (what is the default??) | Optional | +| `spec.externalResources.repo` | The Git repository name for the trigger, 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 | + + + + + + ### spec.debug.steps From 14b0b027295ec76cc9e5a55572c266994ed004d9 Mon Sep 17 00:00:00 2001 From: NimRegev Date: Tue, 24 Sep 2024 15:38:10 +0300 Subject: [PATCH 12/15] Update specifications.md Added overview and completed more descriptions --- _docs/pipelines/specifications.md | 171 ++++++++++++++++++++---------- 1 file changed, 114 insertions(+), 57 deletions(-) diff --git a/_docs/pipelines/specifications.md b/_docs/pipelines/specifications.md index de0e99e5a..e3150df34 100644 --- a/_docs/pipelines/specifications.md +++ b/_docs/pipelines/specifications.md @@ -1,9 +1,26 @@ --- -title: "Pipeline specifications" -description: "Complete schema for pipelines" +title: "Pipeline YAML configuration" +description: "Understand how to configure the pipeline through YAML file" group: pipelines toc: true --- +Pipeline settings can be configured in different ways, with different scopes and levels of customization: + +* **Account-level settings** + Defined by the Codefresh account administrator in the UI, these settings apply globally across all pipelines within the account. Pipelines inherit these settings by default unless overridden at the pipeline level. + +* **Pipeline-specific settings** + Configurable within the UI for individual pipelines. Some settings are inherited from the account-level configuration, while others are unique to each pipeline. Users with the appropriate permissions can override account-level settings and define pipeline-specific settings. + +* **YAML-based settings** + Defined declaratively using YAML syntax. You can define settings inline through the inline YAML editor (default), or by referencing YAML configuration files stored in a public repository or a Git repository. + + +## Inline YAML/codefresh.yml +includes several default definitions such as steps. +Review Pipeline definitions YAML to get an idea on what you + + @@ -13,7 +30,7 @@ toc: true | Field | Description | Type | Required/Optional | | -------------- | ---------------------------- |-----------| -------------------------| -| `.version` | The version of the pipeline schema and is always set to `'1.0'`. | string | Required | +| `.version` | The version of the pipeline schema and is always set to `'1.0'`. | string | Required | ## .kind @@ -29,24 +46,24 @@ toc: true | Field | Description | Type | Required/Optional | | -------------- | ---------------------------- |-----------| -------------------------| -| `metadata.id` | The ID of the pipeline. | string | Optional | -| `metadata.name` | The full path to the pipeline, including the name of the project to which the pipeline belongs, in the format `project_name/pipeline_name`. | string | Required | -| `metadata.shortName` | The name of the pipeline without the `project_name/` | string | Optional | -| `metadata.revision` | An auto updated value for each update of the pipeline. Default is `0` | integer | Optional | +| `metadata.id` | The ID of the pipeline. (NIMA: where do you get the 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. (NIMA: is there a a max limit) | string | Optional | | `metadata.labels` | The parent object for `metadata.labelKeys` defining the `tags` assigned to the pipeline. ???? | object | Optional | -| `metadata.labelKeys` | The tags ????/ is this the same as `tags`? A list of [access control tags]({{site.baseurl}}/docs/administration/account-user-management/access-control/#marking-pipelines-with-policy-attributes) for this pipeline (NIMA: Im not seeing this in the DB when adding tags.) | string | Optional | +| `metadata.labelKeys` | Ask Dev if its the same as tags The tags ????/ is this the same as `tags`? A list of [access control tags]({{site.baseurl}}/docs/administration/account-user-management/access-control/#marking-pipelines-with-policy-attributes) for this pipeline (NIMA: Im not seeing this in the DB when adding tags.) | 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-18T16:43:16.751+00:00.| date | Optional | -| `metadata.accountId` | The ID of the account to which the pipeline belongs.
              For example, `65c5386d7b71f25b3bbb8006`.| obejectId | Optional | -| `metadata.originalYamlString` | The full contents of the pipeline editor (In-line yaml). ???? | string | Optional | +| `metadata.updated_at` | The date and time at which the pipeline was last updated, in ISO 8601 format.
              For example, `2024-10-18T16:43:16.751+00:00`.| date | Optional | +| `metadata.accountId` | The ID of the account to which the pipeline belongs.
              For example, `65c5386d7b71f25b3bbb8006`. (NIMA: where do you get the account ID?)| 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 available as a template when creating a new pipeline.
              When set to `true`, the pipeline name is displayed in the Pipeline Template list. | boolean | Optional | +| `metadata.template` | Determines if the pipeline is designated as 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 where the pipeline was created from. ???? | objectId | Optional | -| `metadata.executionContextId` | The name of the specific execution context to use for the pipeline to makes API calls to the pipeline.
              If there are no execution contexts created for the pipeline, the default execution context is used. (NIMA: is this the CF provided one? what are the implications - that it allows all API calls or minimal ones?).
              See [Pipeline execution context]({{site.baseurl}}/docs/administration/account-user-management/pipeline-execution-context/). | string | 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 @@ -55,36 +72,34 @@ toc: true | Field | Description | Type | Required/Optional | | -------------- | ---------------------------- |-----------| -------------------------| | `spec.scopes` | Custom API Scopes that the Pipeline will use. 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 a failed pipeline from the failed step, instead of from the beginning of the pipeline.
              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.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 use the default setting which is to inherit the account-level setting. (NIMA: to verify)
              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.lowMemoryWarningThreshold` | The memory-usage threshold for the pipelines 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` | Applicable to SaaS environments. Optional for hybrid environments.
                The package identifer based on the resource size: (NIMA: is it the number they need to specify or the size as in the UI?) (`5cd1746617313f468d669013` for Small, `5cd1746717313f468d669014` for Medium, `5cd1746817313f468d669015` for Large, `5cd1746817313f468d669017` for XL, `5cd1746817313f468d669018` for XXL, `5cd1746817313f468d669020` for 4XL) | string | Required for SaaS | -| `spec.requiredAvailableStorage` | ???The minimum disk space for the pipeline’s build volume.
                When defined, Codefresh assigns either a cached disk with sufficient disk space or a new empty disk at the start of the build. Otherwise, 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). (NIMA: is there a default min and max? is it the same as the UI?) | string | Optional | -| `spec.contexts` | A list of strings representing the names of that [shared configuration]({{site.baseurl}}/docs/pipelines/configuration/shared-configuration/) to be added to the pipeline | Array of strings | Optional | -| `spec.clustersInfo` | Determines if all (`injectAll`) or specific (`clusters`) Kubernetes cluster contexts are available for the pipeline build.
                See [Select Kubernetes cluster contexts]({{site.baseurl}}/docs/pipelines/pipelines/#select-kubernetes-cluster-contexts). | object | Optional | -| `spec.clustersInfo.injectAll` | When set as `true` (NIMA is this 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 | +| `spec.packId` | Required for SaaS environments. Optional for hybrid environments.
                The package identifer 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.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). (NIMA: is there a default min and max? is it the same as the UI? from 1Gi to 8 gi??) | string | Optional | +| `spec.contexts` | ???A list of strings representing the names of the [shared configurations]({{site.baseurl}}/docs/pipelines/configuration/shared-configuration/) to be added to the pipeline | Array | Optional | +| `spec.clustersInfo` | Determines if all or specific Kubernetes clusters are available for the pipeline build based on the account-level setting. (NIMA: how can the user know what the account level setting is? Do they have to go manually to the Settings to see if there are restrictions?
                See [Select Kubernetes cluster contexts]({{site.baseurl}}/docs/pipelines/pipelines/#select-kubernetes-cluster-contexts). | object | Optional | | `spec.variablesSchema` | ??? (NIMA: I THINK THIS CAN BE REMOVED) | string | `????'` | | `spec.variables` | The variables defined in the pipeline. See [spec.variables](#specvariables). | array | Optional | | `spec.specTemplate` | ???? . See [spec.specTemplate](#specspectemplate). | object | Optional | -| `spec.steps` | (**NIMA: THIS IS AUTOGENERATED**) The steps to be executed by the pipeline, as a list of key-values pairs.(NIMA: need to add more info )
                See [Steps in pipelines]({{site.baseurl}}/docs/pipelines/steps/). | object | Required | +| `spec.steps` | The steps to be executed by the pipeline, as a list of key-values pairs.(NIMA: need to add more info )
                See [Steps in pipelines]({{site.baseurl}}/docs/pipelines/steps/). | object | Required | | `spec.services` | ??? (**NIMA: THIS IS AUTOGENERATED**) | object | Optional | | `spec.hooks` | ?? (**NIMA: THIS IS AUTOGENERATED**) | object | Optional | -| `spec.stages` | (**NIMA: THIS IS AUTOGENERATED**) The stages into which to group the pipeline's steps. In the pipeline's build view, each stage is displayed as a separate column.
                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` | (**NIMA: THIS IS AUTOGENERATED**) The execution mode for the pipeline, and 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` | (**NIMA: THIS IS AUTOGENERATED**) Determines pipeline execution behavior in case of step failure. {::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` | (**NIMA: THIS IS AUTOGENERATED**) 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.
                    • When set at the step-level, returns a Build status of successful when any step in the pipeline with fail_fast=false fails to execute.
                  {:/}
                  **NOTES**:
                  `strict_fail_fast` does not impact the Build status reported for parallel steps with `fail_fast` enabled. Even if a child step fails, the parallel step itself is considered successful. See also [Handling error conditions in a pipeline]({{site.baseurl}}/docs/pipelines/advanced-workflows/#handling-error-conditions-in-a-pipeline). | ??? | Optional | -| `spec.success_criteria` | ????? (**NIMA: NOT SURE WHAT THIS IS - MAYBE AUTOGENERATED**) | string | `????'` | -| `spec.options` | Advanced options controlling pipeline execution behavior.(NIMA: what happens when not defined? takes the default for each option? (**NIMA: WILL TAKE THE DEFAULTS FOR EACH OPTION WHEN NOT DEFINED**))
                  See [spec.options](#specoptions). | optionsSchema??? | 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.
                      • When set at the step-level, returns a Build status of successful when any step in the pipeline with fail_fast=false fails to execute.
                    {:/}
                    **NOTES**:
                    `strict_fail_fast` does not impact the Build status reported for parallel steps with `fail_fast` enabled. Even if a child step fails, the parallel step itself is considered successful. See also [Handling error conditions in a pipeline]({{site.baseurl}}/docs/pipelines/advanced-workflows/#handling-error-conditions-in-a-pipeline). | ??? | Optional | +| `spec.success_criteria` | ????? | string | `????'` | +| `spec.options` | Advanced options controlling pipeline execution behavior. Leave empty to use the default settings.
                    See [spec.options](#specoptions). | optionsSchema | Optional | | `spec.concurrency` | The maximum number of builds that can run simultaneously for the pipeline, and can range from `0` (the default), to `14`, or `unlimited`.
                    A concurrency of `0` freezes execution of the pipeline, switching it to maintenance mode.
                    . Useful when your pipeline has only one trigger. | integer | Optional | | `spec.triggerConcurrency` | The maximum number of concurrent builds than can run _per trigger defined for the pipeline_.
                    Can range from `1` (the default), to `15`, or `unlimited`.
                    Useful when your pipeline has multiple triggers. | integer | Optional | | `spec.branchConcurrency` | The maximum number of concurrent builds than can run _per branch defined for the pipeline_.
                    Can range from `1` (the default), to `15`, or `unlimited`.
                    Useful when your pipeline builds different branches. | integer | Optional | | `spec.priority` | ??? | string | `????'` | -| `spec.terminationPolicy` | Determines how and when the pipeline build should terminate. See [spec.terminationPolicy](#specterminationpolicy) | ??? | ?? | +| `spec.terminationPolicy` | Determines how and when the pipeline builds should terminate. See [spec.terminationPolicy](#specterminationpolicy) | terminationSchema | Optional | | `spec.externalResources` | The external files, such as scripts or other resources available to the pipeline.
                    When defined, they are automatically retrieved and available when the pipeline starts execution.
                    See [spec.externalResources](#specexternalresources). | array | Optional | | `spec.debug` | ???? (**NIMA: THIS IS AUTOGENERATED WHEN USERS START USING DEBUG IN THE UI - CAN BE DEFINED HERE IF USERS WANTS**) | string | Optional?? | | `spec.serviceAccount` | ???The service account to use for authentication in ECR integrations for this pipeline. | string | Optional | @@ -131,6 +146,54 @@ toc: true Trigger events depend on and are specific to every Git provider. See trigger events for: + +{: .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 | + + + + + * [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) @@ -140,6 +203,7 @@ See trigger events for: ### spec.cronTriggers + {: .table .table-bordered .table-hover} | Field | Description | Type | Required/Optional | | -------------- | ---------------------------- |-----------| -------------------------| @@ -172,14 +236,13 @@ See trigger events for: | `spec.runtimeEnvironment.cpu` | The number of CPUs to use for the pipeline. CPU share using Kubernetes notation ??? NIMA: does this override the account-level setting? Or must it one of those in the UI?|string | Optional | | `spec.runtimeEnvironment.dindStorage` | storage size using Kubernetes notation |string | Optional | -### spec.lowMemoryWarningThreshold -part of param description -### spec.requiredAvailableStorage -??? ### spec.clustersInfo -in parameter description; need to decide if to move here with more details + +| `spec.clustersInfo.injectAll` | When set as `true` (NIMA is this 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 | + ### spec.variables @@ -193,14 +256,14 @@ in parameter description; need to decide if to move here with more details ### spec.specTemplate {: .table .table-bordered .table-hover} -| Field | Description | Type | Required/Optional | -| -------------- | ---------------------------- |-----------| -------------------------| -| `spec.specTemplate.location` | ??? |string | Required | -| `spec.specTemplate.context` | ????| string | | -| `spec.specTemplate.url` | ?????| string | Optional | -| `spec.specTemplate.repo` | ?????| string | Optional | -| `spec.specTemplate.path` | ?????| string | Optional | -| `spec.specTemplate.revision` | ?????| string | Optional | +| 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` | ???? | 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 | ### spec.options @@ -209,7 +272,7 @@ in parameter description; need to decide if to move here with more details | -------------- | ---------------------------- |-----------| -------------------------| | `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.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. NIMA: what happns then?
                      See [Define concurrency limits]({{site.baseurl}}/docs/pipelines/steps/approval/#define-concurrency-limits) |boolean | Optional | @@ -220,20 +283,14 @@ in parameter description; need to decide if to move here with more details {: .table .table-bordered .table-hover} | Field | Description | Type | Required/Optional | | -------------- | ---------------------------- |-----------| -------------------------| -| `spec.terminationPolicy.type` |??? |boolean | Optional | -| `spec.terminationPolicy.event` |??? |boolean | Optional | -| `spec.terminationPolicy.ignoreBranch` |??? |boolean | Optional | -| `spec.terminationPolicy.ignoreTrigger` |??? |boolean | Optional | -| `spec.terminationPolicy.branchName` |??? |boolean | Optional | -| `spec.terminationPolicy.key` |??? |boolean | Optional | -| `spec.terminationPolicy.value` |??? |boolean | 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. ??? | string | Required | +| `spec.terminationPolicy.value` | ??? Applicable only when `spec.terminationPolicy.type` is set to `annotation`.
                      |boolean | Optional | -Build Termination: -Once a build is created terminate previous builds from the same branch -Once a build is created terminate previous builds only from a specific branch (name matches a regular expression) -Once a build is created, terminate all other running builds Once a build is terminated, terminate all child builds initiated from it ### spec.externalResources From 086a664ccc30278250de6a6d9a356cfd2a8f2cc4 Mon Sep 17 00:00:00 2001 From: NimRegev Date: Sun, 29 Sep 2024 11:20:16 +0300 Subject: [PATCH 13/15] Update specifications.md Content edits --- _docs/pipelines/specifications.md | 59 ++++++++++++++++++++----------- 1 file changed, 38 insertions(+), 21 deletions(-) diff --git a/_docs/pipelines/specifications.md b/_docs/pipelines/specifications.md index e3150df34..0de06fdda 100644 --- a/_docs/pipelines/specifications.md +++ b/_docs/pipelines/specifications.md @@ -4,24 +4,41 @@ description: "Understand how to configure the pipeline through YAML file" group: pipelines toc: true --- -Pipeline settings can be configured in different ways, with different scopes and levels of customization: +Pipeline settings can be configured in different ways, with different levels of customization: * **Account-level settings** - Defined by the Codefresh account administrator in the UI, these settings apply globally across all pipelines within the account. Pipelines inherit these settings by default unless overridden at the pipeline level. + Defined by the Codefresh account administrator in the UI, these settings apply globally to all pipelines within the account. Pipelines inherit these settings by default unless overridden at the pipeline level. + See [Account-level settings for pipelines]({{site.baseurl}}/docs/pipelines/configuration/pipeline-settings/). * **Pipeline-specific settings** - Configurable within the UI for individual pipelines. Some settings are inherited from the account-level configuration, while others are unique to each pipeline. Users with the appropriate permissions can override account-level settings and define pipeline-specific settings. + Configurable within the UI for individual pipelines. Some settings are inherited from the account-level configuration, while others are unique to each pipeline. Users with the appropriate permissions can override account-level settings and define pipeline-specific settings. + See [Pipeline settings]({{site.baseurl}}/docs/pipelines/pipelines/#pipeline-settings/). * **YAML-based settings** - Defined declaratively using YAML syntax. You can define settings inline through the inline YAML editor (default), or by referencing YAML configuration files stored in a public repository or a Git repository. + Defined declaratively using YAML syntax. You can define settings inline through the inline YAML editor (default), or by referencing YAML configuration files stored in a public repository or a Git repository. + See the rest of this article for details. +Each level has a different [priority](#priority-for-pipeline-settings) when the same setting is defined at more than one level. -## Inline YAML/codefresh.yml -includes several default definitions such as steps. -Review Pipeline definitions YAML to get an idea on what you +## codefresh.yml pipeline definitions +This YAML is displayed in the Pipelines > Workflow tab when you create a pipeline as the Inline YAML, and includes several default definitions such as steps. +[Pipeline definitions YAML]({{site.baseurl}}/docs/pipelines/what-is-the-codefresh-yaml/) walks you through the syntax in `codefresh.yml`, with examples, validation, execution flow, and other key information for defining Codefresh pipelines using YAML. +## Priority for pipeline settings + +Pipeline settings can be defined at different levels, and not all settings are available at every level. +It's important to understand the order of priority when settings overlap. + +The priority (override behavior) is as follows, from highest to lowest: + +1. YAML file definitions + Regardless of whether the YAML file is inline, in a repository, or public, YAML definitions take the highest priority, overriding both pipeline-specific and account-level settings. +1. Pipeline-specific settings + If no YAML definitions exist, the settings for the individual pipeline take precedence over the corresponding account-level settings, unless they are explicitly set to inherit from the account-level. +1. Account-level settings + Account-level settings apply only when the corresponding settings are not defined either in a YAML file or at the pipeline level. ## .version @@ -30,7 +47,7 @@ Review Pipeline definitions YAML to get an idea on what you | Field | Description | Type | Required/Optional | | -------------- | ---------------------------- |-----------| -------------------------| -| `.version` | The version of the pipeline schema and is always set to `'1.0'`. | string | Required | +| `.version` | The version of the pipeline schema, always set to `'1.0'`. | string | Required | ## .kind @@ -46,21 +63,21 @@ Review Pipeline definitions YAML to get an idea on what you | Field | Description | Type | Required/Optional | | -------------- | ---------------------------- |-----------| -------------------------| -| `metadata.id` | The ID of the pipeline. (NIMA: where do you get the pipeline ID?) | string | Optional | +| `metadata.id` | The ID of the pipeline. The ID is generated when the pipeline is created. (NIMA: where do you get the 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. (NIMA: is there a a max limit) | string | Optional | | `metadata.labels` | The parent object for `metadata.labelKeys` defining the `tags` assigned to the pipeline. ???? | object | Optional | -| `metadata.labelKeys` | Ask Dev if its the same as tags The tags ????/ is this the same as `tags`? A list of [access control tags]({{site.baseurl}}/docs/administration/account-user-management/access-control/#marking-pipelines-with-policy-attributes) for this pipeline (NIMA: Im not seeing this in the DB when adding tags.) | string | 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 (NIMA: Im not seeing this in the DB when adding tags.) | 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-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`. (NIMA: where do you get the account ID?)| 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 as and available as a template when creating a new pipeline. | | | +| `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 | @@ -71,21 +88,21 @@ Review Pipeline definitions YAML to get an idea on what you | Field | Description | Type | Required/Optional | | -------------- | ---------------------------- |-----------| -------------------------| -| `spec.scopes` | Custom API Scopes that the Pipeline will use. Configuring custom scopes will override the account-level defaults for this pipeline. ???? | array of strings | Optional | +| `spec.scopes` | ??? Need to verify what this isThe 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 use the default setting which is to inherit the account-level setting. (NIMA: to verify)
                      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.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. (NIMA: to verify)
                      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.lowMemoryWarningThreshold` | The memory-usage threshold for the pipelines 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.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 identifer 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.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). (NIMA: is there a default min and max? is it the same as the UI? from 1Gi to 8 gi??) | string | Optional | -| `spec.contexts` | ???A list of strings representing the names of the [shared configurations]({{site.baseurl}}/docs/pipelines/configuration/shared-configuration/) to be added to the pipeline | Array | Optional | -| `spec.clustersInfo` | Determines if all or specific Kubernetes clusters are available for the pipeline build based on the account-level setting. (NIMA: how can the user know what the account level setting is? Do they have to go manually to the Settings to see if there are restrictions?
                          See [Select Kubernetes cluster contexts]({{site.baseurl}}/docs/pipelines/pipelines/#select-kubernetes-cluster-contexts). | object | Optional | +| `spec.requiredAvailableStorage` | The minimum disk space for the pipeline’s build volume in `Gi` (NIMA: verify units).
                          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). (NIMA: is there a default min and max? is it the same as the UI? from 1Gi to 8 gi??) | string | Optional | +| `spec.contexts` | (NIMA: is shared config different from shared secrets?)Single or multiple comma-separated shared configuration contexts to be added 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. (NIMA: how can the user know what the account level setting is? Do they have to go manually to the Settings to see if there are restrictions?
                          See [Select Kubernetes cluster contexts]({{site.baseurl}}/docs/pipelines/pipelines/#select-kubernetes-cluster-contexts). | object | Optional | | `spec.variablesSchema` | ??? (NIMA: I THINK THIS CAN BE REMOVED) | string | `????'` | | `spec.variables` | The variables defined in the pipeline. See [spec.variables](#specvariables). | array | Optional | -| `spec.specTemplate` | ???? . See [spec.specTemplate](#specspectemplate). | object | Optional | +| `spec.specTemplate` | (NIMA: what is ) . See [spec.specTemplate](#specspectemplate). | object | Optional | | `spec.steps` | The steps to be executed by the pipeline, as a list of key-values pairs.(NIMA: need to add more info )
                          See [Steps in pipelines]({{site.baseurl}}/docs/pipelines/steps/). | object | Required | | `spec.services` | ??? (**NIMA: THIS IS AUTOGENERATED**) | object | Optional | | `spec.hooks` | ?? (**NIMA: THIS IS AUTOGENERATED**) | object | Optional | @@ -101,8 +118,8 @@ Review Pipeline definitions YAML to get an idea on what you | `spec.priority` | ??? | string | `????'` | | `spec.terminationPolicy` | Determines how and when the pipeline builds should terminate. See [spec.terminationPolicy](#specterminationpolicy) | terminationSchema | Optional | | `spec.externalResources` | The external files, such as scripts or other resources available to the pipeline.
                          When defined, they are automatically retrieved and available when the pipeline starts execution.
                          See [spec.externalResources](#specexternalresources). | array | Optional | -| `spec.debug` | ???? (**NIMA: THIS IS AUTOGENERATED WHEN USERS START USING DEBUG IN THE UI - CAN BE DEFINED HERE IF USERS WANTS**) | string | Optional?? | -| `spec.serviceAccount` | ???The service account to use for authentication in ECR integrations for this pipeline. | string | Optional | +| `spec.debug` | (NIMA: to ask Ziv what the fields mean)) | string | Optional?? | +| `spec.serviceAccount` | (NIMA: to verify )The service account to use for authentication in ECR integrations for this pipeline. | string | Optional | ### spec.triggers From 20a9febf8008d17a6a1d9ffa5610a9dcdcc74ad2 Mon Sep 17 00:00:00 2001 From: NimRegev Date: Tue, 8 Oct 2024 11:04:56 +0300 Subject: [PATCH 14/15] Update specifications.md --- _docs/pipelines/specifications.md | 45 +++++++++++++++++++++++++++++-- 1 file changed, 43 insertions(+), 2 deletions(-) diff --git a/_docs/pipelines/specifications.md b/_docs/pipelines/specifications.md index 0de06fdda..90d30ca27 100644 --- a/_docs/pipelines/specifications.md +++ b/_docs/pipelines/specifications.md @@ -85,10 +85,9 @@ The priority (override behavior) is as follows, from highest to lowest: ## .spec {: .table .table-bordered .table-hover} - | Field | Description | Type | Required/Optional | | -------------- | ---------------------------- |-----------| -------------------------| -| `spec.scopes` | ??? Need to verify what this isThe 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.scopes` | ??? Need to verify what this is.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. (NIMA: to verify)
                          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 | @@ -121,6 +120,42 @@ The priority (override behavior) is as follows, from highest to lowest: | `spec.debug` | (NIMA: to ask Ziv what the fields mean)) | string | Optional?? | | `spec.serviceAccount` | (NIMA: to verify )The service account to use for authentication in ECR integrations for this pipeline. | string | Optional | + + + +{: .table .table-bordered .table-hover} +| Field | Description | Type | Required/Optional | +| -------------- | ---------------------------- |-----------| -------------------------| +| `spec.scopes` | ??? Need to verify what this is. 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. (NIMA: to verify)
                          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.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.requiredAvailableStorage` | The minimum disk space for the pipeline’s build volume in `Gi` (NIMA: verify units).
                          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). (NIMA: is there a default min and max? is it the same as the UI? from 1Gi to 8 Gi??) | string | Optional | +| `spec.contexts` | (NIMA: is shared config different from shared secrets?) Single or multiple comma-separated shared configuration contexts to be added 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. (NIMA: how can the user know what the account-level setting is? Do they have to go manually to the Settings to see if there are restrictions?)
                          See [Select Kubernetes cluster contexts]({{site.baseurl}}/docs/pipelines/pipelines/#select-kubernetes-cluster-contexts). | object | Optional | +| `spec.variablesSchema` | ??? (NIMA: I THINK THIS CAN BE REMOVED) | string | `????` | +| `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. (NIMA: need to add more info)
                          See [Steps in pipelines]({{site.baseurl}}/docs/pipelines/steps/). | object | Required | +| `spec.services` | ??? (**NIMA: THIS IS AUTOGENERATED**) | object | Optional | +| `spec.hooks` | ??? (**NIMA: THIS IS AUTOGENERATED**) | 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.
                            • When set at + + + + + + + + ### spec.triggers {: .table .table-bordered .table-hover} @@ -245,6 +280,7 @@ See trigger events for: ### spec.runtimeEnvironment + {: .table .table-bordered .table-hover} | Field | Description | Type | Required/Optional | | -------------- | ---------------------------- |-----------| -------------------------| @@ -257,6 +293,9 @@ See trigger events for: ### spec.clustersInfo +{: .table .table-bordered .table-hover} +| Field | Description | Type | Required/Optional | +| -------------- | ---------------------------- |-----------| -------------------------| | `spec.clustersInfo.injectAll` | When set as `true` (NIMA is this 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 | @@ -270,6 +309,7 @@ See trigger events for: | `spec.variables.value` | ????| string | Raw value | | `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 | + ### spec.specTemplate {: .table .table-bordered .table-hover} @@ -282,6 +322,7 @@ See trigger events for: | `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 | + ### spec.options {: .table .table-bordered .table-hover} From da64d32e7b667ec58b40810fa5c6849b00a3c169 Mon Sep 17 00:00:00 2001 From: NimRegev Date: Tue, 8 Oct 2024 11:48:55 +0300 Subject: [PATCH 15/15] Update specifications.md --- _docs/pipelines/specifications.md | 40 +------------------------------ 1 file changed, 1 insertion(+), 39 deletions(-) diff --git a/_docs/pipelines/specifications.md b/_docs/pipelines/specifications.md index 90d30ca27..3dfa36f54 100644 --- a/_docs/pipelines/specifications.md +++ b/_docs/pipelines/specifications.md @@ -84,44 +84,6 @@ The priority (override behavior) is as follows, from highest to lowest: ## .spec -{: .table .table-bordered .table-hover} -| Field | Description | Type | Required/Optional | -| -------------- | ---------------------------- |-----------| -------------------------| -| `spec.scopes` | ??? Need to verify what this is.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. (NIMA: to verify)
                              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.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 identifer 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.requiredAvailableStorage` | The minimum disk space for the pipeline’s build volume in `Gi` (NIMA: verify units).
                                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). (NIMA: is there a default min and max? is it the same as the UI? from 1Gi to 8 gi??) | string | Optional | -| `spec.contexts` | (NIMA: is shared config different from shared secrets?)Single or multiple comma-separated shared configuration contexts to be added 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. (NIMA: how can the user know what the account level setting is? Do they have to go manually to the Settings to see if there are restrictions?
                                See [Select Kubernetes cluster contexts]({{site.baseurl}}/docs/pipelines/pipelines/#select-kubernetes-cluster-contexts). | object | Optional | -| `spec.variablesSchema` | ??? (NIMA: I THINK THIS CAN BE REMOVED) | string | `????'` | -| `spec.variables` | The variables defined in the pipeline. See [spec.variables](#specvariables). | array | Optional | -| `spec.specTemplate` | (NIMA: what is ) . See [spec.specTemplate](#specspectemplate). | object | Optional | -| `spec.steps` | The steps to be executed by the pipeline, as a list of key-values pairs.(NIMA: need to add more info )
                                See [Steps in pipelines]({{site.baseurl}}/docs/pipelines/steps/). | object | Required | -| `spec.services` | ??? (**NIMA: THIS IS AUTOGENERATED**) | object | Optional | -| `spec.hooks` | ?? (**NIMA: THIS IS AUTOGENERATED**) | 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.
                                    • When set at the step-level, returns a Build status of successful when any step in the pipeline with fail_fast=false fails to execute.
                                  {:/}
                                  **NOTES**:
                                  `strict_fail_fast` does not impact the Build status reported for parallel steps with `fail_fast` enabled. Even if a child step fails, the parallel step itself is considered successful. See also [Handling error conditions in a pipeline]({{site.baseurl}}/docs/pipelines/advanced-workflows/#handling-error-conditions-in-a-pipeline). | ??? | Optional | -| `spec.success_criteria` | ????? | string | `????'` | -| `spec.options` | Advanced options controlling pipeline execution behavior. Leave empty to use the default settings.
                                  See [spec.options](#specoptions). | optionsSchema | Optional | -| `spec.concurrency` | The maximum number of builds that can run simultaneously for the pipeline, and can range from `0` (the default), to `14`, or `unlimited`.
                                  A concurrency of `0` freezes execution of the pipeline, switching it to maintenance mode.
                                  . Useful when your pipeline has only one trigger. | integer | Optional | -| `spec.triggerConcurrency` | The maximum number of concurrent builds than can run _per trigger defined for the pipeline_.
                                  Can range from `1` (the default), to `15`, or `unlimited`.
                                  Useful when your pipeline has multiple triggers. | integer | Optional | -| `spec.branchConcurrency` | The maximum number of concurrent builds than can run _per branch defined for the pipeline_.
                                  Can range from `1` (the default), to `15`, or `unlimited`.
                                  Useful when your pipeline builds different branches. | integer | Optional | -| `spec.priority` | ??? | string | `????'` | -| `spec.terminationPolicy` | Determines how and when the pipeline builds should terminate. See [spec.terminationPolicy](#specterminationpolicy) | terminationSchema | Optional | -| `spec.externalResources` | The external files, such as scripts or other resources available to the pipeline.
                                  When defined, they are automatically retrieved and available when the pipeline starts execution.
                                  See [spec.externalResources](#specexternalresources). | array | Optional | -| `spec.debug` | (NIMA: to ask Ziv what the fields mean)) | string | Optional?? | -| `spec.serviceAccount` | (NIMA: to verify )The service account to use for authentication in ECR integrations for this pipeline. | string | Optional | - - - {: .table .table-bordered .table-hover} | Field | Description | Type | Required/Optional | @@ -136,7 +98,7 @@ The priority (override behavior) is as follows, from highest to lowest: | `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.requiredAvailableStorage` | The minimum disk space for the pipeline’s build volume in `Gi` (NIMA: verify units).
                                  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). (NIMA: is there a default min and max? is it the same as the UI? from 1Gi to 8 Gi??) | string | Optional | -| `spec.contexts` | (NIMA: is shared config different from shared secrets?) Single or multiple comma-separated shared configuration contexts to be added to the pipeline.
                                  See [Shared configuration contexts]({{site.baseurl}}/docs/pipelines/configuration/shared-configuration/). | array | Optional | +| `spec.contexts` | 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. (NIMA: how can the user know what the account-level setting is? Do they have to go manually to the Settings to see if there are restrictions?)
                                  See [Select Kubernetes cluster contexts]({{site.baseurl}}/docs/pipelines/pipelines/#select-kubernetes-cluster-contexts). | object | Optional | | `spec.variablesSchema` | ??? (NIMA: I THINK THIS CAN BE REMOVED) | string | `????` | | `spec.variables` | The variables defined in the pipeline. See [spec.variables](#specvariables). | array | Optional |