From c5f601e701d9147a9d6b693c9c256aeb4f75dcdb Mon Sep 17 00:00:00 2001 From: Sarah Jackson Date: Tue, 30 Jul 2024 13:56:39 +1000 Subject: [PATCH 1/4] Updating the documentation to accept an optional slug parameter for PATCH /pipelines --- pages/apis/rest_api/pipelines.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/pages/apis/rest_api/pipelines.md b/pages/apis/rest_api/pipelines.md index 7219a3f0e87..0b71bdad83f 100644 --- a/pages/apis/rest_api/pipelines.md +++ b/pages/apis/rest_api/pipelines.md @@ -876,7 +876,7 @@ Optional [request body properties](/docs/api#request-body-properties): name - The name of the pipeline.

Example: "New Pipeline"

+ The name of the pipeline. If you provide a new name without a slug parameter, the slug will be automatically updated to match the new name.

Example: "New Pipeline"

pipeline_template_uuid @@ -898,6 +898,12 @@ Optional [request body properties](/docs/api#request-body-properties): skip_queued_branch_builds_filter A branch filter pattern to limit which branches intermediate build skipping applies to.

Example: "!main"
Default: null

+ + slug + A custom identifier for the pipeline. This slug will be used as the pipeline's URL path. If not provided when the pipeline name is updated, the slug will be automatically generated from the new pipeline name. If the pipeline name is not updated, the existing slug will remain unchanged. +

Example: "slug": "my-custom-pipeline-slug"

+ + tags From e7dada1abfa85af1bdb6392c0f5f4f1469d0ce2d Mon Sep 17 00:00:00 2001 From: Sarah Jackson Date: Tue, 30 Jul 2024 14:24:32 +1000 Subject: [PATCH 2/4] updated the slug examples to be consistent with the other described request params --- pages/apis/rest_api/pipelines.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/apis/rest_api/pipelines.md b/pages/apis/rest_api/pipelines.md index 0b71bdad83f..082cf8561cd 100644 --- a/pages/apis/rest_api/pipelines.md +++ b/pages/apis/rest_api/pipelines.md @@ -382,7 +382,7 @@ Optional [request body properties](/docs/api#request-body-properties): slug

A custom identifier for the pipeline. If provided, this slug will be used as the pipeline's URL path instead of automatically converting the pipeline name. If the value is null, the pipeline name will be used to generate the slug.

-

Example: "slug": "my-custom-pipeline-slug"

+

Example: "my-custom-pipeline-slug"

@@ -901,7 +901,7 @@ Optional [request body properties](/docs/api#request-body-properties): slug A custom identifier for the pipeline. This slug will be used as the pipeline's URL path. If not provided when the pipeline name is updated, the slug will be automatically generated from the new pipeline name. If the pipeline name is not updated, the existing slug will remain unchanged. -

Example: "slug": "my-custom-pipeline-slug"

+

Example: "my-custom-pipeline-slug"

From d5bd409f44e3f473dc62fd0bec96239438bfe271 Mon Sep 17 00:00:00 2001 From: Sarah Jackson Date: Wed, 31 Jul 2024 14:22:54 +1000 Subject: [PATCH 3/4] Ensuring the formatting is consistent for the examples we provide in the property tables for requests in the pipelines API documentation --- pages/apis/rest_api/pipelines.md | 245 +++++++++++++++++++++---------- 1 file changed, 171 insertions(+), 74 deletions(-) diff --git a/pages/apis/rest_api/pipelines.md b/pages/apis/rest_api/pipelines.md index 082cf8561cd..fd4b11fcdfe 100644 --- a/pages/apis/rest_api/pipelines.md +++ b/pages/apis/rest_api/pipelines.md @@ -291,20 +291,30 @@ Required [request body properties](/docs/api#request-body-properties): name - The name of the pipeline.

Example: "New Pipeline"

+ +

The name of the pipeline.

+

Example: "New Pipeline"

+ cluster_id - The ID value of the cluster the pipeline will be associated with.

Example: "Ab1Cd2Ef3Gh4Ij5Kl6Mn7Op8Qr9St0Uv10Wx11Yz12Ab1Cd2Ef3Gh4Ij5Kl6Mn=="

+ +

The ID value of the cluster the pipeline will be associated with.

+

Example: "Ab1Cd2Ef3Gh4Ij5Kl6Mn7Op8Qr9St0Uv10Wx11Yz12Ab1Cd2Ef3Gh4Ij5Kl6Mn=="

+ repository - The repository URL.

Example: "git@github.com:acme-inc/my-pipeline.git"

+ +

The repository URL.

+

Example: "git@github.com:acme-inc/my-pipeline.git"

+ configuration - The YAML pipeline that consists of the build pipeline steps.

Example: "steps:\n - command: \"script/release.sh\"\n" +

The YAML pipeline that consists of the build pipeline steps.

+

Example: "steps:\n - command: \"script/release.sh\"\n" @@ -337,7 +347,10 @@ Optional [request body properties](/docs/api#request-body-properties): cluster_id - The ID of the cluster the pipeline should run in. Set to null to remove the pipeline from a cluster.

Example: "42f1a7da-812d-4430-93d8-1cc7c33a6bcf"

+ +

The ID of the cluster the pipeline should run in. Set to null to remove the pipeline from a cluster.

+

Example: "42f1a7da-812d-4430-93d8-1cc7c33a6bcf"

+ default_branch @@ -355,7 +368,10 @@ Optional [request body properties](/docs/api#request-body-properties): pipeline_template_uuid - The UUID of the pipeline template the pipeline should run with. Set to null to remove the pipeline template from the pipeline.

Example: "018e5a22-d14c-7085-bb28-db0f83f43a1c"

+ +

The UUID of the pipeline template the pipeline should run with. Set to null to remove the pipeline template from the pipeline.

+

Example: "018e5a22-d14c-7085-bb28-db0f83f43a1c"

+ provider_settings @@ -416,7 +432,8 @@ teams: { visibility -

Whether the pipeline is visible to everyone, including users outside this organization.

Example: "public"
Default: "private"

+

Whether the pipeline is visible to everyone, including users outside this organization.

+

Example: "public"
Default: "private"

@@ -610,20 +627,32 @@ Required [request body properties](/docs/api#request-body-properties): name - The name of the pipeline.

Example: "New Pipeline"

+ +

The name of the pipeline.

+

Example: "New Pipeline"

+ cluster_id - The ID value of the cluster the pipeline will be associated with.

Example: "Ab1Cd2Ef3Gh4Ij5Kl6Mn7Op8Qr9St0Uv10Wx11Yz12Ab1Cd2Ef3Gh4Ij5Kl6Mn=="

+ +

The ID value of the cluster the pipeline will be associated with.

+

Example: "Ab1Cd2Ef3Gh4Ij5Kl6Mn7Op8Qr9St0Uv10Wx11Yz12Ab1Cd2Ef3Gh4Ij5Kl6Mn=="

+ repository - The repository URL.

Example: "git@github.com:acme-inc/my-pipeline.git"

+ +

The repository URL.

+

Example: "git@github.com:acme-inc/my-pipeline.git"

+ steps - An array of the build pipeline steps.

Script: { "type": "script", "name": "Script", "command": "command.sh" }

Wait for all previous steps to finish: { "type": "waiter" }

Block pipeline (see the job unblock API): { "type": "manual" } +

An array of the build pipeline steps.

+

Script: { "type": "script", "name": "Script", "command": "command.sh" }

+

Wait for all previous steps to finish: { "type": "waiter" }

+

Block pipeline (see the job unblock API): { "type": "manual" }

@@ -656,7 +685,10 @@ Optional [request body properties](/docs/api#request-body-properties): cluster_id - The ID of the cluster the pipeline should run in. Set to null to remove the pipeline from a cluster.

Example: "42f1a7da-812d-4430-93d8-1cc7c33a6bcf"

+ +

The ID of the cluster the pipeline should run in. Set to null to remove the pipeline from a cluster.

+

Example: "42f1a7da-812d-4430-93d8-1cc7c33a6bcf"

+ default_branch @@ -681,7 +713,10 @@ Optional [request body properties](/docs/api#request-body-properties): pipeline_template_uuid - The UUID of the pipeline template the pipeline should run with. Set to null to remove the pipeline template from the pipeline.

Example: "018e5a22-d14c-7085-bb28-db0f83f43a1c"

+ +

The UUID of the pipeline template the pipeline should run with. Set to null to remove the pipeline template from the pipeline.

+

Example: "018e5a22-d14c-7085-bb28-db0f83f43a1c"

+ provider_settings @@ -842,65 +877,106 @@ Optional [request body properties](/docs/api#request-body-properties): branch_configuration - A branch filter pattern to limit which pushed branches trigger builds on this pipeline.

Example: "main feature/*"
Default: null

+ +

A branch filter pattern to limit which pushed branches trigger builds on this pipeline.

+

Example: "main feature/*"
Default: null

+ cancel_running_branch_builds - Cancel intermediate builds. When a new build is created on a branch, any previous builds that are running on the same branch will be automatically canceled.

Example: true
Default: false

+ +

Cancel intermediate builds. When a new build is created on a branch, any previous builds that are running on the same branch will be automatically canceled.

+

Example: true
Default: false

+ cancel_running_branch_builds_filter - A branch filter pattern to limit which branches intermediate build canceling applies to.

Example: "develop prs/*"
Default: null

+ +

A branch filter pattern to limit which branches intermediate build canceling applies to.

+

Example: "develop prs/*"
Default: null

+ cluster_id - The ID of the cluster the pipeline should run in. Set to null to remove the pipeline from a cluster.

Example: "42f1a7da-812d-4430-93d8-1cc7c33a6bcf"

+ +

The ID of the cluster the pipeline should run in. Set to null to remove the pipeline from a cluster.

+

Example: "42f1a7da-812d-4430-93d8-1cc7c33a6bcf"

+ configuration - The YAML pipeline that consists of the build pipeline steps.

Example: "steps:\n - command: \"new.sh\"\n agents:\n - \"myqueue=true\""

+ +

The YAML pipeline that consists of the build pipeline steps.

+

Example: "steps:\n - command: \"new.sh\"\n agents:\n - \"myqueue=true\""

+ default_branch - The name of the branch to prefill when new builds are created or triggered in Buildkite. + +

The name of the branch to prefill when new builds are created or triggered in Buildkite.

Example: "main"

description - The pipeline description.

Example: "\:package\: A testing pipeline"

+ +

The pipeline description.

+

Example: "\:package\: A testing pipeline"

+ env - The pipeline environment variables.

Example: {"KEY":"value"}

+ +

The pipeline environment variables.

+

Example: {"KEY":"value"}

+ name - The name of the pipeline. If you provide a new name without a slug parameter, the slug will be automatically updated to match the new name.

Example: "New Pipeline"

+ +

The name of the pipeline. If you provide a new name without a slug parameter, the slug will be automatically updated to match the new name.

+

Example: "New Pipeline"

+ pipeline_template_uuid - The UUID of the pipeline template the pipeline should run with. Set to null to remove the pipeline template from the pipeline.

Example: "018e5a22-d14c-7085-bb28-db0f83f43a1c"

+ +

The UUID of the pipeline template the pipeline should run with. Set to null to remove the pipeline template from the pipeline.

+

Example: "018e5a22-d14c-7085-bb28-db0f83f43a1c"

+ provider_settings - The source provider settings. See the Provider Settings section for accepted properties.

Example: { "publish_commit_status": true, "build_pull_request_forks": true }

+ +

The source provider settings. See the Provider Settings section for accepted properties.

+

Example: { "publish_commit_status": true, "build_pull_request_forks": true }

+ repository - The repository URL.

Example: "git@github.com/org/repo.git"

+ +

The repository URL.

+

Example: "git@github.com/org/repo.git"

+ skip_queued_branch_builds - Skip intermediate builds. When a new build is created on a branch, any previous builds that haven't yet started on the same branch will be automatically marked as skipped.

Example: true
Default: false

+ +

Skip intermediate builds. When a new build is created on a branch, any previous builds that haven't yet started on the same branch will be automatically marked as skipped.

+

Example: true
Default: false

+ skip_queued_branch_builds_filter - A branch filter pattern to limit which branches intermediate build skipping applies to.

Example: "!main"
Default: null

+ +

A branch filter pattern to limit which branches intermediate build skipping applies to.

+

Example: "!main"
Default: null

+ slug - A custom identifier for the pipeline. This slug will be used as the pipeline's URL path. If not provided when the pipeline name is updated, the slug will be automatically generated from the new pipeline name. If the pipeline name is not updated, the existing slug will remain unchanged. + +

A custom identifier for the pipeline. This slug will be used as the pipeline's URL path. If not provided when the pipeline name is updated, the slug will be automatically generated from the new pipeline name. If the pipeline name is not updated, the existing slug will remain unchanged.

Example: "my-custom-pipeline-slug"

@@ -913,7 +989,10 @@ Optional [request body properties](/docs/api#request-body-properties): visibility - Whether the pipeline is visible to everyone, including users outside this organization.

Example: "public"
Default: "private"

+ +

Whether the pipeline is visible to everyone, including users outside this organization.

+

Example: "public"
Default: "private"

+ @@ -1145,13 +1224,13 @@ Properties available for all providers: filter_enabled - Whether filter conditions are used for this pipeline. +

Whether filter conditions are used for this pipeline.

Values: true, false

filter_condition - The conditions under which this pipeline will trigger a build. See the Using conditionals guide for more information. +

The conditions under which this pipeline will trigger a build. See the Using conditionals guide for more information.

Example: "build.pull_request.base_branch =~ /main/"

@@ -1167,20 +1246,23 @@ Properties available for Bitbucket Server: build_branches - Whether to create builds when branches are pushed. -

Values: true, false

+

Whether to create builds when branches are pushed.

+

Values: true, false

+ build_pull_requests - Whether to create builds for commits that are part of a Pull Request. -

Values: true, false

+

Whether to create builds for commits that are part of a Pull Request.

+

Values: true, false

+ build_tags - Whether to create builds when tags are pushed. -

Values: true, false

+

Whether to create builds when tags are pushed.

+

Values: true, false

+ @@ -1192,65 +1274,72 @@ Properties available for Bitbucket Cloud, GitHub, and GitHub Enterprise: build_branches - Whether to create builds when branches are pushed. +

Whether to create builds when branches are pushed.

Values: true, false

build_pull_requests - Whether to create builds for commits that are part of a Pull Request. +

Whether to create builds for commits that are part of a Pull Request.

Values: true, false

build_tags - Whether to create builds when tags are pushed. -

Values: true, false

+

Whether to create builds when tags are pushed.

+

Values: true, false

+ cancel_deleted_branch_builds - A boolean to enable automatically cancelling any running builds for a branch if the branch is deleted. -

Values: true, false

+

A boolean to enable automatically cancelling any running builds for a branch if the branch is deleted.

+

Values: true, false

+ publish_commit_status - Whether to update the status of commits in Bitbucket or GitHub. -

Values: true, false

+

Whether to update the status of commits in Bitbucket or GitHub.

+

Values: true, false

+ publish_commit_status_per_step - Whether to create a separate status for each job in a build, allowing you to see the status of each job directly in Bitbucket or GitHub. -

Values: true, false

+

Whether to create a separate status for each job in a build, allowing you to see the status of each job directly in Bitbucket or GitHub.

+

Values: true, false

+ pull_request_branch_filter_enabled - Whether to limit the creation of builds to specific branches or patterns. +

Whether to limit the creation of builds to specific branches or patterns.

Values: true, false

+ pull_request_branch_filter_configuration - The branch filtering pattern. Only pull requests on branches matching this pattern will cause builds to be created. +

The branch filtering pattern. Only pull requests on branches matching this pattern will cause builds to be created.

Example: "features/*"

skip_builds_for_existing_commits - Whether to skip creating a new build if a build for the commit and branch already exists. -

Values: true, false

+

Whether to skip creating a new build if a build for the commit and branch already exists.

+

Values: true, false

+ skip_pull_request_builds_for_existing_commits - Whether to skip creating a new build for a pull request if an existing build for the commit and branch already exists. -

Values: true, false

+

Whether to skip creating a new build for a pull request if an existing build for the commit and branch already exists.

+

Values: true, false

+ @@ -1262,50 +1351,58 @@ Additional properties available for GitHub: build_pull_request_forks - Whether to create builds for pull requests from third-party forks. -

Values: true, false

+

Whether to create builds for pull requests from third-party forks.

+

Values: true, false

+ build_pull_request_labels_changed - - Whether to create builds for pull requests when labels are added or removed. -

Values: true, false

+ < +

Whether to create builds for pull requests when labels are added or removed.

+

Values: true, false

+ build_pull_request_ready_for_review - Whether to create builds for pull requests that are ready for review. -

Values: true, false

+

Whether to create builds for pull requests that are ready for review.

+

Values: true, false

+ prefix_pull_request_fork_branch_names - Prefix branch names for third-party fork builds to ensure they don't trigger branch conditions. For example, the main branch from some-user will become some-user:main. -

Values: true, false

+

Prefix branch names for third-party fork builds to ensure they don't trigger branch conditions. For example, the main branch from some-user will become some-user:main.

+

Values: true, false

+ publish_blocked_as_pending - The status to use for blocked builds. Pending can be used with required status checks to prevent merging pull requests with blocked builds. -

Values: true, false

+

The status to use for blocked builds. Pending can be used with required status checks to prevent merging pull requests with blocked builds.

+

Values: true, false

+ separate_pull_request_statuses - Whether to create a separate status for pull request builds, allowing you to require a passing pull request build in your required status checks in GitHub. -

Values: true, false

+

Whether to create a separate status for pull request builds, allowing you to require a passing pull request build in your required status checks in GitHub.

+

Values: true, false

+ trigger_mode - What type of event to trigger builds on. -
    -
  • code creates builds when code is pushed to GitHub.
    • -
  • deployment creates builds when a deployment is created with the GitHub Deployments API.
    • -
  • fork creates builds when the GitHub repository is forked.
    • -
  • none will not create any builds based on GitHub activity.
    • -
-

Values: code, deployment, fork, none

+

What type of event to trigger builds on. +

    +
  • code creates builds when code is pushed to GitHub.
    • +
  • deployment creates builds when a deployment is created with the GitHub Deployments API.
    • +
  • fork creates builds when the GitHub repository is forked.
    • +
  • none will not create any builds based on GitHub activity.
    • +
+

+

Values: code, deployment, fork, none

+ From 0df99ddd67cbab2e4d00a5d9bfb66ce0200f136e Mon Sep 17 00:00:00 2001 From: Sarah Jackson Date: Wed, 31 Jul 2024 14:47:08 +1000 Subject: [PATCH 4/4] Ensuring proper escaping of special characters --- pages/apis/rest_api/pipelines.md | 58 ++++++++++++++++---------------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/pages/apis/rest_api/pipelines.md b/pages/apis/rest_api/pipelines.md index fd4b11fcdfe..601eb38718c 100644 --- a/pages/apis/rest_api/pipelines.md +++ b/pages/apis/rest_api/pipelines.md @@ -288,35 +288,35 @@ The response contains information about your new pipeline: Required [request body properties](/docs/api#request-body-properties): - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + +
name -

The name of the pipeline.

-

Example: "New Pipeline"

-
cluster_id -

The ID value of the cluster the pipeline will be associated with.

-

Example: "Ab1Cd2Ef3Gh4Ij5Kl6Mn7Op8Qr9St0Uv10Wx11Yz12Ab1Cd2Ef3Gh4Ij5Kl6Mn=="

-
repository -

The repository URL.

-

Example: "git@github.com:acme-inc/my-pipeline.git"

-
configuration -

The YAML pipeline that consists of the build pipeline steps.

-

Example: "steps:\n - command: \"script/release.sh\"\n" -

name +

The name of the pipeline.

+

Example: "New Pipeline"

+
cluster_id +

The ID value of the cluster the pipeline will be associated with.

+

Example: "Ab1Cd2Ef3Gh4Ij5Kl6Mn7Op8Qr9St0Uv10Wx11Yz12Ab1Cd2Ef3Gh4Ij5Kl6Mn=="

+
repository +

The repository URL.

+

Example: "git@github.com:acme-inc/my-pipeline.git"

+
configuration +

The YAML pipeline that consists of the build pipeline steps.

+

Example: "steps:\n - command: \"script/release.sh\"\n"

+