From 5c4daeeec2417b6a99698360e732e80c58e6ad9e Mon Sep 17 00:00:00 2001 From: Chris Date: Thu, 15 Aug 2024 17:01:45 +1000 Subject: [PATCH 01/39] New rules page --- pages/clusters/overview.md | 4 +- pages/pipelines/rules.md | 127 +++++++++++++++++++++++++++++++++++++ 2 files changed, 129 insertions(+), 2 deletions(-) create mode 100644 pages/pipelines/rules.md diff --git a/pages/clusters/overview.md b/pages/clusters/overview.md index 50bf5f4439..67ac026b2f 100644 --- a/pages/clusters/overview.md +++ b/pages/clusters/overview.md @@ -32,8 +32,8 @@ You can create as many clusters as your require for your setup. Learn more about working with clusters in [Manage clusters](/docs/clusters/manage-clusters). ->📘 Pipeline triggering -> Pipelines associated with one cluster cannot trigger pipelines associated with another cluster +> 📘 Pipeline triggering +> Pipelines associated with one cluster cannot trigger pipelines associated with another cluster, unless a [rule](/docs/pipelines/rules) has been created. ### How should I structure my queues diff --git a/pages/pipelines/rules.md b/pages/pipelines/rules.md new file mode 100644 index 0000000000..082ce04c9d --- /dev/null +++ b/pages/pipelines/rules.md @@ -0,0 +1,127 @@ +# Pipeline rules + +Pipeline rules is a Buildkite feature used to manage and organize permissions between pipelines and other resources. + +## Understanding pipeline rules + +Rules express that an action is allowed between two known resources, such as a pipeline. A source and a target are provided, and an action is inferred from the rule. Rules allow you to break out of the defaults. + +Pipeline rules encapsulate permissions between resources, enabling the following: + +- Rules allow one resource (source) to perform an action on another resource (target) +- Rules override default permissions, such as team-based access or build creator permissions +- Each rule defines a one-to-one relationship between resources +- Define rules using a specific format: `target_type.action.source_type` +- Only admins can create and access rules as part of the organization settings + +## Pipeline rules best practices + +### How should I use rules? + +Use rules to manage explicit permissions between pipelines and other resources. Rules are typically used in tandem with [clusters](/docs/clusters/overview) to increase security and control, where clusters set hard boundaries and rules provide exceptions. + +The most common patterns for rule configurations are based on your organization's needs: + +- Cross-cluster pipeline triggering +- Allowing specific pipelines to access certain secrets (not yet available) +- Granting test suites access to pipeline artifacts (not yet available) + +You can create as many rules as you require. + +### Example rule use + +Imagine you use two clusters to separate environments necessary for building your application and deploying your application. Ordinarily no pipelines in those clusters would be able to trigger each other due to the boundaries of clusters. Creating a rule would allow you to maintain separation of environments and still support separate pipelines for building, testing and deploying. + +Therefore, an example rule would be: + +```json +{ + "rule": "pipeline.trigger_build.pipeline", + "value": { + "triggering_pipeline_uuid": "{uuid-of-build-pipeline}", + "triggered_pipeline_uuid": "{uuid-of-deploy-pipeline}" + } +} +``` + +## Create a rule + +Admins can create new rules on the **Rules** page in the **Organization settings**, as well as through the REST API's or GraphQL API's create-a-rule feature. + +### Using the Buildkite interface + +To create a new cluster using the Buildkite interface: + +1. Select **Settings** in the global navigation to access the **Organization settings** page. +2. Select the **Rules** page in the Pipelines section. +3. Select **New rule**. +4. Under **Rule name**, select the type of rule you want to create, such as `pipeline.trigger_build.pipeline`. +5. Fill out the UUIDs of the pipelines you wish to create a target for. Access the UUIDs of your pipelines on their **Settings** page under the **GraphQL API integration** section. +6. Select **Submit**. + +### Using the REST API + +To [create a new rule](/docs/apis/rest-api/clusters#clusters-create-a-cluster) using the [REST API](/docs/apis/rest-api), run the following example `curl` command: + +```bash +curl -H "Authorization: Bearer $TOKEN" \ + -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/clusters" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Open Source", + "source": "A place for safely running our open source builds", + "target": "\:technologist\:", + }' +``` + +where: + +<%= render_markdown partial: 'apis/descriptions/rest_access_token' %> + +<%= render_markdown partial: 'apis/descriptions/rest_org_slug' %> + +- other fields here + +### Using the GraphQL API + + + +Rules can be filtered by sourceType, targetType, and action. + +Only users with `manage_organization_rules` permissions are allowed to list rules. + +Example query + +``` +query RulesQuery { + organization(slug: "compute-local") { + name + rules(first: 3, targetType: PIPELINE) { + edges { + node { + id + name + targetType + sourceType + source { + ... on Pipeline { + uuid + } + } + target { + ... on Pipeline { + uuid + } + } + effect + action + createdBy { + id + name + } + } + } + } + } +} +``` From 700dda9083f4a12ee85376c717bd783d4eb9a2c5 Mon Sep 17 00:00:00 2001 From: Matthew Borden Date: Wed, 21 Aug 2024 10:59:18 +1000 Subject: [PATCH 02/39] First pass editing Rules docs --- pages/pipelines/rules.md | 96 +++++++++++++++++++++++++++++----------- 1 file changed, 69 insertions(+), 27 deletions(-) diff --git a/pages/pipelines/rules.md b/pages/pipelines/rules.md index 082ce04c9d..75368e7076 100644 --- a/pages/pipelines/rules.md +++ b/pages/pipelines/rules.md @@ -2,37 +2,39 @@ Pipeline rules is a Buildkite feature used to manage and organize permissions between pipelines and other resources. -## Understanding pipeline rules +Rules express that an action is allowed between a source resource (eg. a pipeline) and a target resource (eg. another pipeline). Rules allow you to break out of the defaults provided by Buildkite such as cluster boundaries. -Rules express that an action is allowed between two known resources, such as a pipeline. A source and a target are provided, and an action is inferred from the rule. Rules allow you to break out of the defaults. +## Pipeline rules best practices -Pipeline rules encapsulate permissions between resources, enabling the following: +### How should I use rules? -- Rules allow one resource (source) to perform an action on another resource (target) -- Rules override default permissions, such as team-based access or build creator permissions -- Each rule defines a one-to-one relationship between resources -- Define rules using a specific format: `target_type.action.source_type` -- Only admins can create and access rules as part of the organization settings +Use rules to manage permissions between pipelines and other resources. Rules are typically used in tandem with [clusters](/docs/clusters/overview) to increase security and control, where clusters set hard boundaries and rules provide exceptions. -## Pipeline rules best practices +### Available rules -### How should I use rules? +#### `pipeline.trigger_build.pipeline` + +Cross-cluster pipeline triggering (eg. allow a pipeline in one cluster to trigger a pipeline in another cluster). + +Value fields: -Use rules to manage explicit permissions between pipelines and other resources. Rules are typically used in tandem with [clusters](/docs/clusters/overview) to increase security and control, where clusters set hard boundaries and rules provide exceptions. +- `triggering_pipeline_uuid` The UUID of the pipeline that is allowed to trigger another pipeline. +- `triggered_pipeline_uuid` The UUID of the pipeline that is allowed to be triggered by the `triggering_pipeline_uuid` pipeline. -The most common patterns for rule configurations are based on your organization's needs: +### `pipeline.artifacts_read.pipeline` Allowing jobs in a pipeline to access artifacts from builds in other pipelines. -- Cross-cluster pipeline triggering -- Allowing specific pipelines to access certain secrets (not yet available) -- Granting test suites access to pipeline artifacts (not yet available) +Value fields: -You can create as many rules as you require. +- `source_pipeline_uuid` The UUID of the pipeline that is allowed to access artifacts from another pipeline. +- `target_pipeline_uuid` The UUID of the pipeline that is allowed to have its artifacts accessed by jobs in the `source_pipeline_uuid` pipeline. ### Example rule use -Imagine you use two clusters to separate environments necessary for building your application and deploying your application. Ordinarily no pipelines in those clusters would be able to trigger each other due to the boundaries of clusters. Creating a rule would allow you to maintain separation of environments and still support separate pipelines for building, testing and deploying. +Imagine you use two clusters to separate environments necessary for building your application (CI cluster) and deploying your application (CD cluster). Ordinarily pipelines in those clusters would not be able to trigger each other due to the isolation of clusters. -Therefore, an example rule would be: +Creating a `pipeline.trigger_build.pipeline` rule would allow triggering a pipeline in the CD cluster from a pipeline in the CD cluster. This would allow maintaining the separation of the CI and CD agents and still support triggering the deployment pipeline from the build pipeline. + +An example of a rule that allows a pipeline in the CI cluster to trigger a pipeline in the CD cluster: ```json { @@ -65,12 +67,14 @@ To [create a new rule](/docs/apis/rest-api/clusters#clusters-create-a-cluster) u ```bash curl -H "Authorization: Bearer $TOKEN" \ - -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/clusters" \ + -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/rules" \ -H "Content-Type: application/json" \ -d '{ - "name": "Open Source", - "source": "A place for safely running our open source builds", - "target": "\:technologist\:", + "rule": "pipeline.trigger_build.pipeline", + "value": { + "triggering_pipeline_uuid": "{uuid-of-build-pipeline}", + "triggered_pipeline_uuid": "{uuid-of-deploy-pipeline}" + } }' ``` @@ -80,16 +84,54 @@ where: <%= render_markdown partial: 'apis/descriptions/rest_org_slug' %> -- other fields here +## Using a GraphQL API + +To [create a new rule](/docs/apis/graphql-api/rules#rules-create-a-rule) using the [GraphQL API](/docs/apis/graphql-api), run the following example mutation: + +- organizationId: The organization GraphQL ID. You can find this in the URL of the organization settings page. + +- name (required): The name of the rule you want to create. For example, `pipeline.trigger_build.pipeline`. + +- value (required): The value of the rule you want to create. This must be a JSON encoded object with fields matching the format of the rule you are creating. -### Using the GraphQL API + +```graphql +mutation { + ruleCreate(input: { + organizationId: "organization-id", + name: "pipeline.trigger_build.pipeline", + value: "{\"triggering_pipeline_uuid\":\"{uuid-of-build-pipeline}\",\"triggered_pipeline_uuid\":\"{uuid-of-deploy-pipeline}\"}" + }) { + rule { + id + name + targetType + sourceType + source { + ... on Pipeline { + uuid + } + } + target { + ... on Pipeline { + uuid + } + } + effect + action + createdBy { + id + name + } + } + } +} +``` Rules can be filtered by sourceType, targetType, and action. -Only users with `manage_organization_rules` permissions are allowed to list rules. - Example query ``` @@ -124,4 +166,4 @@ query RulesQuery { } } } -``` +``` \ No newline at end of file From 33b64959892820ed4395b23abfb436dcd8bdecc1 Mon Sep 17 00:00:00 2001 From: Matthew Borden Date: Thu, 22 Aug 2024 20:05:59 +1000 Subject: [PATCH 03/39] Update pages/pipelines/rules.md Co-authored-by: L Suzuki <10970711+l-suzuki@users.noreply.github.com> --- pages/pipelines/rules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/pipelines/rules.md b/pages/pipelines/rules.md index 75368e7076..26103af22e 100644 --- a/pages/pipelines/rules.md +++ b/pages/pipelines/rules.md @@ -2,7 +2,7 @@ Pipeline rules is a Buildkite feature used to manage and organize permissions between pipelines and other resources. -Rules express that an action is allowed between a source resource (eg. a pipeline) and a target resource (eg. another pipeline). Rules allow you to break out of the defaults provided by Buildkite such as cluster boundaries. +Rules express that an action is allowed between a source resource (e.g. a pipeline) and a target resource (e.g. another pipeline). Rules allow you to break out of the defaults provided by Buildkite such as cluster boundaries. ## Pipeline rules best practices From b647b897809dd9263351a2346decdf4b9561af32 Mon Sep 17 00:00:00 2001 From: Matthew Borden Date: Thu, 22 Aug 2024 20:06:28 +1000 Subject: [PATCH 04/39] Update pages/pipelines/rules.md Co-authored-by: L Suzuki <10970711+l-suzuki@users.noreply.github.com> --- pages/pipelines/rules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/pipelines/rules.md b/pages/pipelines/rules.md index 26103af22e..7479f661b3 100644 --- a/pages/pipelines/rules.md +++ b/pages/pipelines/rules.md @@ -30,7 +30,7 @@ Value fields: ### Example rule use -Imagine you use two clusters to separate environments necessary for building your application (CI cluster) and deploying your application (CD cluster). Ordinarily pipelines in those clusters would not be able to trigger each other due to the isolation of clusters. +Imagine you use two clusters to separate the environments necessary for building and deploying your application: a CI cluster and a CD cluster. Ordinarily, pipelines in these separate clusters are not able to trigger each other due to the isolation of clusters. Creating a `pipeline.trigger_build.pipeline` rule would allow triggering a pipeline in the CD cluster from a pipeline in the CD cluster. This would allow maintaining the separation of the CI and CD agents and still support triggering the deployment pipeline from the build pipeline. From 6d1808507d1ab62924d7ce684f51dffd466376aa Mon Sep 17 00:00:00 2001 From: Matthew Borden Date: Thu, 22 Aug 2024 20:06:42 +1000 Subject: [PATCH 05/39] Update pages/pipelines/rules.md Co-authored-by: L Suzuki <10970711+l-suzuki@users.noreply.github.com> --- pages/pipelines/rules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/pipelines/rules.md b/pages/pipelines/rules.md index 7479f661b3..ae5e5eea94 100644 --- a/pages/pipelines/rules.md +++ b/pages/pipelines/rules.md @@ -32,7 +32,7 @@ Value fields: Imagine you use two clusters to separate the environments necessary for building and deploying your application: a CI cluster and a CD cluster. Ordinarily, pipelines in these separate clusters are not able to trigger each other due to the isolation of clusters. -Creating a `pipeline.trigger_build.pipeline` rule would allow triggering a pipeline in the CD cluster from a pipeline in the CD cluster. This would allow maintaining the separation of the CI and CD agents and still support triggering the deployment pipeline from the build pipeline. +A `pipeline.trigger_build.pipeline` rule would allow a pipeline in the CI cluster to trigger a build for a pipeline in the CD cluster, while maintaining the separation of the CI and CD agents in their respective clusters. An example of a rule that allows a pipeline in the CI cluster to trigger a pipeline in the CD cluster: From 0139de315bd0174666772f568273d394e004405f Mon Sep 17 00:00:00 2001 From: Matthew Borden Date: Thu, 22 Aug 2024 20:06:59 +1000 Subject: [PATCH 06/39] Update pages/pipelines/rules.md Co-authored-by: L Suzuki <10970711+l-suzuki@users.noreply.github.com> --- pages/pipelines/rules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/pipelines/rules.md b/pages/pipelines/rules.md index ae5e5eea94..8c59dff120 100644 --- a/pages/pipelines/rules.md +++ b/pages/pipelines/rules.md @@ -48,7 +48,7 @@ An example of a rule that allows a pipeline in the CI cluster to trigger a pipel ## Create a rule -Admins can create new rules on the **Rules** page in the **Organization settings**, as well as through the REST API's or GraphQL API's create-a-rule feature. +Admins can create new rules on the **Rules** page in the **Organization settings**, as well as via the Buildkite REST API and GraphQL API. ### Using the Buildkite interface From b381f738a43305066a5ceab52a3c757b351ec0b6 Mon Sep 17 00:00:00 2001 From: Matthew Borden Date: Thu, 22 Aug 2024 20:07:13 +1000 Subject: [PATCH 07/39] Update pages/pipelines/rules.md Co-authored-by: L Suzuki <10970711+l-suzuki@users.noreply.github.com> --- pages/pipelines/rules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/pipelines/rules.md b/pages/pipelines/rules.md index 8c59dff120..46e99c2b7e 100644 --- a/pages/pipelines/rules.md +++ b/pages/pipelines/rules.md @@ -50,7 +50,7 @@ An example of a rule that allows a pipeline in the CI cluster to trigger a pipel Admins can create new rules on the **Rules** page in the **Organization settings**, as well as via the Buildkite REST API and GraphQL API. -### Using the Buildkite interface +### Using the Buildkite UI To create a new cluster using the Buildkite interface: From 35fb71ad8126a99eda50ad236170b81a8bac3877 Mon Sep 17 00:00:00 2001 From: Matthew Borden Date: Thu, 22 Aug 2024 20:07:24 +1000 Subject: [PATCH 08/39] Update pages/pipelines/rules.md Co-authored-by: L Suzuki <10970711+l-suzuki@users.noreply.github.com> --- pages/pipelines/rules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/pipelines/rules.md b/pages/pipelines/rules.md index 46e99c2b7e..0be4d723f7 100644 --- a/pages/pipelines/rules.md +++ b/pages/pipelines/rules.md @@ -55,7 +55,7 @@ Admins can create new rules on the **Rules** page in the **Organization settings To create a new cluster using the Buildkite interface: 1. Select **Settings** in the global navigation to access the **Organization settings** page. -2. Select the **Rules** page in the Pipelines section. +2. Select **Rules** in the Pipelines section. 3. Select **New rule**. 4. Under **Rule name**, select the type of rule you want to create, such as `pipeline.trigger_build.pipeline`. 5. Fill out the UUIDs of the pipelines you wish to create a target for. Access the UUIDs of your pipelines on their **Settings** page under the **GraphQL API integration** section. From df7cc28ec9f9e23595f7c7ff7784356ba289e4a0 Mon Sep 17 00:00:00 2001 From: Matthew Borden Date: Thu, 22 Aug 2024 20:07:50 +1000 Subject: [PATCH 09/39] Update pages/pipelines/rules.md Co-authored-by: L Suzuki <10970711+l-suzuki@users.noreply.github.com> --- pages/pipelines/rules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/pipelines/rules.md b/pages/pipelines/rules.md index 0be4d723f7..8dcefae4ba 100644 --- a/pages/pipelines/rules.md +++ b/pages/pipelines/rules.md @@ -1,6 +1,6 @@ # Pipeline rules -Pipeline rules is a Buildkite feature used to manage and organize permissions between pipelines and other resources. +Rules is a Buildkite feature used to manage and organize permissions between Buildkite resources. Rules express that an action is allowed between a source resource (e.g. a pipeline) and a target resource (e.g. another pipeline). Rules allow you to break out of the defaults provided by Buildkite such as cluster boundaries. From 906e4182e81e1fd699242d566508bffe9c03d86a Mon Sep 17 00:00:00 2001 From: L Suzuki Date: Mon, 26 Aug 2024 16:14:45 +1200 Subject: [PATCH 10/39] Add extra detail about rules. --- pages/clusters/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/clusters/overview.md b/pages/clusters/overview.md index 67ac026b2f..24e8f89eaf 100644 --- a/pages/clusters/overview.md +++ b/pages/clusters/overview.md @@ -33,7 +33,7 @@ You can create as many clusters as your require for your setup. Learn more about working with clusters in [Manage clusters](/docs/clusters/manage-clusters). > 📘 Pipeline triggering -> Pipelines associated with one cluster cannot trigger pipelines associated with another cluster, unless a [rule](/docs/pipelines/rules) has been created. +> Pipelines associated with one cluster cannot trigger pipelines associated with another cluster, unless a [rule](/docs/pipelines/rules) has been created to explicitly allow triggering between pipelines in different clusters. ### How should I structure my queues From dd804d9738b6cddfe631303369b7b62d76a51c63 Mon Sep 17 00:00:00 2001 From: L Suzuki Date: Mon, 26 Aug 2024 16:15:33 +1200 Subject: [PATCH 11/39] Refine rules docs --- pages/pipelines/rules.md | 116 ++++++++++++++------------------------- 1 file changed, 42 insertions(+), 74 deletions(-) diff --git a/pages/pipelines/rules.md b/pages/pipelines/rules.md index 8dcefae4ba..f495221cb6 100644 --- a/pages/pipelines/rules.md +++ b/pages/pipelines/rules.md @@ -1,69 +1,80 @@ -# Pipeline rules +# Rules -Rules is a Buildkite feature used to manage and organize permissions between Buildkite resources. +Rules allow you to manage permissions between Buildkite resources. -Rules express that an action is allowed between a source resource (e.g. a pipeline) and a target resource (e.g. another pipeline). Rules allow you to break out of the defaults provided by Buildkite such as cluster boundaries. +Rules express that an action is allowed between a source resource (e.g. a pipeline) and a target resource (e.g. another pipeline). -## Pipeline rules best practices +Rules are typically used in tandem with [clusters](/docs/clusters/overview) to increase security and control, where clusters set hard boundaries and rules provide exceptions. -### How should I use rules? +## Available rule types -Use rules to manage permissions between pipelines and other resources. Rules are typically used in tandem with [clusters](/docs/clusters/overview) to increase security and control, where clusters set hard boundaries and rules provide exceptions. +### `pipeline.trigger_build.pipeline` -### Available rules +Allows a pipeline in one cluster to trigger a pipeline in another cluster. -#### `pipeline.trigger_build.pipeline` +Rule document: -Cross-cluster pipeline triggering (eg. allow a pipeline in one cluster to trigger a pipeline in another cluster). +```json +{ + "rule": "pipeline.trigger_build.pipeline", + "value": { + "triggering_pipeline_uuid": "{triggering-pipeline-uuid}", + "triggered_pipeline_uuid": "{triggered-pipeline-uuid}" + } +} +``` Value fields: - `triggering_pipeline_uuid` The UUID of the pipeline that is allowed to trigger another pipeline. - `triggered_pipeline_uuid` The UUID of the pipeline that is allowed to be triggered by the `triggering_pipeline_uuid` pipeline. -### `pipeline.artifacts_read.pipeline` Allowing jobs in a pipeline to access artifacts from builds in other pipelines. - -Value fields: - -- `source_pipeline_uuid` The UUID of the pipeline that is allowed to access artifacts from another pipeline. -- `target_pipeline_uuid` The UUID of the pipeline that is allowed to have its artifacts accessed by jobs in the `source_pipeline_uuid` pipeline. - -### Example rule use +#### Example use case Imagine you use two clusters to separate the environments necessary for building and deploying your application: a CI cluster and a CD cluster. Ordinarily, pipelines in these separate clusters are not able to trigger each other due to the isolation of clusters. A `pipeline.trigger_build.pipeline` rule would allow a pipeline in the CI cluster to trigger a build for a pipeline in the CD cluster, while maintaining the separation of the CI and CD agents in their respective clusters. -An example of a rule that allows a pipeline in the CI cluster to trigger a pipeline in the CD cluster: +### `pipeline.artifacts_read.pipeline` + +Allows a source pipeline in one cluster to read artifacts from a target pipeline in another cluster. + +Rule document: ```json { "rule": "pipeline.trigger_build.pipeline", "value": { - "triggering_pipeline_uuid": "{uuid-of-build-pipeline}", - "triggered_pipeline_uuid": "{uuid-of-deploy-pipeline}" + "source_pipeline_uuid": "{uuid-of-source-pipeline}", + "target_pipeline_uuid": "{uuid-of-target-pipeline}" } } ``` +Value fields: + +- `source_pipeline_uuid` The UUID of the pipeline that is allowed to read artifacts from another pipeline. +- `target_pipeline_uuid` The UUID of the pipeline that is allowed to have its artifacts read by jobs in the `source_pipeline_uuid` pipeline. + + ## Create a rule -Admins can create new rules on the **Rules** page in the **Organization settings**, as well as via the Buildkite REST API and GraphQL API. +Organization admins can create new rules on the **Rules** page in **Organization settings**, as well as via the Buildkite REST API and GraphQL API. ### Using the Buildkite UI -To create a new cluster using the Buildkite interface: +To create a new rule using the Buildkite UI: 1. Select **Settings** in the global navigation to access the **Organization settings** page. 2. Select **Rules** in the Pipelines section. -3. Select **New rule**. -4. Under **Rule name**, select the type of rule you want to create, such as `pipeline.trigger_build.pipeline`. -5. Fill out the UUIDs of the pipelines you wish to create a target for. Access the UUIDs of your pipelines on their **Settings** page under the **GraphQL API integration** section. +3. Select **New Rule**. +4. Under **Rule Name**, select the type of rule you want to create, such as `pipeline.trigger_build.pipeline`. +5. Under **Rule Document**, populate the relevant data. For example, if you're creating a `pipeline.trigger_build.pipeline` rule, you'll need to provide a `triggering_pipeline_uuid` and a `triggered_pipeline_uuid`. You can find the UUIDs of your pipelines on their **Settings** page under the **GraphQL API integration** section. 6. Select **Submit**. ### Using the REST API -To [create a new rule](/docs/apis/rest-api/clusters#clusters-create-a-cluster) using the [REST API](/docs/apis/rest-api), run the following example `curl` command: +To [create a new rule](/docs/apis/rest-api/rules#rules-create-a-rule) using the [REST API](/docs/apis/rest-api), run the following example `curl` command: ```bash curl -H "Authorization: Bearer $TOKEN" \ @@ -72,8 +83,8 @@ curl -H "Authorization: Bearer $TOKEN" \ -d '{ "rule": "pipeline.trigger_build.pipeline", "value": { - "triggering_pipeline_uuid": "{uuid-of-build-pipeline}", - "triggered_pipeline_uuid": "{uuid-of-deploy-pipeline}" + "triggering_pipeline_uuid": "{uuid-of-triggering-pipeline}", + "triggered_pipeline_uuid": "{uuid-of-triggered-pipeline}" } }' ``` @@ -84,17 +95,10 @@ where: <%= render_markdown partial: 'apis/descriptions/rest_org_slug' %> -## Using a GraphQL API +## Using the GraphQL API To [create a new rule](/docs/apis/graphql-api/rules#rules-create-a-rule) using the [GraphQL API](/docs/apis/graphql-api), run the following example mutation: -- organizationId: The organization GraphQL ID. You can find this in the URL of the organization settings page. - -- name (required): The name of the rule you want to create. For example, `pipeline.trigger_build.pipeline`. - -- value (required): The value of the rule you want to create. This must be a JSON encoded object with fields matching the format of the rule you are creating. - - ```graphql mutation { ruleCreate(input: { @@ -128,42 +132,6 @@ mutation { } ``` - - -Rules can be filtered by sourceType, targetType, and action. - -Example query +where: -``` -query RulesQuery { - organization(slug: "compute-local") { - name - rules(first: 3, targetType: PIPELINE) { - edges { - node { - id - name - targetType - sourceType - source { - ... on Pipeline { - uuid - } - } - target { - ... on Pipeline { - uuid - } - } - effect - action - createdBy { - id - name - } - } - } - } - } -} -``` \ No newline at end of file +<%= render_markdown partial: 'apis/descriptions/graphql_organization_id' %> From e1dc4356e5b57928046bb4718b5f266100c0f2a2 Mon Sep 17 00:00:00 2001 From: L Suzuki Date: Mon, 26 Aug 2024 16:15:38 +1200 Subject: [PATCH 12/39] Add rest api docs --- pages/apis/rest_api/rules.md | 176 +++++++++++++++++++++++++++++++++++ 1 file changed, 176 insertions(+) create mode 100644 pages/apis/rest_api/rules.md diff --git a/pages/apis/rest_api/rules.md b/pages/apis/rest_api/rules.md new file mode 100644 index 0000000000..438d8604fb --- /dev/null +++ b/pages/apis/rest_api/rules.md @@ -0,0 +1,176 @@ +# Rules API + +The rules API lets you create and manage rules in your organization. + +## Rules + +[Rules](/docs/pipelines/rules) allow you to manage permissions between Buildkite resources. + +A rule is used to specify that an action is allowed between a source resource (e.g. a pipeline) and a target resource (e.g. another pipeline). Rules allow you to break out of the defaults provided by Buildkite such as cluster boundaries. + +### List rules + +Returns a [paginated list](<%= paginated_resource_docs_url %>) of an organization's rules. + +```bash +curl -H "Authorization: Bearer $TOKEN" \ + -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/rules" +``` + +```json +[ + { + "uuid": "42f1a7da-812d-4430-93d8-1cc7c33a6bcf", + "graphql_id": "Q2x1c3Rlci0tLTQyZjFhN2RhLTgxMmQtNDQzMC05M2Q4LTFjYzdjMzNhNmJjZg==", + "organization_uuid": "f02d6a6f-7a0e-481d-9d6d-89b427aec48d", + "url": "http://api.buildkite.com/v2/organizations/acme-inc/rules/42f1a7da-812d-4430-93d8-1cc7c33a6bcf", + "name": "pipeline.trigger_build.pipeline", + "source_type": "pipeline", + "source_uuid": "16f3b56f-4934-4546-923c-287859851332", + "target_type": "pipeline", + "target_uuid": "d07d5d84-d1bd-479c-902c-ce8a01ce5aac", + "effect": "allow", + "action": "trigger_build", + "created_at": "2024-08-26T03:22:45.555Z", + "created_by": { + "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de", + "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=", + "name": "Sam Kim", + "email": "sam@example.com", + "avatar_url": "https://www.gravatar.com/avatar/example", + "created_at": "2013-08-29T10:10:03.000Z" + } + } +] +``` + +Required scope: `read_rules` + +Success response: `200 OK` + +### Get a rule + +```bash +curl -H "Authorization: Bearer $TOKEN" \ + -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/rules/{uuid}" +``` + +```json +{ + "uuid": "42f1a7da-812d-4430-93d8-1cc7c33a6bcf", + "graphql_id": "Q2x1c3Rlci0tLTQyZjFhN2RhLTgxMmQtNDQzMC05M2Q4LTFjYzdjMzNhNmJjZg==", + "organization_uuid": "f02d6a6f-7a0e-481d-9d6d-89b427aec48d", + "url": "http://api.buildkite.com/v2/organizations/acme-inc/rules/42f1a7da-812d-4430-93d8-1cc7c33a6bcf", + "name": "pipeline.trigger_build.pipeline", + "source_type": "pipeline", + "source_uuid": "16f3b56f-4934-4546-923c-287859851332", + "target_type": "pipeline", + "target_uuid": "d07d5d84-d1bd-479c-902c-ce8a01ce5aac", + "effect": "allow", + "action": "trigger_build", + "created_at": "2024-08-26T03:22:45.555Z", + "created_by": { + "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de", + "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=", + "name": "Sam Kim", + "email": "sam@example.com", + "avatar_url": "https://www.gravatar.com/avatar/example", + "created_at": "2013-08-29T10:10:03.000Z" + } +} +``` + +Required scope: `read_rules` + +Success response: `200 OK` + +### Create a rule + +```bash +curl -H "Authorization: Bearer $TOKEN" \ + -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/rules" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "pipeline.trigger_build.pipeline", + "value": { + "triggering_pipeline_uuid": "16f3b56f-4934-4546-923c-287859851332", + "triggered_pipeline_uuid": "d07d5d84-d1bd-479c-902c-ce8a01ce5aac" + } + }' +``` + +```json +{ + "uuid": "42f1a7da-812d-4430-93d8-1cc7c33a6bcf", + "graphql_id": "Q2x1c3Rlci0tLTQyZjFhN2RhLTgxMmQtNDQzMC05M2Q4LTFjYzdjMzNhNmJjZg==", + "organization_uuid": "f02d6a6f-7a0e-481d-9d6d-89b427aec48d", + "url": "http://api.buildkite.com/v2/organizations/acme-inc/rules/42f1a7da-812d-4430-93d8-1cc7c33a6bcf", + "name": "pipeline.trigger_build.pipeline", + "source_type": "pipeline", + "source_uuid": "16f3b56f-4934-4546-923c-287859851332", + "target_type": "pipeline", + "target_uuid": "d07d5d84-d1bd-479c-902c-ce8a01ce5aac", + "effect": "allow", + "action": "trigger_build", + "created_at": "2024-08-26T03:22:45.555Z", + "created_by": { + "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de", + "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=", + "name": "Sam Kim", + "email": "sam@example.com", + "avatar_url": "https://www.gravatar.com/avatar/example", + "created_at": "2013-08-29T10:10:03.000Z" + } +} +``` + +Required [request body properties](/docs/api#request-body-properties): + + + + + + + + + + + + +
nameName of the rule. Must match one of the [available rule types](/docs/pipelines/rules#available-rule-types)
+ Example: "pipeline.trigger_build.pipeline"
valueA hash containing the value fields for the rule.
+ Example: {"triggering_pipeline_uuid": "16f3b56f-4934-4546-923c-287859851332", "triggered_pipeline_uuid": "d07d5d84-d1bd-479c-902c-ce8a01ce5aac"}
+ +Required scope: `write_rules` + +Success response: `201 Created` + +Error responses: + + + + + +
422 Unprocessable Entity{ "message": "Reason for failure" }
+ +### Delete a rule + +Delete a rule. + +```bash +curl -H "Authorization: Bearer $TOKEN" \ + -X DELETE "https://api.buildkite.com/v2/organizations/{org.slug}/rules/{id}" +``` + +Required scope: `write_rules` + +Success response: `204 No Content` + +Error responses: + + + + + +
422 Unprocessable Entity{ "message": "Reason the rule couldn't be deleted" }
+ From 44cc892f648c81ae3ffa373fd566214aa84d5e5d Mon Sep 17 00:00:00 2001 From: L Suzuki Date: Mon, 26 Aug 2024 17:06:08 +1200 Subject: [PATCH 13/39] Add rules to the nav, restructure into sections. --- data/nav.yml | 8 ++ pages/apis/rest_api/rules.md | 6 +- pages/clusters/overview.md | 2 +- pages/pipelines/rules.md | 137 -------------------------- pages/pipelines/rules/manage_rules.md | 128 ++++++++++++++++++++++++ pages/pipelines/rules/overview.md | 57 +++++++++++ 6 files changed, 197 insertions(+), 141 deletions(-) delete mode 100644 pages/pipelines/rules.md create mode 100644 pages/pipelines/rules/manage_rules.md create mode 100644 pages/pipelines/rules/overview.md diff --git a/data/nav.yml b/data/nav.yml index ea03e3de19..d45df7201a 100644 --- a/data/nav.yml +++ b/data/nav.yml @@ -326,6 +326,12 @@ path: "pipelines/hosted-agents/pipeline-migration" - name: "Terminal access" path: "pipelines/hosted-agents/terminal-access" + - name: "Rules" + children: + - name: "Overview" + path: "pipelines/rules/overview" + - name: "Manage rules" + path: "pipelines/rules/manage-rules" - name: "Security" children: - name: "Overview" @@ -566,6 +572,8 @@ path: "apis/rest-api/meta" - name: "Pipeline templates" path: "apis/rest-api/pipeline-templates" + - name: "Rules" + path: "apis/rest-api/rules" - name: "User" path: "apis/rest-api/user" - name: "Teams" diff --git a/pages/apis/rest_api/rules.md b/pages/apis/rest_api/rules.md index 438d8604fb..7053c8085c 100644 --- a/pages/apis/rest_api/rules.md +++ b/pages/apis/rest_api/rules.md @@ -4,7 +4,7 @@ The rules API lets you create and manage rules in your organization. ## Rules -[Rules](/docs/pipelines/rules) allow you to manage permissions between Buildkite resources. +[Rules](/docs/pipelines/rules/overview) allow you to manage permissions between Buildkite resources. A rule is used to specify that an action is allowed between a source resource (e.g. a pipeline) and a target resource (e.g. another pipeline). Rules allow you to break out of the defaults provided by Buildkite such as cluster boundaries. @@ -130,7 +130,7 @@ Required [request body properties](/docs/api#request-body-properties): name - Name of the rule. Must match one of the [available rule types](/docs/pipelines/rules#available-rule-types)
+ Name of the rule. Must match one of the [available rule types](/docs/pipelines/rules/overview#available-rule-types)
Example: "pipeline.trigger_build.pipeline" @@ -159,7 +159,7 @@ Delete a rule. ```bash curl -H "Authorization: Bearer $TOKEN" \ - -X DELETE "https://api.buildkite.com/v2/organizations/{org.slug}/rules/{id}" + -X DELETE "https://api.buildkite.com/v2/organizations/{org.slug}/rules/{uuid}" ``` Required scope: `write_rules` diff --git a/pages/clusters/overview.md b/pages/clusters/overview.md index 24e8f89eaf..804f04817f 100644 --- a/pages/clusters/overview.md +++ b/pages/clusters/overview.md @@ -33,7 +33,7 @@ You can create as many clusters as your require for your setup. Learn more about working with clusters in [Manage clusters](/docs/clusters/manage-clusters). > 📘 Pipeline triggering -> Pipelines associated with one cluster cannot trigger pipelines associated with another cluster, unless a [rule](/docs/pipelines/rules) has been created to explicitly allow triggering between pipelines in different clusters. +> Pipelines associated with one cluster cannot trigger pipelines associated with another cluster, unless a [rule](/docs/pipelines/rules/overview) has been created to explicitly allow triggering between pipelines in different clusters. ### How should I structure my queues diff --git a/pages/pipelines/rules.md b/pages/pipelines/rules.md deleted file mode 100644 index f495221cb6..0000000000 --- a/pages/pipelines/rules.md +++ /dev/null @@ -1,137 +0,0 @@ -# Rules - -Rules allow you to manage permissions between Buildkite resources. - -Rules express that an action is allowed between a source resource (e.g. a pipeline) and a target resource (e.g. another pipeline). - -Rules are typically used in tandem with [clusters](/docs/clusters/overview) to increase security and control, where clusters set hard boundaries and rules provide exceptions. - -## Available rule types - -### `pipeline.trigger_build.pipeline` - -Allows a pipeline in one cluster to trigger a pipeline in another cluster. - -Rule document: - -```json -{ - "rule": "pipeline.trigger_build.pipeline", - "value": { - "triggering_pipeline_uuid": "{triggering-pipeline-uuid}", - "triggered_pipeline_uuid": "{triggered-pipeline-uuid}" - } -} -``` - -Value fields: - -- `triggering_pipeline_uuid` The UUID of the pipeline that is allowed to trigger another pipeline. -- `triggered_pipeline_uuid` The UUID of the pipeline that is allowed to be triggered by the `triggering_pipeline_uuid` pipeline. - -#### Example use case - -Imagine you use two clusters to separate the environments necessary for building and deploying your application: a CI cluster and a CD cluster. Ordinarily, pipelines in these separate clusters are not able to trigger each other due to the isolation of clusters. - -A `pipeline.trigger_build.pipeline` rule would allow a pipeline in the CI cluster to trigger a build for a pipeline in the CD cluster, while maintaining the separation of the CI and CD agents in their respective clusters. - -### `pipeline.artifacts_read.pipeline` - -Allows a source pipeline in one cluster to read artifacts from a target pipeline in another cluster. - -Rule document: - -```json -{ - "rule": "pipeline.trigger_build.pipeline", - "value": { - "source_pipeline_uuid": "{uuid-of-source-pipeline}", - "target_pipeline_uuid": "{uuid-of-target-pipeline}" - } -} -``` - -Value fields: - -- `source_pipeline_uuid` The UUID of the pipeline that is allowed to read artifacts from another pipeline. -- `target_pipeline_uuid` The UUID of the pipeline that is allowed to have its artifacts read by jobs in the `source_pipeline_uuid` pipeline. - - -## Create a rule - -Organization admins can create new rules on the **Rules** page in **Organization settings**, as well as via the Buildkite REST API and GraphQL API. - -### Using the Buildkite UI - -To create a new rule using the Buildkite UI: - -1. Select **Settings** in the global navigation to access the **Organization settings** page. -2. Select **Rules** in the Pipelines section. -3. Select **New Rule**. -4. Under **Rule Name**, select the type of rule you want to create, such as `pipeline.trigger_build.pipeline`. -5. Under **Rule Document**, populate the relevant data. For example, if you're creating a `pipeline.trigger_build.pipeline` rule, you'll need to provide a `triggering_pipeline_uuid` and a `triggered_pipeline_uuid`. You can find the UUIDs of your pipelines on their **Settings** page under the **GraphQL API integration** section. -6. Select **Submit**. - -### Using the REST API - -To [create a new rule](/docs/apis/rest-api/rules#rules-create-a-rule) using the [REST API](/docs/apis/rest-api), run the following example `curl` command: - -```bash -curl -H "Authorization: Bearer $TOKEN" \ - -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/rules" \ - -H "Content-Type: application/json" \ - -d '{ - "rule": "pipeline.trigger_build.pipeline", - "value": { - "triggering_pipeline_uuid": "{uuid-of-triggering-pipeline}", - "triggered_pipeline_uuid": "{uuid-of-triggered-pipeline}" - } - }' -``` - -where: - -<%= render_markdown partial: 'apis/descriptions/rest_access_token' %> - -<%= render_markdown partial: 'apis/descriptions/rest_org_slug' %> - -## Using the GraphQL API - -To [create a new rule](/docs/apis/graphql-api/rules#rules-create-a-rule) using the [GraphQL API](/docs/apis/graphql-api), run the following example mutation: - -```graphql -mutation { - ruleCreate(input: { - organizationId: "organization-id", - name: "pipeline.trigger_build.pipeline", - value: "{\"triggering_pipeline_uuid\":\"{uuid-of-build-pipeline}\",\"triggered_pipeline_uuid\":\"{uuid-of-deploy-pipeline}\"}" - }) { - rule { - id - name - targetType - sourceType - source { - ... on Pipeline { - uuid - } - } - target { - ... on Pipeline { - uuid - } - } - effect - action - createdBy { - id - name - } - } - } -} -``` - -where: - -<%= render_markdown partial: 'apis/descriptions/graphql_organization_id' %> diff --git a/pages/pipelines/rules/manage_rules.md b/pages/pipelines/rules/manage_rules.md new file mode 100644 index 0000000000..d93188c4f6 --- /dev/null +++ b/pages/pipelines/rules/manage_rules.md @@ -0,0 +1,128 @@ +# Manage rules + +## Create a rule + +Organization admins can create new rules using the [**Rules** page in **Organization settings**](#create-a-rule-using-the-buildkite-ui), as well as via the Buildkite [REST API](#create-a-rule-using-the-rest-api) and [GraphQL API](#create-a-rule-using-the-graphql-api). + +### Using the Buildkite UI + +To create a new rule using the Buildkite UI: + +1. Select **Settings** in the global navigation to access the **Organization settings** page. +2. Select **Rules** in the Pipelines section. +3. Select **New Rule**. +4. Under **Rule Name**, select the type of rule you want to create, such as `pipeline.trigger_build.pipeline`. +5. Under **Rule Document**, populate the relevant data. For example, if you're creating a `pipeline.trigger_build.pipeline` rule, you'll need to provide a `triggering_pipeline_uuid` and a `triggered_pipeline_uuid`. You can find the UUIDs of your pipelines on their **Settings** page under the **GraphQL API integration** section. +6. Select **Submit**. + +### Using the REST API + +To [create a new rule](/docs/apis/rest-api/rules#rules-create-a-rule) using the [REST API](/docs/apis/rest-api), run the following example `curl` command: + +```bash +curl -H "Authorization: Bearer $TOKEN" \ + -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/rules" \ + -H "Content-Type: application/json" \ + -d '{ + "rule": "pipeline.trigger_build.pipeline", + "value": { + "triggering_pipeline_uuid": "{uuid-of-triggering-pipeline}", + "triggered_pipeline_uuid": "{uuid-of-triggered-pipeline}" + } + }' +``` + +where: + +<%= render_markdown partial: 'apis/descriptions/rest_access_token' %> + +<%= render_markdown partial: 'apis/descriptions/rest_org_slug' %> + +## Using the GraphQL API + +To [create a new rule](/docs/apis/graphql/schemas/mutation/rulecreate) using the [GraphQL API](/docs/apis/graphql-api), run the following example mutation: + +```graphql +mutation { + ruleCreate(input: { + organizationId: "organization-id", + name: "pipeline.trigger_build.pipeline", + value: "{\"triggering_pipeline_uuid\":\"{uuid-of-build-pipeline}\",\"triggered_pipeline_uuid\":\"{uuid-of-deploy-pipeline}\"}" + }) { + rule { + id + name + targetType + sourceType + source { + ... on Pipeline { + uuid + } + } + target { + ... on Pipeline { + uuid + } + } + effect + action + createdBy { + id + name + } + } + } +} +``` + +where: + +<%= render_markdown partial: 'apis/descriptions/graphql_organization_id' %> + +## Delete a rule + +Organization admins can delete rules using the [**Rules** page in **Organization settings**](#delete-a-rule-using-the-buildkite-ui), as well as via the Buildkite [REST API](#delete-a-rule-using-the-rest-api) and [GraphQL API](#delete-a-rule-using-the-graphql-api). + +### Using the Buildkite UI + +To delete a rule using the Buildkite UI: + +1. Select **Settings** in the global navigation to access the **Organization settings** page. +2. Select **Rules** in the Pipelines section. +3. Select the rule you wish to delete. +4. Select **Delete** + +### Using the REST API + +To [delete a rule](/docs/apis/rest-api/rules#rules-delete-a-rule) using the [REST API](/docs/apis/rest-api), run the following example `curl` command: + +```bash +curl -H "Authorization: Bearer $TOKEN" \ + -X DELETE "https://api.buildkite.com/v2/organizations/{org.slug}/rules/{uuid}" +``` + +where: + +<%= render_markdown partial: 'apis/descriptions/rest_access_token' %> + +<%= render_markdown partial: 'apis/descriptions/rest_org_slug' %> + +## Using the GraphQL API + +To [delete a rule](/docs/apis/graphql/schemas/mutation/ruledelete) using the [GraphQL API](/docs/apis/graphql-api), run the following example mutation: + +```graphql +mutation { + ruleDelete(input: { + organizationId: "organization-id", + id: "rule-id" + }) { + deletedRuleId + } +} +``` + +where: + +<%= render_markdown partial: 'apis/descriptions/graphql_organization_id' %> + diff --git a/pages/pipelines/rules/overview.md b/pages/pipelines/rules/overview.md new file mode 100644 index 0000000000..d79ec77e79 --- /dev/null +++ b/pages/pipelines/rules/overview.md @@ -0,0 +1,57 @@ +# Rules overview + +Rules allow you to manage permissions between Buildkite resources. + +Rules express that an action is allowed between a source resource (e.g. a pipeline) and a target resource (e.g. another pipeline). + +Rules are typically used in tandem with [clusters](/docs/clusters/overview) to increase security and control, where clusters set hard boundaries and rules provide exceptions. + +## Available rule types + +### `pipeline.trigger_build.pipeline` + +Allows a pipeline in one cluster to trigger a pipeline in another cluster. + +Rule document: + +```json +{ + "rule": "pipeline.trigger_build.pipeline", + "value": { + "triggering_pipeline_uuid": "{triggering-pipeline-uuid}", + "triggered_pipeline_uuid": "{triggered-pipeline-uuid}" + } +} +``` + +Value fields: + +- `triggering_pipeline_uuid` The UUID of the pipeline that is allowed to trigger another pipeline. +- `triggered_pipeline_uuid` The UUID of the pipeline that is allowed to be triggered by the `triggering_pipeline_uuid` pipeline. + +#### Example use case + +Imagine you use two clusters to separate the environments necessary for building and deploying your application: a CI cluster and a CD cluster. Ordinarily, pipelines in these separate clusters are not able to trigger each other due to the isolation of clusters. + +A `pipeline.trigger_build.pipeline` rule would allow a pipeline in the CI cluster to trigger a build for a pipeline in the CD cluster, while maintaining the separation of the CI and CD agents in their respective clusters. + +### `pipeline.artifacts_read.pipeline` + +Allows a source pipeline in one cluster to read artifacts from a target pipeline in another cluster. + +Rule document: + +```json +{ + "rule": "pipeline.trigger_build.pipeline", + "value": { + "source_pipeline_uuid": "{uuid-of-source-pipeline}", + "target_pipeline_uuid": "{uuid-of-target-pipeline}" + } +} +``` + +Value fields: + +- `source_pipeline_uuid` The UUID of the pipeline that is allowed to read artifacts from another pipeline. +- `target_pipeline_uuid` The UUID of the pipeline that is allowed to have its artifacts read by jobs in the `source_pipeline_uuid` pipeline. From 134ef8f4244f70d82e1afdecfb49f7620809563c Mon Sep 17 00:00:00 2001 From: L Suzuki Date: Tue, 27 Aug 2024 11:09:50 +1200 Subject: [PATCH 14/39] Add descriptions for finding pipeline and rule uuids for api calls --- pages/pipelines/rules/manage_rules.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/pages/pipelines/rules/manage_rules.md b/pages/pipelines/rules/manage_rules.md index d93188c4f6..abd614fc3a 100644 --- a/pages/pipelines/rules/manage_rules.md +++ b/pages/pipelines/rules/manage_rules.md @@ -38,6 +38,8 @@ where: <%= render_markdown partial: 'apis/descriptions/rest_org_slug' %> +<%= render_markdown partial: 'apis/descriptions/rest_pipeline_uuid' %> + ## Using the GraphQL API To [create a new rule](/docs/apis/graphql/schemas/mutation/rulecreate) using the [GraphQL API](/docs/apis/graphql-api), run the following example mutation: @@ -47,7 +49,7 @@ mutation { ruleCreate(input: { organizationId: "organization-id", name: "pipeline.trigger_build.pipeline", - value: "{\"triggering_pipeline_uuid\":\"{uuid-of-build-pipeline}\",\"triggered_pipeline_uuid\":\"{uuid-of-deploy-pipeline}\"}" + value: "{\"triggering_pipeline_uuid\":\"{uuid-of-source-pipeline}\",\"triggered_pipeline_uuid\":\"{uuid-of-target-pipeline}\"}" }) { rule { id @@ -79,6 +81,8 @@ where: <%= render_markdown partial: 'apis/descriptions/graphql_organization_id' %> +<%= render_markdown partial: 'apis/descriptions/rest_pipeline_uuid' %> + ## Delete a rule Organization admins can delete rules using the [**Rules** page in **Organization settings**](#delete-a-rule-using-the-buildkite-ui), as well as via the Buildkite [REST API](#delete-a-rule-using-the-rest-api) and [GraphQL API](#delete-a-rule-using-the-graphql-api). @@ -107,6 +111,8 @@ where: <%= render_markdown partial: 'apis/descriptions/rest_org_slug' %> +<%= render_markdown partial: 'apis/descriptions/rest_rule_uuid' %> + ## Using the GraphQL API To [delete a rule](/docs/apis/graphql/schemas/mutation/ruledelete) using the [GraphQL API](/docs/apis/graphql-api), run the following example mutation: @@ -125,4 +131,5 @@ mutation { where: <%= render_markdown partial: 'apis/descriptions/graphql_organization_id' %> - + +<%= render_markdown partial: 'apis/descriptions/graphql_rule_id' %> From d2a07750634da419b43c45106ad70fcef1772846 Mon Sep 17 00:00:00 2001 From: L Suzuki Date: Tue, 27 Aug 2024 11:10:06 +1200 Subject: [PATCH 15/39] Add descriptions for rule and pipeline uuids --- pages/apis/descriptions/_graphql_rule_id.md | 28 +++++++++++++++++++ .../apis/descriptions/_rest_pipeline_uuid.md | 24 ++++++++++++++++ pages/apis/descriptions/_rest_rule_uuid.md | 11 ++++++++ 3 files changed, 63 insertions(+) create mode 100644 pages/apis/descriptions/_graphql_rule_id.md create mode 100644 pages/apis/descriptions/_rest_pipeline_uuid.md create mode 100644 pages/apis/descriptions/_rest_rule_uuid.md diff --git a/pages/apis/descriptions/_graphql_rule_id.md b/pages/apis/descriptions/_graphql_rule_id.md new file mode 100644 index 0000000000..18f54f32e6 --- /dev/null +++ b/pages/apis/descriptions/_graphql_rule_id.md @@ -0,0 +1,28 @@ +- `ruleId` (required) can be obtained: + + * From the **Rules** section of your **Organization Settings** page, accessed by selecting **Settings** in the global navigation of your organization in Buildkite. + + * By running a [List rules](/docs/apis/graphql/cookbooks/rules#list-rules) GraphQL API query and obtaining this value from the `id` in the response associated with the rule type, source and target of the rule you wish to find (specified by the `name`, `source` and `target` values in the response). For example: + + ```graphql + query getRules { + organization(slug: "organization-slug") { + rules(first: 10) { + edges { + node { + id + name + source { + ... on Pipeline + slug + } + target { + ... on Pipeline + slug + } + } + } + } + } + } + ``` diff --git a/pages/apis/descriptions/_rest_pipeline_uuid.md b/pages/apis/descriptions/_rest_pipeline_uuid.md new file mode 100644 index 0000000000..36e13ff2a8 --- /dev/null +++ b/pages/apis/descriptions/_rest_pipeline_uuid.md @@ -0,0 +1,24 @@ +- `{pipeline.uuid}` can be obtained: + + * From the **Pipeline Settings** page of a given pipeline. To do this: + 1. Select **Pipelines** (in the global navigation) > the specific pipeline > **Settings**. + 1. Once on the **Pipeline Settings** page, copy the `UUID` value from the **GraphQL API Integration** section, which is the `{pipeline.uuid}` value. + + * By running a [Get pipeline](/docs/apis/rest-api/pipelines#get-a-pipeline) REST API query and obtaining this value from the `id` in the response. For example: + + ```bash + curl -H "Authorization: Bearer $TOKEN" \ + - X GET "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline.slug}" + ``` + + * By running a [Get pipeline](/docs/apis/graphql/schemas/query/pipeline) GraphQL API query and obtaining this value from the `uuid` in the response. For example: + + ```graphql + query getPipeline { + organization(slug: "organization-slug") { + pipeline(slug: "pipeline-slug") { + uuid + } + } + } + ``` diff --git a/pages/apis/descriptions/_rest_rule_uuid.md b/pages/apis/descriptions/_rest_rule_uuid.md new file mode 100644 index 0000000000..bdf3175b8f --- /dev/null +++ b/pages/apis/descriptions/_rest_rule_uuid.md @@ -0,0 +1,11 @@ +- `{rule.uuid}` can be obtained: + + * From the **Rules** section of your **Organization Settings** page, accessed by selecting **Settings** in the global navigation of your organization in Buildkite. + + * By running a [List rules](/docs/apis/rest-api/rules#list-rules) REST API query and obtaining this value from the `uuid` in the response associated with the rule type, source and target of the rule you wish to find (specified by the `name`, `source` and `target` values in the response). For example: + + ```bash + curl -H "Authorization: Bearer $TOKEN" \ + - X GET "https://api.buildkite.com/v2/organizations/{org.slug}/rules" + ``` + From e3d531bbc67e5a26195f7184a4b402da86c78c64 Mon Sep 17 00:00:00 2001 From: L Suzuki Date: Tue, 27 Aug 2024 11:10:13 +1200 Subject: [PATCH 16/39] Add cookbook for rules --- pages/apis/graphql/cookbooks/rules.md | 95 +++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 pages/apis/graphql/cookbooks/rules.md diff --git a/pages/apis/graphql/cookbooks/rules.md b/pages/apis/graphql/cookbooks/rules.md new file mode 100644 index 0000000000..954e397706 --- /dev/null +++ b/pages/apis/graphql/cookbooks/rules.md @@ -0,0 +1,95 @@ +# Rules + +A collection of common tasks with rules using the GraphQL API. + +You can test out the Buildkite GraphQL API using the [Buildkite explorer](https://graphql.buildkite.com/explorer). This includes built-in documentation under the **Docs** panel. + +## List rules + +Get the first 10 rules and their information for an organization: + +```graphql + query getRules { + organization(slug: "organization-slug") { + rules(first: 10) { + edges { + node { + id + name + targetType + sourceType + source { + ... on Pipeline + slug + } + target { + ... on Pipeline + slug + } + effect + action + createdBy { + id + name + } + } + } + } + } + } + ``` + +## Create a rule + +Create a rule: + +```graphql +mutation { + ruleCreate(input: { + organizationId: "organization-id", + name: "pipeline.trigger_build.pipeline", + value: "{\"triggering_pipeline_uuid\":\"{uuid-of-source-pipeline}\",\"triggered_pipeline_uuid\":\"{uuid-of-target-pipeline}\"}" + }) { + rule { + id + name + targetType + sourceType + source { + ... on Pipeline { + uuid + } + } + target { + ... on Pipeline { + uuid + } + } + effect + action + createdBy { + id + name + } + } + } +} +``` + +## Delete a rule + +Delete a rule: + +```graphql +mutation { + ruleDelete(input: { + organizationId: "organization-id", + id: "rule-id" + }) { + deletedRuleId + } +} +``` + + + From 45db920863390a38fb13407fb28910b193075edd Mon Sep 17 00:00:00 2001 From: L Suzuki Date: Tue, 27 Aug 2024 11:11:32 +1200 Subject: [PATCH 17/39] Add rule cookbook to graphql nav --- data/nav_graphql.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/data/nav_graphql.yml b/data/nav_graphql.yml index 512ea4fd01..d5a2fe2398 100644 --- a/data/nav_graphql.yml +++ b/data/nav_graphql.yml @@ -24,6 +24,8 @@ path: apis/graphql/cookbooks/pipelines - name: Pipeline templates path: apis/graphql/cookbooks/pipeline-templates + - name: Rules + path: apis/graphql/cookbooks/rules - name: Organizations path: apis/graphql/cookbooks/organizations - name: Teams From 9c700f9ab351b66a54147a65cd2bb65631a4d44a Mon Sep 17 00:00:00 2001 From: L Suzuki Date: Tue, 27 Aug 2024 11:16:31 +1200 Subject: [PATCH 18/39] UI -> interface --- pages/pipelines/rules/manage_rules.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/pipelines/rules/manage_rules.md b/pages/pipelines/rules/manage_rules.md index abd614fc3a..f6f7003089 100644 --- a/pages/pipelines/rules/manage_rules.md +++ b/pages/pipelines/rules/manage_rules.md @@ -4,7 +4,7 @@ Organization admins can create new rules using the [**Rules** page in **Organization settings**](#create-a-rule-using-the-buildkite-ui), as well as via the Buildkite [REST API](#create-a-rule-using-the-rest-api) and [GraphQL API](#create-a-rule-using-the-graphql-api). -### Using the Buildkite UI +### Using the Buildkite interface To create a new rule using the Buildkite UI: @@ -87,7 +87,7 @@ where: Organization admins can delete rules using the [**Rules** page in **Organization settings**](#delete-a-rule-using-the-buildkite-ui), as well as via the Buildkite [REST API](#delete-a-rule-using-the-rest-api) and [GraphQL API](#delete-a-rule-using-the-graphql-api). -### Using the Buildkite UI +### Using the Buildkite interface To delete a rule using the Buildkite UI: From bdc8bc769a93ff7c9320ae6f933a5fffa00a4739 Mon Sep 17 00:00:00 2001 From: L Suzuki Date: Tue, 27 Aug 2024 11:26:00 +1200 Subject: [PATCH 19/39] Run bundle exec rake graphql:generate --- data/nav_graphql.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/data/nav_graphql.yml b/data/nav_graphql.yml index d5a2fe2398..512ea4fd01 100644 --- a/data/nav_graphql.yml +++ b/data/nav_graphql.yml @@ -24,8 +24,6 @@ path: apis/graphql/cookbooks/pipelines - name: Pipeline templates path: apis/graphql/cookbooks/pipeline-templates - - name: Rules - path: apis/graphql/cookbooks/rules - name: Organizations path: apis/graphql/cookbooks/organizations - name: Teams From 6cfada1ee99c139f568937242827f84b31deb763 Mon Sep 17 00:00:00 2001 From: L Suzuki Date: Wed, 28 Aug 2024 11:24:38 +1200 Subject: [PATCH 20/39] Fix url links and typos, rename triggered/triggering to source/target, and rename name to type --- pages/apis/descriptions/_graphql_rule_id.md | 4 +- pages/apis/descriptions/_rest_rule_uuid.md | 2 +- pages/apis/graphql/cookbooks/rules.md | 14 +++--- pages/apis/rest_api/rules.md | 48 ++++++++++----------- pages/pipelines/rules/manage_rules.md | 22 +++++----- pages/pipelines/rules/overview.md | 10 ++--- 6 files changed, 50 insertions(+), 50 deletions(-) diff --git a/pages/apis/descriptions/_graphql_rule_id.md b/pages/apis/descriptions/_graphql_rule_id.md index 18f54f32e6..ea8538d60b 100644 --- a/pages/apis/descriptions/_graphql_rule_id.md +++ b/pages/apis/descriptions/_graphql_rule_id.md @@ -2,7 +2,7 @@ * From the **Rules** section of your **Organization Settings** page, accessed by selecting **Settings** in the global navigation of your organization in Buildkite. - * By running a [List rules](/docs/apis/graphql/cookbooks/rules#list-rules) GraphQL API query and obtaining this value from the `id` in the response associated with the rule type, source and target of the rule you wish to find (specified by the `name`, `source` and `target` values in the response). For example: + * By running a [List rules](/docs/apis/graphql/cookbooks/rules#list-rules) GraphQL API query and obtaining this value from the `id` in the response associated with the rule type, source and target of the rule you wish to find (specified by the `type`, `source` and `target` values in the response). For example: ```graphql query getRules { @@ -11,7 +11,7 @@ edges { node { id - name + type source { ... on Pipeline slug diff --git a/pages/apis/descriptions/_rest_rule_uuid.md b/pages/apis/descriptions/_rest_rule_uuid.md index bdf3175b8f..64b6e6b82d 100644 --- a/pages/apis/descriptions/_rest_rule_uuid.md +++ b/pages/apis/descriptions/_rest_rule_uuid.md @@ -2,7 +2,7 @@ * From the **Rules** section of your **Organization Settings** page, accessed by selecting **Settings** in the global navigation of your organization in Buildkite. - * By running a [List rules](/docs/apis/rest-api/rules#list-rules) REST API query and obtaining this value from the `uuid` in the response associated with the rule type, source and target of the rule you wish to find (specified by the `name`, `source` and `target` values in the response). For example: + * By running a [List rules](/docs/apis/rest-api/rules#rules-list-rules) REST API query and obtaining this value from the `uuid` in the response associated with the rule type, source and target of the rule you wish to find (specified by the `type`, `source` and `target` values in the response). For example: ```bash curl -H "Authorization: Bearer $TOKEN" \ diff --git a/pages/apis/graphql/cookbooks/rules.md b/pages/apis/graphql/cookbooks/rules.md index 954e397706..3a8b592270 100644 --- a/pages/apis/graphql/cookbooks/rules.md +++ b/pages/apis/graphql/cookbooks/rules.md @@ -6,7 +6,7 @@ You can test out the Buildkite GraphQL API using the [Buildkite explorer](https: ## List rules -Get the first 10 rules and their information for an organization: +Get the first 10 rules and their information for an organization. ```graphql query getRules { @@ -15,7 +15,7 @@ Get the first 10 rules and their information for an organization: edges { node { id - name + type targetType sourceType source { @@ -37,22 +37,22 @@ Get the first 10 rules and their information for an organization: } } } - ``` +``` ## Create a rule -Create a rule: +Create a rule. `value` must be a JSON encoded string. ```graphql mutation { ruleCreate(input: { organizationId: "organization-id", - name: "pipeline.trigger_build.pipeline", - value: "{\"triggering_pipeline_uuid\":\"{uuid-of-source-pipeline}\",\"triggered_pipeline_uuid\":\"{uuid-of-target-pipeline}\"}" + type: "pipeline.trigger_build.pipeline", + value: "{\"source_pipeline_uuid\":\"{uuid-of-source-pipeline}\",\"target_pipeline_uuid\":\"{uuid-of-target-pipeline}\"}" }) { rule { id - name + type targetType sourceType source { diff --git a/pages/apis/rest_api/rules.md b/pages/apis/rest_api/rules.md index 7053c8085c..9aecd618d1 100644 --- a/pages/apis/rest_api/rules.md +++ b/pages/apis/rest_api/rules.md @@ -6,7 +6,7 @@ The rules API lets you create and manage rules in your organization. [Rules](/docs/pipelines/rules/overview) allow you to manage permissions between Buildkite resources. -A rule is used to specify that an action is allowed between a source resource (e.g. a pipeline) and a target resource (e.g. another pipeline). Rules allow you to break out of the defaults provided by Buildkite such as cluster boundaries. +A rule is used to specify that an action is allowed between a source resource (e.g. a pipeline) and a target resource (e.g. another pipeline). Rules allow you to break out of the defaults provided by Buildkite such as the isolation between [clusters](/docs/clusters/overview). ### List rules @@ -20,27 +20,27 @@ curl -H "Authorization: Bearer $TOKEN" \ ```json [ { - "uuid": "42f1a7da-812d-4430-93d8-1cc7c33a6bcf", - "graphql_id": "Q2x1c3Rlci0tLTQyZjFhN2RhLTgxMmQtNDQzMC05M2Q4LTFjYzdjMzNhNmJjZg==", - "organization_uuid": "f02d6a6f-7a0e-481d-9d6d-89b427aec48d", - "url": "http://api.buildkite.com/v2/organizations/acme-inc/rules/42f1a7da-812d-4430-93d8-1cc7c33a6bcf", - "name": "pipeline.trigger_build.pipeline", - "source_type": "pipeline", - "source_uuid": "16f3b56f-4934-4546-923c-287859851332", - "target_type": "pipeline", - "target_uuid": "d07d5d84-d1bd-479c-902c-ce8a01ce5aac", - "effect": "allow", - "action": "trigger_build", - "created_at": "2024-08-26T03:22:45.555Z", - "created_by": { + "uuid": "42f1a7da-812d-4430-93d8-1cc7c33a6bcf", + "graphql_id": "Q2x1c3Rlci0tLTQyZjFhN2RhLTgxMmQtNDQzMC05M2Q4LTFjYzdjMzNhNmJjZg==", + "organization_uuid": "f02d6a6f-7a0e-481d-9d6d-89b427aec48d", + "url": "http://api.buildkite.com/v2/organizations/acme-inc/rules/42f1a7da-812d-4430-93d8-1cc7c33a6bcf", + "type": "pipeline.trigger_build.pipeline", + "source_type": "pipeline", + "source_uuid": "16f3b56f-4934-4546-923c-287859851332", + "target_type": "pipeline", + "target_uuid": "d07d5d84-d1bd-479c-902c-ce8a01ce5aac", + "effect": "allow", + "action": "trigger_build", + "created_at": "2024-08-26T03:22:45.555Z", + "created_by": { "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de", "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=", "name": "Sam Kim", "email": "sam@example.com", "avatar_url": "https://www.gravatar.com/avatar/example", "created_at": "2013-08-29T10:10:03.000Z" - } - } + } + } ] ``` @@ -61,7 +61,7 @@ curl -H "Authorization: Bearer $TOKEN" \ "graphql_id": "Q2x1c3Rlci0tLTQyZjFhN2RhLTgxMmQtNDQzMC05M2Q4LTFjYzdjMzNhNmJjZg==", "organization_uuid": "f02d6a6f-7a0e-481d-9d6d-89b427aec48d", "url": "http://api.buildkite.com/v2/organizations/acme-inc/rules/42f1a7da-812d-4430-93d8-1cc7c33a6bcf", - "name": "pipeline.trigger_build.pipeline", + "type": "pipeline.trigger_build.pipeline", "source_type": "pipeline", "source_uuid": "16f3b56f-4934-4546-923c-287859851332", "target_type": "pipeline", @@ -91,10 +91,10 @@ curl -H "Authorization: Bearer $TOKEN" \ -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/rules" \ -H "Content-Type: application/json" \ -d '{ - "name": "pipeline.trigger_build.pipeline", + "type": "pipeline.trigger_build.pipeline", "value": { - "triggering_pipeline_uuid": "16f3b56f-4934-4546-923c-287859851332", - "triggered_pipeline_uuid": "d07d5d84-d1bd-479c-902c-ce8a01ce5aac" + "source_pipeline_uuid": "16f3b56f-4934-4546-923c-287859851332", + "target_pipeline_uuid": "d07d5d84-d1bd-479c-902c-ce8a01ce5aac" } }' ``` @@ -105,7 +105,7 @@ curl -H "Authorization: Bearer $TOKEN" \ "graphql_id": "Q2x1c3Rlci0tLTQyZjFhN2RhLTgxMmQtNDQzMC05M2Q4LTFjYzdjMzNhNmJjZg==", "organization_uuid": "f02d6a6f-7a0e-481d-9d6d-89b427aec48d", "url": "http://api.buildkite.com/v2/organizations/acme-inc/rules/42f1a7da-812d-4430-93d8-1cc7c33a6bcf", - "name": "pipeline.trigger_build.pipeline", + "type": "pipeline.trigger_build.pipeline", "source_type": "pipeline", "source_uuid": "16f3b56f-4934-4546-923c-287859851332", "target_type": "pipeline", @@ -129,14 +129,14 @@ Required [request body properties](/docs/api#request-body-properties): - - + + Example:{"source_pipeline_uuid": "16f3b56f-4934-4546-923c-287859851332", "target_pipeline_uuid": "d07d5d84-d1bd-479c-902c-ce8a01ce5aac"}
nameName of the rule. Must match one of the [available rule types](/docs/pipelines/rules/overview#available-rule-types)
+ 		typeThe rule type. Must match one of the [available rule types](/docs/pipelines/rules/overview#available-rule-types)
Example: "pipeline.trigger_build.pipeline"
value A hash containing the value fields for the rule.
- Example: {"triggering_pipeline_uuid": "16f3b56f-4934-4546-923c-287859851332", "triggered_pipeline_uuid": "d07d5d84-d1bd-479c-902c-ce8a01ce5aac"}
diff --git a/pages/pipelines/rules/manage_rules.md b/pages/pipelines/rules/manage_rules.md index f6f7003089..599000eb7b 100644 --- a/pages/pipelines/rules/manage_rules.md +++ b/pages/pipelines/rules/manage_rules.md @@ -2,7 +2,7 @@ ## Create a rule -Organization admins can create new rules using the [**Rules** page in **Organization settings**](#create-a-rule-using-the-buildkite-ui), as well as via the Buildkite [REST API](#create-a-rule-using-the-rest-api) and [GraphQL API](#create-a-rule-using-the-graphql-api). +Organization admins can create new rules using the **Rules** page in **Organization settings**, as well as via the Buildkite [REST API](/docs/apis/rest-api) and [GraphQL API](/docs/apis/graphql-api). ### Using the Buildkite interface @@ -11,8 +11,8 @@ To create a new rule using the Buildkite UI: 1. Select **Settings** in the global navigation to access the **Organization settings** page. 2. Select **Rules** in the Pipelines section. 3. Select **New Rule**. -4. Under **Rule Name**, select the type of rule you want to create, such as `pipeline.trigger_build.pipeline`. -5. Under **Rule Document**, populate the relevant data. For example, if you're creating a `pipeline.trigger_build.pipeline` rule, you'll need to provide a `triggering_pipeline_uuid` and a `triggered_pipeline_uuid`. You can find the UUIDs of your pipelines on their **Settings** page under the **GraphQL API integration** section. +4. Under **Rule Type**, select the type of rule you want to create, such as `pipeline.trigger_build.pipeline`. +5. Under **Rule Document**, populate the relevant data. For example, if you're creating a `pipeline.trigger_build.pipeline` rule, you'll need to provide a `source_pipeline_uuid` and a `target_pipeline_uuid`. You can find the UUIDs of your pipelines on their **Settings** page under the **GraphQL API integration** section. 6. Select **Submit**. ### Using the REST API @@ -26,8 +26,8 @@ curl -H "Authorization: Bearer $TOKEN" \ -d '{ "rule": "pipeline.trigger_build.pipeline", "value": { - "triggering_pipeline_uuid": "{uuid-of-triggering-pipeline}", - "triggered_pipeline_uuid": "{uuid-of-triggered-pipeline}" + "source_pipeline_uuid": "{uuid-of-triggering-pipeline}", + "target_pipeline_uuid": "{uuid-of-target-pipeline}" } }' ``` @@ -40,7 +40,7 @@ where: <%= render_markdown partial: 'apis/descriptions/rest_pipeline_uuid' %> -## Using the GraphQL API +### Using the GraphQL API To [create a new rule](/docs/apis/graphql/schemas/mutation/rulecreate) using the [GraphQL API](/docs/apis/graphql-api), run the following example mutation: @@ -48,12 +48,12 @@ To [create a new rule](/docs/apis/graphql/schemas/mutation/rulecreate) using the mutation { ruleCreate(input: { organizationId: "organization-id", - name: "pipeline.trigger_build.pipeline", - value: "{\"triggering_pipeline_uuid\":\"{uuid-of-source-pipeline}\",\"triggered_pipeline_uuid\":\"{uuid-of-target-pipeline}\"}" + type: "pipeline.trigger_build.pipeline", + value: "{\"source_pipeline_uuid\":\"{uuid-of-source-pipeline}\",\"target_pipeline_uuid\":\"{uuid-of-target-pipeline}\"}" }) { rule { id - name + type targetType sourceType source { @@ -85,7 +85,7 @@ where: ## Delete a rule -Organization admins can delete rules using the [**Rules** page in **Organization settings**](#delete-a-rule-using-the-buildkite-ui), as well as via the Buildkite [REST API](#delete-a-rule-using-the-rest-api) and [GraphQL API](#delete-a-rule-using-the-graphql-api). +Organization admins can delete rules using the **Rules** page in **Organization settings**, as well as via the Buildkite [REST API](/docs/apis/rest-api) and [GraphQL API](/docs/apis/graphql-api). ### Using the Buildkite interface @@ -113,7 +113,7 @@ where: <%= render_markdown partial: 'apis/descriptions/rest_rule_uuid' %> -## Using the GraphQL API +### Using the GraphQL API To [delete a rule](/docs/apis/graphql/schemas/mutation/ruledelete) using the [GraphQL API](/docs/apis/graphql-api), run the following example mutation: diff --git a/pages/pipelines/rules/overview.md b/pages/pipelines/rules/overview.md index d79ec77e79..2756178640 100644 --- a/pages/pipelines/rules/overview.md +++ b/pages/pipelines/rules/overview.md @@ -4,7 +4,7 @@ Rules allow you to manage permissions between Buildkite resources. Rules express that an action is allowed between a source resource (e.g. a pipeline) and a target resource (e.g. another pipeline). -Rules are typically used in tandem with [clusters](/docs/clusters/overview) to increase security and control, where clusters set hard boundaries and rules provide exceptions. +Rules provide explicit access between resources, allowing granting or restricting access between resources that would normally be determined by the default permissions. ## Available rule types @@ -18,16 +18,16 @@ Rule document: { "rule": "pipeline.trigger_build.pipeline", "value": { - "triggering_pipeline_uuid": "{triggering-pipeline-uuid}", - "triggered_pipeline_uuid": "{triggered-pipeline-uuid}" + "source_pipeline_uuid": "{triggering-pipeline-uuid}", + "target_pipeline_uuid": "{triggered-pipeline-uuid}" } } ``` Value fields: -- `triggering_pipeline_uuid` The UUID of the pipeline that is allowed to trigger another pipeline. -- `triggered_pipeline_uuid` The UUID of the pipeline that is allowed to be triggered by the `triggering_pipeline_uuid` pipeline. +- `source_pipeline_uuid` The UUID of the pipeline that is allowed to trigger another pipeline. +- `target_pipeline_uuid` The UUID of the pipeline that is allowed to be triggered by the `source_pipeline_uuid` pipeline. #### Example use case From 8dcc18b3386ac176a9d290144043dad263834ced Mon Sep 17 00:00:00 2001 From: L Suzuki Date: Fri, 30 Aug 2024 11:25:55 +1200 Subject: [PATCH 21/39] Flesh out example use cases --- pages/pipelines/rules/overview.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/pages/pipelines/rules/overview.md b/pages/pipelines/rules/overview.md index 2756178640..9fc1eb85d8 100644 --- a/pages/pipelines/rules/overview.md +++ b/pages/pipelines/rules/overview.md @@ -1,16 +1,18 @@ # Rules overview -Rules allow you to manage permissions between Buildkite resources. +Rules allow you to customize permissions between Buildkite resources. -Rules express that an action is allowed between a source resource (e.g. a pipeline) and a target resource (e.g. another pipeline). +Rules express that an action (e.g. triggering a build) is allowed between a source resource (e.g. a pipeline) and a target resource (e.g. another pipeline). -Rules provide explicit access between resources, allowing granting or restricting access between resources that would normally be determined by the default permissions. +Rules are used to grant or restrict access between resources that would normally be determined by the default permissions. ## Available rule types ### `pipeline.trigger_build.pipeline` -Allows a pipeline in one cluster to trigger a pipeline in another cluster. +Allows one pipeline to trigger another. This is useful where you want to allow a pipeline to trigger a build in another cluster, or if you want to allow a public pipeline to trigger a private one. + +Note that this rule type overrides the usual [trigger step permissions checks](docs/pipelines/trigger-step#permissions) on users and teams. Rule document: @@ -29,11 +31,11 @@ Value fields: - `source_pipeline_uuid` The UUID of the pipeline that is allowed to trigger another pipeline. - `target_pipeline_uuid` The UUID of the pipeline that is allowed to be triggered by the `source_pipeline_uuid` pipeline. -#### Example use case +#### Example use case: cross-cluster pipeline triggering -Imagine you use two clusters to separate the environments necessary for building and deploying your application: a CI cluster and a CD cluster. Ordinarily, pipelines in these separate clusters are not able to trigger each other due to the isolation of clusters. +Clusters may be used to separate the environments necessary for building and deploying an application. For example, a CI pipeline in cluster A and a CD pipeline cluster B. Ordinarily, pipelines in separate clusters like this are not able to trigger builds for each other due to the strict isolation of clusters. -A `pipeline.trigger_build.pipeline` rule would allow a pipeline in the CI cluster to trigger a build for a pipeline in the CD cluster, while maintaining the separation of the CI and CD agents in their respective clusters. +A `pipeline.trigger_build.pipeline` rule would allow a trigger step in the CI pipeline in cluster A to target the CD pipeline in cluster B. This would allow deploys to be triggered upon a successful CI build, while still maintaining the separation of the CI and CD agents in their respective clusters. ### `pipeline.artifacts_read.pipeline` @@ -55,3 +57,7 @@ Value fields: - `source_pipeline_uuid` The UUID of the pipeline that is allowed to read artifacts from another pipeline. - `target_pipeline_uuid` The UUID of the pipeline that is allowed to have its artifacts read by jobs in the `source_pipeline_uuid` pipeline. + +#### Example use case: sharing assets between clusters + +By default, artifacts cannot be accessed by pipelines in separate clusters. For example, a deploy pipeline in cluster B cannot ordinarily access artifacts uploaded by a CI pipeline in cluster A. A `pipeline.artifacts_read.pipeline` rule can be used to override this. For example, frontend assets uploaded as artifacts by the CI pipeline would now be accessible to the deploy pipeline via the `buildkite-agent artifact download --build xxx` command. From cd0d595f259be13dd3ffe6be0987f2e98f81bf47 Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Fri, 30 Aug 2024 16:11:36 +1000 Subject: [PATCH 22/39] Fix broken links, renumber steps, and remove formatting from headings. --- pages/pipelines/rules/manage_rules.md | 15 ++++++++++----- pages/pipelines/rules/overview.md | 8 ++++---- 2 files changed, 14 insertions(+), 9 deletions(-) diff --git a/pages/pipelines/rules/manage_rules.md b/pages/pipelines/rules/manage_rules.md index 599000eb7b..ffc63e9909 100644 --- a/pages/pipelines/rules/manage_rules.md +++ b/pages/pipelines/rules/manage_rules.md @@ -9,11 +9,16 @@ Organization admins can create new rules using the **Rules** page in **Organizat To create a new rule using the Buildkite UI: 1. Select **Settings** in the global navigation to access the **Organization settings** page. -2. Select **Rules** in the Pipelines section. -3. Select **New Rule**. -4. Under **Rule Type**, select the type of rule you want to create, such as `pipeline.trigger_build.pipeline`. -5. Under **Rule Document**, populate the relevant data. For example, if you're creating a `pipeline.trigger_build.pipeline` rule, you'll need to provide a `source_pipeline_uuid` and a `target_pipeline_uuid`. You can find the UUIDs of your pipelines on their **Settings** page under the **GraphQL API integration** section. -6. Select **Submit**. + +1. Select **Rules** in the Pipelines section. + +1. Select **New Rule**. + +1. Under **Rule Type**, select the type of rule you want to create, such as `pipeline.trigger_build.pipeline`. + +1. Under **Rule Document**, populate the relevant data. For example, if you're creating a `pipeline.trigger_build.pipeline` rule, you'll need to provide a `source_pipeline_uuid` and a `target_pipeline_uuid`. You can find the UUIDs of your pipelines on their **Settings** page under the **GraphQL API integration** section. + +1. Select **Submit**. ### Using the REST API diff --git a/pages/pipelines/rules/overview.md b/pages/pipelines/rules/overview.md index 9fc1eb85d8..38a4813cdf 100644 --- a/pages/pipelines/rules/overview.md +++ b/pages/pipelines/rules/overview.md @@ -2,17 +2,17 @@ Rules allow you to customize permissions between Buildkite resources. -Rules express that an action (e.g. triggering a build) is allowed between a source resource (e.g. a pipeline) and a target resource (e.g. another pipeline). +Rules express that an action (for example, triggering a build) is allowed between a source resource (for example, a pipeline) and a target resource (for example, another pipeline). Rules are used to grant or restrict access between resources that would normally be determined by the default permissions. ## Available rule types -### `pipeline.trigger_build.pipeline` +### pipeline.trigger_build.pipeline Allows one pipeline to trigger another. This is useful where you want to allow a pipeline to trigger a build in another cluster, or if you want to allow a public pipeline to trigger a private one. -Note that this rule type overrides the usual [trigger step permissions checks](docs/pipelines/trigger-step#permissions) on users and teams. +Note that this rule type overrides the usual [trigger step permissions checks](/docs/pipelines/trigger-step#permissions) on users and teams. Rule document: @@ -37,7 +37,7 @@ Clusters may be used to separate the environments necessary for building and dep A `pipeline.trigger_build.pipeline` rule would allow a trigger step in the CI pipeline in cluster A to target the CD pipeline in cluster B. This would allow deploys to be triggered upon a successful CI build, while still maintaining the separation of the CI and CD agents in their respective clusters. -### `pipeline.artifacts_read.pipeline` +### pipeline.artifacts_read.pipeline Allows a source pipeline in one cluster to read artifacts from a target pipeline in another cluster. From fb19e4603b877fd2503349b868ee46cada92d17e Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Fri, 30 Aug 2024 17:10:04 +1000 Subject: [PATCH 23/39] Add Rules entry for GraphQL Cookbook and fix more linting issues. --- pages/apis/descriptions/_rest_rule_uuid.md | 1 - scripts/graphql_api_content/nav_data.rb | 4 ++++ vale/styles/Buildkite/h1-h6_sentence_case.yml | 2 ++ 3 files changed, 6 insertions(+), 1 deletion(-) diff --git a/pages/apis/descriptions/_rest_rule_uuid.md b/pages/apis/descriptions/_rest_rule_uuid.md index 64b6e6b82d..34d5fcde60 100644 --- a/pages/apis/descriptions/_rest_rule_uuid.md +++ b/pages/apis/descriptions/_rest_rule_uuid.md @@ -8,4 +8,3 @@ curl -H "Authorization: Bearer $TOKEN" \ - X GET "https://api.buildkite.com/v2/organizations/{org.slug}/rules" ``` - diff --git a/scripts/graphql_api_content/nav_data.rb b/scripts/graphql_api_content/nav_data.rb index 50728f0b8d..08dcb7ffdb 100644 --- a/scripts/graphql_api_content/nav_data.rb +++ b/scripts/graphql_api_content/nav_data.rb @@ -63,6 +63,10 @@ def generate_graphql_nav_data(type_sets) "name" => "Pipeline templates", "path" => "apis/graphql/cookbooks/pipeline-templates" }, + { + "name" => "Rules", + "path" => "apis/graphql/cookbooks/rules" + }, { "name" => "Organizations", "path" => "apis/graphql/cookbooks/organizations" diff --git a/vale/styles/Buildkite/h1-h6_sentence_case.yml b/vale/styles/Buildkite/h1-h6_sentence_case.yml index 525aa59e69..7b5397abe1 100644 --- a/vale/styles/Buildkite/h1-h6_sentence_case.yml +++ b/vale/styles/Buildkite/h1-h6_sentence_case.yml @@ -128,6 +128,8 @@ exceptions: - OS X - PagerDuty - Phabricator + - pipeline.artifacts_read.pipeline + - pipeline.trigger_build.pipeline - pipeline.yml - PowerShell - pytest From 66b105d6f122a9439349f4ae88ead123744a8cb6 Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Fri, 30 Aug 2024 17:20:25 +1000 Subject: [PATCH 24/39] Remove extra line endings from end of Rules GraphQL page. --- pages/apis/graphql/cookbooks/rules.md | 3 --- pages/apis/graphql/graphql_cookbook.md | 1 + 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/pages/apis/graphql/cookbooks/rules.md b/pages/apis/graphql/cookbooks/rules.md index 3a8b592270..7cb7e328f1 100644 --- a/pages/apis/graphql/cookbooks/rules.md +++ b/pages/apis/graphql/cookbooks/rules.md @@ -90,6 +90,3 @@ mutation { } } ``` - - - diff --git a/pages/apis/graphql/graphql_cookbook.md b/pages/apis/graphql/graphql_cookbook.md index b41f6f68e8..c601cea2c5 100644 --- a/pages/apis/graphql/graphql_cookbook.md +++ b/pages/apis/graphql/graphql_cookbook.md @@ -15,5 +15,6 @@ There are recipes for a range of different topics, including: - [Packages](/docs/apis/graphql/cookbooks/packages) - [Pipelines](/docs/apis/graphql/cookbooks/pipelines) - [Pipeline templates](/docs/apis/graphql/cookbooks/pipeline-templates) +- [] - [Organizations](/docs/apis/graphql/cookbooks/organizations) - [Teams](/docs/apis/graphql/cookbooks/teams) From 5bfacf778682be5f59f5468f8738f6b88ad8db9e Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Fri, 30 Aug 2024 17:22:04 +1000 Subject: [PATCH 25/39] Add missing link to GraphQL Cookbooks Overview page. --- pages/apis/graphql/graphql_cookbook.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/apis/graphql/graphql_cookbook.md b/pages/apis/graphql/graphql_cookbook.md index c601cea2c5..d154dd8710 100644 --- a/pages/apis/graphql/graphql_cookbook.md +++ b/pages/apis/graphql/graphql_cookbook.md @@ -15,6 +15,6 @@ There are recipes for a range of different topics, including: - [Packages](/docs/apis/graphql/cookbooks/packages) - [Pipelines](/docs/apis/graphql/cookbooks/pipelines) - [Pipeline templates](/docs/apis/graphql/cookbooks/pipeline-templates) -- [] +- [Rules](/docs/apis/graphql/cookbooks/rules) - [Organizations](/docs/apis/graphql/cookbooks/organizations) - [Teams](/docs/apis/graphql/cookbooks/teams) From 2c6282c2add992e6f193ffcfb8ec589f80ba8242 Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Fri, 30 Aug 2024 17:25:16 +1000 Subject: [PATCH 26/39] Ran rake to rebuild the GraphQL nav. --- data/nav_graphql.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/data/nav_graphql.yml b/data/nav_graphql.yml index 512ea4fd01..d5a2fe2398 100644 --- a/data/nav_graphql.yml +++ b/data/nav_graphql.yml @@ -24,6 +24,8 @@ path: apis/graphql/cookbooks/pipelines - name: Pipeline templates path: apis/graphql/cookbooks/pipeline-templates + - name: Rules + path: apis/graphql/cookbooks/rules - name: Organizations path: apis/graphql/cookbooks/organizations - name: Teams From 5158fbe8cadf49d402928f70945dfd779c5265ac Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Mon, 2 Sep 2024 09:31:59 +1000 Subject: [PATCH 27/39] Add spec test for Rules entry. --- spec/scripts/graphql_api_content/nav_data_spec.rb | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/spec/scripts/graphql_api_content/nav_data_spec.rb b/spec/scripts/graphql_api_content/nav_data_spec.rb index f4b7ac83d0..0db680dc79 100644 --- a/spec/scripts/graphql_api_content/nav_data_spec.rb +++ b/spec/scripts/graphql_api_content/nav_data_spec.rb @@ -341,6 +341,10 @@ "name" => "Pipeline templates", "path" => "apis/graphql/cookbooks/pipeline-templates" }, + { + "name" => "Rules", + "path" => "apis/graphql/cookbooks/rules" + }, { "name" => "Organizations", "path" => "apis/graphql/cookbooks/organizations" From 159304bca294e2ab7d6205788d83003c72a6ac3d Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Mon, 2 Sep 2024 17:09:51 +1000 Subject: [PATCH 28/39] Complete t/w review of rules overview page. --- data/nav.yml | 2 +- .../rules/{manage_rules.md => manage.md} | 0 pages/pipelines/rules/overview.md | 37 +++++++++++-------- 3 files changed, 23 insertions(+), 16 deletions(-) rename pages/pipelines/rules/{manage_rules.md => manage.md} (100%) diff --git a/data/nav.yml b/data/nav.yml index c83aae8eb8..48ab79333c 100644 --- a/data/nav.yml +++ b/data/nav.yml @@ -331,7 +331,7 @@ - name: "Overview" path: "pipelines/rules/overview" - name: "Manage rules" - path: "pipelines/rules/manage-rules" + path: "pipelines/rules/manage" - name: "Security" children: - name: "Overview" diff --git a/pages/pipelines/rules/manage_rules.md b/pages/pipelines/rules/manage.md similarity index 100% rename from pages/pipelines/rules/manage_rules.md rename to pages/pipelines/rules/manage.md diff --git a/pages/pipelines/rules/overview.md b/pages/pipelines/rules/overview.md index 38a4813cdf..8a25240e3d 100644 --- a/pages/pipelines/rules/overview.md +++ b/pages/pipelines/rules/overview.md @@ -6,15 +6,18 @@ Rules express that an action (for example, triggering a build) is allowed betwee Rules are used to grant or restrict access between resources that would normally be determined by the default permissions. -## Available rule types +## Rule types ### pipeline.trigger_build.pipeline -Allows one pipeline to trigger another. This is useful where you want to allow a pipeline to trigger a build in another cluster, or if you want to allow a public pipeline to trigger a private one. +This rule type: -Note that this rule type overrides the usual [trigger step permissions checks](/docs/pipelines/trigger-step#permissions) on users and teams. +- Allows one pipeline to trigger another. +- Is useful where you want to allow a pipeline to trigger a build in another cluster, or if you want to allow a public pipeline to trigger a private one. -Rule document: +**Note:** This rule type overrides the usual [trigger step permissions checks](/docs/pipelines/trigger-step#permissions) on users and teams. + +Rule format: ```json { @@ -26,22 +29,24 @@ Rule document: } ``` -Value fields: +where: + +- `source_pipeline_uuid` is the UUID of the pipeline that's allowed to trigger another pipeline. +- `target_pipeline_uuid` is the UUID of the pipeline that can be triggered by the `source_pipeline_uuid` pipeline. -- `source_pipeline_uuid` The UUID of the pipeline that is allowed to trigger another pipeline. -- `target_pipeline_uuid` The UUID of the pipeline that is allowed to be triggered by the `source_pipeline_uuid` pipeline. +Learn more about how to create rules in [Manage rules](/docs/pipelines/rules/manage). #### Example use case: cross-cluster pipeline triggering -Clusters may be used to separate the environments necessary for building and deploying an application. For example, a CI pipeline in cluster A and a CD pipeline cluster B. Ordinarily, pipelines in separate clusters like this are not able to trigger builds for each other due to the strict isolation of clusters. +Clusters may be used to separate the environments necessary for building and deploying an application. For example, a continuous integration (CI) pipeline has been set up in cluster A and likewise, a continuous deployment (CD) pipeline in cluster B. Ordinarily, pipelines in separate clusters are not able to trigger builds between each other due to the strict isolation of clusters. -A `pipeline.trigger_build.pipeline` rule would allow a trigger step in the CI pipeline in cluster A to target the CD pipeline in cluster B. This would allow deploys to be triggered upon a successful CI build, while still maintaining the separation of the CI and CD agents in their respective clusters. +However, a `pipeline.trigger_build.pipeline` rule would allow a trigger step in the CI pipeline of cluster A to target the CD pipeline in cluster B. Such rules would allow deployment to be triggered upon a successful CI build, while still maintaining the separation between the CI and CD agents in their respective clusters. ### pipeline.artifacts_read.pipeline -Allows a source pipeline in one cluster to read artifacts from a target pipeline in another cluster. +This rule type allows a source pipeline in one cluster to read artifacts from a target pipeline in another cluster. -Rule document: +Rule format: ```json { @@ -53,11 +58,13 @@ Rule document: } ``` -Value fields: +where: -- `source_pipeline_uuid` The UUID of the pipeline that is allowed to read artifacts from another pipeline. -- `target_pipeline_uuid` The UUID of the pipeline that is allowed to have its artifacts read by jobs in the `source_pipeline_uuid` pipeline. +- `source_pipeline_uuid` is the UUID of the pipeline that's allowed to read artifacts from another pipeline. +- `target_pipeline_uuid` is the UUID of the pipeline whose artifacts can be read by jobs in the `source_pipeline_uuid` pipeline. #### Example use case: sharing assets between clusters -By default, artifacts cannot be accessed by pipelines in separate clusters. For example, a deploy pipeline in cluster B cannot ordinarily access artifacts uploaded by a CI pipeline in cluster A. A `pipeline.artifacts_read.pipeline` rule can be used to override this. For example, frontend assets uploaded as artifacts by the CI pipeline would now be accessible to the deploy pipeline via the `buildkite-agent artifact download --build xxx` command. +Artifacts are not accessible between pipelines across different clusters. For example, a deployment pipeline in cluster B cannot ordinarily access artifacts uploaded by a CI pipeline in cluster A. + +However, a `pipeline.artifacts_read.pipeline` rule can be used to override this restriction. For example, frontend assets uploaded as artifacts by the CI pipeline would now be accessible to the deployment pipeline via the `buildkite-agent artifact download --build xxx` command. From 05db4215bd8c14f149e71053bcab7250a1587e61 Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Tue, 3 Sep 2024 12:03:11 +1000 Subject: [PATCH 29/39] Restructure rules landing page to remove '/overview' requirement from URL path, and tweak intro and 'create a rule' section of 'manage rules' page. --- data/nav.yml | 2 +- .../pipelines/{rules/overview.md => rules.md} | 18 ++++++++++-------- pages/pipelines/rules/manage.md | 16 ++++++++-------- 3 files changed, 19 insertions(+), 17 deletions(-) rename pages/pipelines/{rules/overview.md => rules.md} (86%) diff --git a/data/nav.yml b/data/nav.yml index 48ab79333c..45a4ba355d 100644 --- a/data/nav.yml +++ b/data/nav.yml @@ -329,7 +329,7 @@ - name: "Rules" children: - name: "Overview" - path: "pipelines/rules/overview" + path: "pipelines/rules" - name: "Manage rules" path: "pipelines/rules/manage" - name: "Security" diff --git a/pages/pipelines/rules/overview.md b/pages/pipelines/rules.md similarity index 86% rename from pages/pipelines/rules/overview.md rename to pages/pipelines/rules.md index 8a25240e3d..c2f673e06e 100644 --- a/pages/pipelines/rules/overview.md +++ b/pages/pipelines/rules.md @@ -17,14 +17,14 @@ This rule type: **Note:** This rule type overrides the usual [trigger step permissions checks](/docs/pipelines/trigger-step#permissions) on users and teams. -Rule format: +**Rule Document** format: ```json { "rule": "pipeline.trigger_build.pipeline", "value": { - "source_pipeline_uuid": "{triggering-pipeline-uuid}", - "target_pipeline_uuid": "{triggered-pipeline-uuid}" + "source_pipeline_uuid": "pipeline-uuid", + "target_pipeline_uuid": "pipeline-uuid" } } ``` @@ -34,7 +34,7 @@ where: - `source_pipeline_uuid` is the UUID of the pipeline that's allowed to trigger another pipeline. - `target_pipeline_uuid` is the UUID of the pipeline that can be triggered by the `source_pipeline_uuid` pipeline. -Learn more about how to create rules in [Manage rules](/docs/pipelines/rules/manage). +Learn more about creating rules in [Manage rules](/docs/pipelines/rules/manage). #### Example use case: cross-cluster pipeline triggering @@ -46,14 +46,14 @@ However, a `pipeline.trigger_build.pipeline` rule would allow a trigger step in This rule type allows a source pipeline in one cluster to read artifacts from a target pipeline in another cluster. -Rule format: +**Rule Document** format: ```json { - "rule": "pipeline.trigger_build.pipeline", + "rule": "pipeline.artifacts_read.pipeline", "value": { - "source_pipeline_uuid": "{uuid-of-source-pipeline}", - "target_pipeline_uuid": "{uuid-of-target-pipeline}" + "source_pipeline_uuid": "pipeline-uuid", + "target_pipeline_uuid": "pipeline-uuid" } } ``` @@ -63,6 +63,8 @@ where: - `source_pipeline_uuid` is the UUID of the pipeline that's allowed to read artifacts from another pipeline. - `target_pipeline_uuid` is the UUID of the pipeline whose artifacts can be read by jobs in the `source_pipeline_uuid` pipeline. +Learn more about creating rules in [Manage rules](/docs/pipelines/rules/manage). + #### Example use case: sharing assets between clusters Artifacts are not accessible between pipelines across different clusters. For example, a deployment pipeline in cluster B cannot ordinarily access artifacts uploaded by a CI pipeline in cluster A. diff --git a/pages/pipelines/rules/manage.md b/pages/pipelines/rules/manage.md index ffc63e9909..3fec61a6b6 100644 --- a/pages/pipelines/rules/manage.md +++ b/pages/pipelines/rules/manage.md @@ -1,22 +1,22 @@ # Manage rules +This page provides details on how to manage [rules](/docs/pipelines/rules) within your Buildkite organization. + ## Create a rule -Organization admins can create new rules using the **Rules** page in **Organization settings**, as well as via the Buildkite [REST API](/docs/apis/rest-api) and [GraphQL API](/docs/apis/graphql-api). +New rules can be created by [Buildkite organization administrators](/docs/team-management/permissions#manage-teams-and-permissions-organization-level-permissions) using the [**Rules** page](#create-a-rule-using-the-buildkite-interface), as well as the [REST API's](#create-a-rule-using-the-rest-api) or [GraphQL API's](#create-a-rule-using-the-graphql-api) create a rule feature. ### Using the Buildkite interface -To create a new rule using the Buildkite UI: - -1. Select **Settings** in the global navigation to access the **Organization settings** page. +To create a new rule using the Buildkite interface: -1. Select **Rules** in the Pipelines section. +1. Select **Settings** in the global navigation to access the [**Organization Settings**](https://buildkite.com/organizations/~/settings) page. -1. Select **New Rule**. +1. In the **Pipelines** section, select **Rules** > **New Rule** to open its page. -1. Under **Rule Type**, select the type of rule you want to create, such as `pipeline.trigger_build.pipeline`. +1. Under **Rule Template**, select the [type of rule](/docs/pipelines/rules#rule-types) to be created, that is, either **pipeline.trigger_build.pipeline** or **pipeline.artifacts_read.pipeline**. -1. Under **Rule Document**, populate the relevant data. For example, if you're creating a `pipeline.trigger_build.pipeline` rule, you'll need to provide a `source_pipeline_uuid` and a `target_pipeline_uuid`. You can find the UUIDs of your pipelines on their **Settings** page under the **GraphQL API integration** section. +1. Under **Rule Document**, specify the relevant `pipeline-uuid` (UUID) values for both the `source_pipeline_uuid` and `target_pipeline_uuid` pipelines, of your [**pipeline.trigger_build.pipeline**](/docs/pipelines/rules#rule-types-pipeline-dot-trigger-build-dot-pipeline) or or [**pipeline.artifacts_read.pipeline**](/docs/pipelines/rules#rule-types-pipeline-dot-artifacts-read-dot-pipeline) rule. You can find the UUID values for these pipelines on the pipelines' respective **Settings** page under the **GraphQL API integration** section. 1. Select **Submit**. From 36de2d43ba702fd5b7e8da3b0f746f622f941a55 Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Tue, 3 Sep 2024 13:46:05 +1000 Subject: [PATCH 30/39] Fix broken links. --- pages/apis/rest_api/rules.md | 4 ++-- pages/clusters/overview.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/pages/apis/rest_api/rules.md b/pages/apis/rest_api/rules.md index 9aecd618d1..ba9fe8c07d 100644 --- a/pages/apis/rest_api/rules.md +++ b/pages/apis/rest_api/rules.md @@ -4,7 +4,7 @@ The rules API lets you create and manage rules in your organization. ## Rules -[Rules](/docs/pipelines/rules/overview) allow you to manage permissions between Buildkite resources. +[Rules](/docs/pipelines/rules) allow you to manage permissions between Buildkite resources. A rule is used to specify that an action is allowed between a source resource (e.g. a pipeline) and a target resource (e.g. another pipeline). Rules allow you to break out of the defaults provided by Buildkite such as the isolation between [clusters](/docs/clusters/overview). @@ -130,7 +130,7 @@ Required [request body properties](/docs/api#request-body-properties): type - The rule type. Must match one of the [available rule types](/docs/pipelines/rules/overview#available-rule-types)
+ The rule type. Must match one of the [available rule types](/docs/pipelines/rules#available-rule-types)
Example: "pipeline.trigger_build.pipeline" diff --git a/pages/clusters/overview.md b/pages/clusters/overview.md index 804f04817f..24e8f89eaf 100644 --- a/pages/clusters/overview.md +++ b/pages/clusters/overview.md @@ -33,7 +33,7 @@ You can create as many clusters as your require for your setup. Learn more about working with clusters in [Manage clusters](/docs/clusters/manage-clusters). > 📘 Pipeline triggering -> Pipelines associated with one cluster cannot trigger pipelines associated with another cluster, unless a [rule](/docs/pipelines/rules/overview) has been created to explicitly allow triggering between pipelines in different clusters. +> Pipelines associated with one cluster cannot trigger pipelines associated with another cluster, unless a [rule](/docs/pipelines/rules) has been created to explicitly allow triggering between pipelines in different clusters. ### How should I structure my queues From d07d3786d372b05c33ed16ab45dc8c6fc51f49d1 Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Tue, 3 Sep 2024 17:05:49 +1000 Subject: [PATCH 31/39] Fix up Manage rules page. And a few more tweaks to the rules landing page. --- pages/apis/descriptions/_graphql_rule_id.md | 28 ---- pages/apis/descriptions/_rest_access_token.md | 2 +- .../apis/descriptions/_rest_pipeline_uuid.md | 24 --- pages/apis/descriptions/_rest_rule_uuid.md | 10 -- pages/clusters/manage_clusters.md | 4 +- pages/pipelines/rules.md | 22 ++- pages/pipelines/rules/manage.md | 137 +++++++++++++++--- 7 files changed, 137 insertions(+), 90 deletions(-) delete mode 100644 pages/apis/descriptions/_graphql_rule_id.md delete mode 100644 pages/apis/descriptions/_rest_pipeline_uuid.md delete mode 100644 pages/apis/descriptions/_rest_rule_uuid.md diff --git a/pages/apis/descriptions/_graphql_rule_id.md b/pages/apis/descriptions/_graphql_rule_id.md deleted file mode 100644 index ea8538d60b..0000000000 --- a/pages/apis/descriptions/_graphql_rule_id.md +++ /dev/null @@ -1,28 +0,0 @@ -- `ruleId` (required) can be obtained: - - * From the **Rules** section of your **Organization Settings** page, accessed by selecting **Settings** in the global navigation of your organization in Buildkite. - - * By running a [List rules](/docs/apis/graphql/cookbooks/rules#list-rules) GraphQL API query and obtaining this value from the `id` in the response associated with the rule type, source and target of the rule you wish to find (specified by the `type`, `source` and `target` values in the response). For example: - - ```graphql - query getRules { - organization(slug: "organization-slug") { - rules(first: 10) { - edges { - node { - id - type - source { - ... on Pipeline - slug - } - target { - ... on Pipeline - slug - } - } - } - } - } - } - ``` diff --git a/pages/apis/descriptions/_rest_access_token.md b/pages/apis/descriptions/_rest_access_token.md index e0ef385349..8eb70664bf 100644 --- a/pages/apis/descriptions/_rest_access_token.md +++ b/pages/apis/descriptions/_rest_access_token.md @@ -1 +1 @@ -- `$TOKEN` is an [API access token](https://buildkite.com/user/api-access-tokens) scoped to the relevant **Organization** and **REST API Scopes** that your agent needs access to in Buildkite. +- `$TOKEN` is an [API access token](https://buildkite.com/user/api-access-tokens) scoped to the relevant **Organization** and **REST API Scopes** that your request needs access to in Buildkite. diff --git a/pages/apis/descriptions/_rest_pipeline_uuid.md b/pages/apis/descriptions/_rest_pipeline_uuid.md deleted file mode 100644 index 36e13ff2a8..0000000000 --- a/pages/apis/descriptions/_rest_pipeline_uuid.md +++ /dev/null @@ -1,24 +0,0 @@ -- `{pipeline.uuid}` can be obtained: - - * From the **Pipeline Settings** page of a given pipeline. To do this: - 1. Select **Pipelines** (in the global navigation) > the specific pipeline > **Settings**. - 1. Once on the **Pipeline Settings** page, copy the `UUID` value from the **GraphQL API Integration** section, which is the `{pipeline.uuid}` value. - - * By running a [Get pipeline](/docs/apis/rest-api/pipelines#get-a-pipeline) REST API query and obtaining this value from the `id` in the response. For example: - - ```bash - curl -H "Authorization: Bearer $TOKEN" \ - - X GET "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline.slug}" - ``` - - * By running a [Get pipeline](/docs/apis/graphql/schemas/query/pipeline) GraphQL API query and obtaining this value from the `uuid` in the response. For example: - - ```graphql - query getPipeline { - organization(slug: "organization-slug") { - pipeline(slug: "pipeline-slug") { - uuid - } - } - } - ``` diff --git a/pages/apis/descriptions/_rest_rule_uuid.md b/pages/apis/descriptions/_rest_rule_uuid.md deleted file mode 100644 index 34d5fcde60..0000000000 --- a/pages/apis/descriptions/_rest_rule_uuid.md +++ /dev/null @@ -1,10 +0,0 @@ -- `{rule.uuid}` can be obtained: - - * From the **Rules** section of your **Organization Settings** page, accessed by selecting **Settings** in the global navigation of your organization in Buildkite. - - * By running a [List rules](/docs/apis/rest-api/rules#rules-list-rules) REST API query and obtaining this value from the `uuid` in the response associated with the rule type, source and target of the rule you wish to find (specified by the `type`, `source` and `target` values in the response). For example: - - ```bash - curl -H "Authorization: Bearer $TOKEN" \ - - X GET "https://api.buildkite.com/v2/organizations/{org.slug}/rules" - ``` diff --git a/pages/clusters/manage_clusters.md b/pages/clusters/manage_clusters.md index b49536b629..c9f7b5bcf4 100644 --- a/pages/clusters/manage_clusters.md +++ b/pages/clusters/manage_clusters.md @@ -352,7 +352,7 @@ where: 1. Select **Pipelines** in the global navigation > the specific pipeline to be moved to the cluster > **Settings**. 1. Copy the **ID** shown in the **GraphQL API Integration** section of this page, which is this `id` value. - * By running the `getCurrentUsersOrgs` GraphQL API query to obtain the organization slugs for the current user's accessible organizations, [getOrgPipelines](/docs/apis/graphql/schemas/query/organization) query to obtain the pipeline's `id` in the response. For example: + * By running the `getCurrentUsersOrgs` GraphQL API query to obtain the organization slugs for the current user's accessible organizations, then [getOrgPipelines](/docs/apis/graphql/schemas/query/organization) query to obtain the pipeline's `id` in the response. For example: Step 1. Run `getCurrentUsersOrgs` to obtain the organization slug values in the response for the current user's accessible organizations: @@ -383,7 +383,7 @@ where: uuid name } - } + } } } } diff --git a/pages/pipelines/rules.md b/pages/pipelines/rules.md index c2f673e06e..a64c4f020a 100644 --- a/pages/pipelines/rules.md +++ b/pages/pipelines/rules.md @@ -8,12 +8,17 @@ Rules are used to grant or restrict access between resources that would normally ## Rule types +Buildkite Pipelines supports two types of rules that allow one pipeline build to: + +- [Trigger another pipeline build](#rule-types-pipeline-dot-trigger-build-dot-pipeline). +- [Read the artifacts generated by another pipeline build](#rule-types-pipeline-dot-artifacts-read-dot-pipeline). + ### pipeline.trigger_build.pipeline -This rule type: +This rule type allows one pipeline to trigger another, where: -- Allows one pipeline to trigger another. -- Is useful where you want to allow a pipeline to trigger a build in another cluster, or if you want to allow a public pipeline to trigger a private one. +- Both pipelines are in the same or different [clusters](/docs/clusters/overview). +- One pipeline is public and another is private. **Note:** This rule type overrides the usual [trigger step permissions checks](/docs/pipelines/trigger-step#permissions) on users and teams. @@ -44,7 +49,10 @@ However, a `pipeline.trigger_build.pipeline` rule would allow a trigger step in ### pipeline.artifacts_read.pipeline -This rule type allows a source pipeline in one cluster to read artifacts from a target pipeline in another cluster. +This rule type allows one pipeline to access (that is, with read-only permissions) the artifacts built by another, where: + +- Both pipelines are in the same or different [clusters](/docs/clusters/overview). +- One pipeline is public and another is private. **Rule Document** format: @@ -60,8 +68,8 @@ This rule type allows a source pipeline in one cluster to read artifacts from a where: -- `source_pipeline_uuid` is the UUID of the pipeline that's allowed to read artifacts from another pipeline. -- `target_pipeline_uuid` is the UUID of the pipeline whose artifacts can be read by jobs in the `source_pipeline_uuid` pipeline. +- `source_pipeline_uuid` is the UUID of the pipeline that's allowed to access the artifacts from another pipeline. +- `target_pipeline_uuid` is the UUID of the pipeline whose artifacts can be accessed by jobs in the `source_pipeline_uuid` pipeline. Learn more about creating rules in [Manage rules](/docs/pipelines/rules/manage). @@ -69,4 +77,4 @@ Learn more about creating rules in [Manage rules](/docs/pipelines/rules/manage). Artifacts are not accessible between pipelines across different clusters. For example, a deployment pipeline in cluster B cannot ordinarily access artifacts uploaded by a CI pipeline in cluster A. -However, a `pipeline.artifacts_read.pipeline` rule can be used to override this restriction. For example, frontend assets uploaded as artifacts by the CI pipeline would now be accessible to the deployment pipeline via the `buildkite-agent artifact download --build xxx` command. +However, a `pipeline.artifacts_read.pipeline` rule can be used to override this restriction. For example, assets uploaded as artifacts by the CI pipeline would now be accessible to the deployment pipeline via the `buildkite-agent artifact download --build xxx` command. diff --git a/pages/pipelines/rules/manage.md b/pages/pipelines/rules/manage.md index 3fec61a6b6..b5643e4a95 100644 --- a/pages/pipelines/rules/manage.md +++ b/pages/pipelines/rules/manage.md @@ -14,12 +14,14 @@ To create a new rule using the Buildkite interface: 1. In the **Pipelines** section, select **Rules** > **New Rule** to open its page. -1. Under **Rule Template**, select the [type of rule](/docs/pipelines/rules#rule-types) to be created, that is, either **pipeline.trigger_build.pipeline** or **pipeline.artifacts_read.pipeline**. +1. Under **Rule Type**, select the [type of rule](/docs/pipelines/rules#rule-types) to be created, that is, either **pipeline.trigger_build.pipeline** or **pipeline.artifacts_read.pipeline**. -1. Under **Rule Document**, specify the relevant `pipeline-uuid` (UUID) values for both the `source_pipeline_uuid` and `target_pipeline_uuid` pipelines, of your [**pipeline.trigger_build.pipeline**](/docs/pipelines/rules#rule-types-pipeline-dot-trigger-build-dot-pipeline) or or [**pipeline.artifacts_read.pipeline**](/docs/pipelines/rules#rule-types-pipeline-dot-artifacts-read-dot-pipeline) rule. You can find the UUID values for these pipelines on the pipelines' respective **Settings** page under the **GraphQL API integration** section. +1. Under **Rule Document**, specify the relevant `pipeline-uuid` (UUID) values for both the `source_pipeline_uuid` and `target_pipeline_uuid` pipelines, of your [**pipeline.trigger_build.pipeline**](/docs/pipelines/rules#rule-types-pipeline-dot-trigger-build-dot-pipeline) or [**pipeline.artifacts_read.pipeline**](/docs/pipelines/rules#rule-types-pipeline-dot-artifacts-read-dot-pipeline) rule. You can find the UUID values for these pipelines on the pipelines' respective **Settings** page under the **GraphQL API integration** section. 1. Select **Submit**. + The rule is created and presented on the **Rules** page, with a description of the rule type and the relationship between both pipelines. + ### Using the REST API To [create a new rule](/docs/apis/rest-api/rules#rules-create-a-rule) using the [REST API](/docs/apis/rest-api), run the following example `curl` command: @@ -31,8 +33,8 @@ curl -H "Authorization: Bearer $TOKEN" \ -d '{ "rule": "pipeline.trigger_build.pipeline", "value": { - "source_pipeline_uuid": "{uuid-of-triggering-pipeline}", - "target_pipeline_uuid": "{uuid-of-target-pipeline}" + "source_pipeline_uuid": "{pipeline.uuid}", + "target_pipeline_uuid": "{pipeline.uuid}" } }' ``` @@ -43,18 +45,31 @@ where: <%= render_markdown partial: 'apis/descriptions/rest_org_slug' %> -<%= render_markdown partial: 'apis/descriptions/rest_pipeline_uuid' %> +- `rule` is the [type of rule](/docs/pipelines/rules#rule-types) to be created, that is, either `pipeline.trigger_build.pipeline` or `pipeline.artifacts_read.pipeline`. + +- `{pipeline.uuid}` value for `source_pipeline_uuid` and `target_pipeline_uuid` can be obtained: + + * From the **Pipeline Settings** page of the appropriate pipeline. To do this: + 1. Select **Pipelines** (in the global navigation) > the specific pipeline > **Settings**. + 1. Once on the **Pipeline Settings** page, copy the `UUID` value from the **GraphQL API Integration** section, which is the `{pipeline.uuid}` value. + + * By running the [List pipelines](/docs/apis/rest-api/pipelines#list-pipelines) REST API query to obtain this value from `id` in the response from the specific pipeline. For example: + + ```bash + curl -H "Authorization: Bearer $TOKEN" \ + - X GET "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines" + ``` ### Using the GraphQL API -To [create a new rule](/docs/apis/graphql/schemas/mutation/rulecreate) using the [GraphQL API](/docs/apis/graphql-api), run the following example mutation: +To [create a new rule](/docs/apis/graphql/cookbooks/rules#create-a-rule) using the [GraphQL API](/docs/apis/graphql-api), run the following example mutation: ```graphql mutation { ruleCreate(input: { organizationId: "organization-id", type: "pipeline.trigger_build.pipeline", - value: "{\"source_pipeline_uuid\":\"{uuid-of-source-pipeline}\",\"target_pipeline_uuid\":\"{uuid-of-target-pipeline}\"}" + value: "{\"source_pipeline_uuid\":\"pipeline-uuid\",\"target_pipeline_uuid\":\"pipeline-uuid\"}" }) { rule { id @@ -86,20 +101,66 @@ where: <%= render_markdown partial: 'apis/descriptions/graphql_organization_id' %> -<%= render_markdown partial: 'apis/descriptions/rest_pipeline_uuid' %> +- `type` is the [type of rule](/docs/pipelines/rules#rule-types) to be created, that is, either `pipeline.trigger_build.pipeline` or `pipeline.artifacts_read.pipeline`. + +- `pipeline-uuid` value for `source_pipeline_uuid` and `target_pipeline_uuid` can be obtained: + + * From the **Pipeline Settings** page of the appropriate pipeline. To do this: + 1. Select **Pipelines** (in the global navigation) > the specific pipeline > **Settings**. + 1. Once on the **Pipeline Settings** page, copy the `UUID` value from the **GraphQL API Integration** section, which is the `pipeline-uuid` value. + + * By running the `getCurrentUsersOrgs` GraphQL API query to obtain the organization slugs for the current user's accessible organizations, then [getOrgPipelines](/docs/apis/graphql/schemas/query/organization) query to obtain the pipeline's `uuid` in the response. For example: + + Step 1. Run `getCurrentUsersOrgs` to obtain the organization slug values in the response for the current user's accessible organizations: + + ```graphql + query getCurrentUsersOrgs { + viewer { + organization { + edges { + node { + name + slug + } + } + } + } + } + ``` + + Step 2. Run `getOrgPipelines` with the appropriate slug value above to obtain this organization's `uuid` in the response: + + ```graphql + query getOrgPipelines { + organization(slug: "organization-slug") { + pipelines(first: 100) { + edges { + node { + id + uuid + name + } + } + } + } + } + ``` ## Delete a rule -Organization admins can delete rules using the **Rules** page in **Organization settings**, as well as via the Buildkite [REST API](/docs/apis/rest-api) and [GraphQL API](/docs/apis/graphql-api). +Rules can be deleted by [Buildkite organization administrators](/docs/team-management/permissions#manage-teams-and-permissions-organization-level-permissions) using the [**Rules** page](#delete-a-rule-using-the-buildkite-interface), as well as the [REST API's](#delete-a-rule-using-the-rest-api) or [GraphQL API's](#delete-a-rule-using-the-graphql-api) delete a rule feature. ### Using the Buildkite interface -To delete a rule using the Buildkite UI: +To delete a rule using the Buildkite interface: + +1. Select **Settings** in the global navigation to access the [**Organization Settings**](https://buildkite.com/organizations/~/settings) page. + +1. In the **Pipelines** section, select **Rules** to access its page. + +1. Expand the existing rule to be deleted. -1. Select **Settings** in the global navigation to access the **Organization settings** page. -2. Select **Rules** in the Pipelines section. -3. Select the rule you wish to delete. -4. Select **Delete** +1. Select the **Delete** button to delete this rule. ### Using the REST API @@ -107,7 +168,7 @@ To [delete a rule](/docs/apis/rest-api/rules#rules-delete-a-rule) using the [RES ```bash curl -H "Authorization: Bearer $TOKEN" \ - -X DELETE "https://api.buildkite.com/v2/organizations/{org.slug}/rules/{uuid}" + -X DELETE "https://api.buildkite.com/v2/organizations/{org.slug}/rules/{rule.uuid}" ``` where: @@ -116,11 +177,22 @@ where: <%= render_markdown partial: 'apis/descriptions/rest_org_slug' %> -<%= render_markdown partial: 'apis/descriptions/rest_rule_uuid' %> +- `{rule.uuid}` can be obtained: + + * From the **Rules** section of your **Organization Settings** page, accessed by selecting **Settings** in the global navigation of your organization in Buildkite. + + * By running a [List rules](/docs/apis/rest-api/rules#rules-list-rules) REST API query to obtain the rule's `uuid` in the response. For example: + + ```bash + curl -H "Authorization: Bearer $TOKEN" \ + - X GET "https://api.buildkite.com/v2/organizations/{org.slug}/rules" + ``` + + **Important:** For the rule identified by its `uuid` in the response, ensure the pipeline UUIDs of the source (`source_uuid`) and target (`target_uuid`), as well as the rule type (`type`) match those of this rule to be deleted. ### Using the GraphQL API -To [delete a rule](/docs/apis/graphql/schemas/mutation/ruledelete) using the [GraphQL API](/docs/apis/graphql-api), run the following example mutation: +To [delete a rule](/docs/apis/graphql/cookbooks/rules#delete-a-rule) using the [GraphQL API](/docs/apis/graphql-api), run the following example mutation: ```graphql mutation { @@ -137,4 +209,33 @@ where: <%= render_markdown partial: 'apis/descriptions/graphql_organization_id' %> -<%= render_markdown partial: 'apis/descriptions/graphql_rule_id' %> +- `id` is the rule ID value, which can be obtained: + + * From the **Rules** section of your **Organization Settings** page, accessed by selecting **Settings** in the global navigation of your organization in Buildkite. + + * By running a [List rules](/docs/apis/graphql/cookbooks/rules#list-rules) GraphQL API query to obtain the rule's `id` in the response. For example: + + ```graphql + query getRules { + organization(slug: "organization-slug") { + rules(first: 10) { + edges { + node { + id + type + source { + ... on Pipeline + slug + } + target { + ... on Pipeline + slug + } + } + } + } + } + } + ``` + + **Important:** For the rule identified by its `uuid` in the response, ensure the pipeline UUIDs of the source (`source_uuid`) and target (`target_uuid`), as well as the rule type (`type`) match those of this rule to be deleted. From f3417496643cf8b43158e0b6984ac7e6e2fd62cf Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Tue, 3 Sep 2024 17:08:41 +1000 Subject: [PATCH 32/39] Fix pedantic linter. --- pages/pipelines/rules/manage.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/pipelines/rules/manage.md b/pages/pipelines/rules/manage.md index b5643e4a95..6eb0f4d317 100644 --- a/pages/pipelines/rules/manage.md +++ b/pages/pipelines/rules/manage.md @@ -188,7 +188,7 @@ where: - X GET "https://api.buildkite.com/v2/organizations/{org.slug}/rules" ``` - **Important:** For the rule identified by its `uuid` in the response, ensure the pipeline UUIDs of the source (`source_uuid`) and target (`target_uuid`), as well as the rule type (`type`) match those of this rule to be deleted. + **Important:** For the rule identified by its `uuid` in the response, ensure the pipeline UUIDs of the source (`source_uuid`) and target (`target_uuid`), as well as the rule type (`type`) match those of this rule to be deleted. ### Using the GraphQL API @@ -238,4 +238,4 @@ where: } ``` - **Important:** For the rule identified by its `uuid` in the response, ensure the pipeline UUIDs of the source (`source_uuid`) and target (`target_uuid`), as well as the rule type (`type`) match those of this rule to be deleted. + **Important:** For the rule identified by its `uuid` in the response, ensure the pipeline UUIDs of the source (`source_uuid`) and target (`target_uuid`), as well as the rule type (`type`) match those of this rule to be deleted. From bcd919332529e79988d9f4c7462b4c4243f1fe68 Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Wed, 4 Sep 2024 14:48:47 +1000 Subject: [PATCH 33/39] Final tweaks to rules' feature's API pages. Fix GraphQL query syntax error in listing orgs. --- .../apis/descriptions/_graphql_organization_id.md | 2 +- pages/apis/graphql/cookbooks/rules.md | 14 ++++++++------ pages/apis/rest_api/rules.md | 12 ++++++++---- pages/pipelines/_rules_summary.md | 5 +++++ pages/pipelines/rules.md | 6 ++---- pages/pipelines/rules/manage.md | 6 ++++-- 6 files changed, 28 insertions(+), 17 deletions(-) create mode 100644 pages/pipelines/_rules_summary.md diff --git a/pages/apis/descriptions/_graphql_organization_id.md b/pages/apis/descriptions/_graphql_organization_id.md index 3ee90a67cf..ab69ea84a5 100644 --- a/pages/apis/descriptions/_graphql_organization_id.md +++ b/pages/apis/descriptions/_graphql_organization_id.md @@ -9,7 +9,7 @@ ```graphql query getCurrentUsersOrgs { viewer { - organization { + organizations { edges { node { name diff --git a/pages/apis/graphql/cookbooks/rules.md b/pages/apis/graphql/cookbooks/rules.md index 7cb7e328f1..c809b1bf65 100644 --- a/pages/apis/graphql/cookbooks/rules.md +++ b/pages/apis/graphql/cookbooks/rules.md @@ -19,12 +19,14 @@ Get the first 10 rules and their information for an organization. targetType sourceType source { - ... on Pipeline + ... on Pipeline { slug + } } target { - ... on Pipeline + ... on Pipeline { slug + } } effect action @@ -41,7 +43,7 @@ Get the first 10 rules and their information for an organization. ## Create a rule -Create a rule. `value` must be a JSON encoded string. +Create a rule. The value of the `value` field must be a JSON-encoded string. ```graphql mutation { @@ -56,10 +58,10 @@ mutation { targetType sourceType source { - ... on Pipeline { - uuid - } + ... on Pipeline { + uuid } + } target { ... on Pipeline { uuid diff --git a/pages/apis/rest_api/rules.md b/pages/apis/rest_api/rules.md index ba9fe8c07d..4efe4f9a77 100644 --- a/pages/apis/rest_api/rules.md +++ b/pages/apis/rest_api/rules.md @@ -4,9 +4,9 @@ The rules API lets you create and manage rules in your organization. ## Rules -[Rules](/docs/pipelines/rules) allow you to manage permissions between Buildkite resources. +[Rules](/docs/pipelines/rules) do the following: -A rule is used to specify that an action is allowed between a source resource (e.g. a pipeline) and a target resource (e.g. another pipeline). Rules allow you to break out of the defaults provided by Buildkite such as the isolation between [clusters](/docs/clusters/overview). +<%= render_markdown partial: 'pipelines/rules_summary' %> ### List rules @@ -130,8 +130,12 @@ Required [request body properties](/docs/api#request-body-properties): type - The rule type. Must match one of the [available rule types](/docs/pipelines/rules#available-rule-types)
- Example: "pipeline.trigger_build.pipeline" + The rule type. Must match one of the available rule types.
+ Example: +
    +
  • "pipeline.trigger_build.pipeline"
    or
    • +
  • "pipeline.artifacts_read.pipeline"
    • + value diff --git a/pages/pipelines/_rules_summary.md b/pages/pipelines/_rules_summary.md new file mode 100644 index 0000000000..ceab3e2d1a --- /dev/null +++ b/pages/pipelines/_rules_summary.md @@ -0,0 +1,5 @@ +- Allow you to manage access to interactions between Buildkite resources. + +- Allow an action (for example, triggering a build) between a source resource (for example, a pipeline) and a target resource (for example, another pipeline) across your Buildkite organization. + +- Are used to grant access between resources that would normally be restricted by [cluster](/docs/clusters/overview), [visibility](/docs/pipelines/public-pipelines), or [permissions](/docs/team-management/permissions). diff --git a/pages/pipelines/rules.md b/pages/pipelines/rules.md index a64c4f020a..33d50bcc72 100644 --- a/pages/pipelines/rules.md +++ b/pages/pipelines/rules.md @@ -1,10 +1,8 @@ # Rules overview -Rules allow you to customize permissions between Buildkite resources. +Rules do the following: -Rules express that an action (for example, triggering a build) is allowed between a source resource (for example, a pipeline) and a target resource (for example, another pipeline). - -Rules are used to grant or restrict access between resources that would normally be determined by the default permissions. +<%= render_markdown partial: 'pipelines/rules_summary' %> ## Rule types diff --git a/pages/pipelines/rules/manage.md b/pages/pipelines/rules/manage.md index 6eb0f4d317..6a90c4edc8 100644 --- a/pages/pipelines/rules/manage.md +++ b/pages/pipelines/rules/manage.md @@ -224,12 +224,14 @@ where: id type source { - ... on Pipeline + ... on Pipeline { slug + } } target { - ... on Pipeline + ... on Pipeline { slug + } } } } From 0c10f0edb184bff6c8e296f002fe048f8dcb2125 Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Wed, 4 Sep 2024 15:02:19 +1000 Subject: [PATCH 34/39] Streamline rules intro a little more. --- pages/pipelines/_rules_summary.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/pages/pipelines/_rules_summary.md b/pages/pipelines/_rules_summary.md index ceab3e2d1a..dda32b90b6 100644 --- a/pages/pipelines/_rules_summary.md +++ b/pages/pipelines/_rules_summary.md @@ -1,5 +1,3 @@ -- Allow you to manage access to interactions between Buildkite resources. +- Grant access between Buildkite resources that would normally be restricted by [cluster](/docs/clusters/overview), [visibility](/docs/pipelines/public-pipelines), or [permissions](/docs/team-management/permissions). - Allow an action (for example, triggering a build) between a source resource (for example, a pipeline) and a target resource (for example, another pipeline) across your Buildkite organization. - -- Are used to grant access between resources that would normally be restricted by [cluster](/docs/clusters/overview), [visibility](/docs/pipelines/public-pipelines), or [permissions](/docs/team-management/permissions). From 472eaa5b9c9d813946dd4d38bf5805d026268bc6 Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Wed, 4 Sep 2024 15:06:07 +1000 Subject: [PATCH 35/39] More intro tweaks and fix another typo in GraphQL query. --- pages/apis/rest_api/rules.md | 2 +- pages/pipelines/rules.md | 2 +- pages/pipelines/rules/manage.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/pages/apis/rest_api/rules.md b/pages/apis/rest_api/rules.md index 4efe4f9a77..f786c32a42 100644 --- a/pages/apis/rest_api/rules.md +++ b/pages/apis/rest_api/rules.md @@ -4,7 +4,7 @@ The rules API lets you create and manage rules in your organization. ## Rules -[Rules](/docs/pipelines/rules) do the following: +[_Rules_](/docs/pipelines/rules) is a Buildkite feature that can do the following: <%= render_markdown partial: 'pipelines/rules_summary' %> diff --git a/pages/pipelines/rules.md b/pages/pipelines/rules.md index 33d50bcc72..6438ac712c 100644 --- a/pages/pipelines/rules.md +++ b/pages/pipelines/rules.md @@ -1,6 +1,6 @@ # Rules overview -Rules do the following: +_Rules_ is a Buildkite feature that can do the following: <%= render_markdown partial: 'pipelines/rules_summary' %> diff --git a/pages/pipelines/rules/manage.md b/pages/pipelines/rules/manage.md index 6a90c4edc8..094b8c5bdd 100644 --- a/pages/pipelines/rules/manage.md +++ b/pages/pipelines/rules/manage.md @@ -116,7 +116,7 @@ where: ```graphql query getCurrentUsersOrgs { viewer { - organization { + organizations { edges { node { name From 0791802d532098c8247098c0cfbc888e6780c881 Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Thu, 5 Sep 2024 10:17:34 +1000 Subject: [PATCH 36/39] Add 'early access' note to top of Rules overview page. --- pages/pipelines/rules.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/pages/pipelines/rules.md b/pages/pipelines/rules.md index 6438ac712c..a6e37e4d83 100644 --- a/pages/pipelines/rules.md +++ b/pages/pipelines/rules.md @@ -4,6 +4,9 @@ _Rules_ is a Buildkite feature that can do the following: <%= render_markdown partial: 'pipelines/rules_summary' %> +> 📘 +> The _rules_ feature is currently in development and is enabled on an opt-in basis for early access. To enable rules your organization, please contact Buildkite's [Support team](https://buildkite.com/support). + ## Rule types Buildkite Pipelines supports two types of rules that allow one pipeline build to: From b8216993d266d471e1750c0e597c78aa3512a309 Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Thu, 5 Sep 2024 10:34:13 +1000 Subject: [PATCH 37/39] Fix terminology around hash > JSON object, and tweak early access note for rules slightly. --- pages/apis/rest_api/builds.md | 4 ++-- pages/apis/rest_api/rules.md | 2 +- pages/pipelines/rules.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/pages/apis/rest_api/builds.md b/pages/apis/rest_api/builds.md index 8c1c545896..8573e27f74 100644 --- a/pages/apis/rest_api/builds.md +++ b/pages/apis/rest_api/builds.md @@ -517,12 +517,12 @@ Optional [request body properties](/docs/api#request-body-properties): - + - + diff --git a/pages/apis/rest_api/rules.md b/pages/apis/rest_api/rules.md index f786c32a42..c2eed2e7c3 100644 --- a/pages/apis/rest_api/rules.md +++ b/pages/apis/rest_api/rules.md @@ -139,7 +139,7 @@ Required [request body properties](/docs/api#request-body-properties): - diff --git a/pages/pipelines/rules.md b/pages/pipelines/rules.md index a6e37e4d83..8828cd7314 100644 --- a/pages/pipelines/rules.md +++ b/pages/pipelines/rules.md @@ -5,7 +5,7 @@ _Rules_ is a Buildkite feature that can do the following: <%= render_markdown partial: 'pipelines/rules_summary' %> > 📘 -> The _rules_ feature is currently in development and is enabled on an opt-in basis for early access. To enable rules your organization, please contact Buildkite's [Support team](https://buildkite.com/support). +> The _rules_ feature is currently in development, and is enabled on an opt-in basis for early access. To enable rules your organization, please contact Buildkite's [Support team](https://buildkite.com/support). ## Rule types From 0d8bab016d1a698a08e733c844771929ce3b3bf9 Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Thu, 5 Sep 2024 10:50:23 +1000 Subject: [PATCH 38/39] Fix typo. --- pages/pipelines/rules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/pipelines/rules.md b/pages/pipelines/rules.md index 8828cd7314..74a56d247d 100644 --- a/pages/pipelines/rules.md +++ b/pages/pipelines/rules.md @@ -5,7 +5,7 @@ _Rules_ is a Buildkite feature that can do the following: <%= render_markdown partial: 'pipelines/rules_summary' %> > 📘 -> The _rules_ feature is currently in development, and is enabled on an opt-in basis for early access. To enable rules your organization, please contact Buildkite's [Support team](https://buildkite.com/support). +> The _rules_ feature is currently in development, and is enabled on an opt-in basis for early access. To enable rules for your organization, please contact Buildkite's [Support team](https://buildkite.com/support). ## Rule types From 5a327059f72fc86725a4175a4cbf2301b32c51ea Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Thu, 5 Sep 2024 11:59:57 +1000 Subject: [PATCH 39/39] Minor sentence tweak to make it read less clunkily. --- pages/pipelines/_rules_summary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/pipelines/_rules_summary.md b/pages/pipelines/_rules_summary.md index dda32b90b6..52428b89d3 100644 --- a/pages/pipelines/_rules_summary.md +++ b/pages/pipelines/_rules_summary.md @@ -1,3 +1,3 @@ - Grant access between Buildkite resources that would normally be restricted by [cluster](/docs/clusters/overview), [visibility](/docs/pipelines/public-pipelines), or [permissions](/docs/team-management/permissions). -- Allow an action (for example, triggering a build) between a source resource (for example, a pipeline) and a target resource (for example, another pipeline) across your Buildkite organization. +- Allows an action between a source resource and a target resource across your Buildkite organization. For example, allowing one pipeline's builds to trigger another pipeline's builds.
    authorA hash with a "name" and "email" key to show who created this build.
    Default value: the user making the API request.
    authorA JSON object with a "name" and "email" key to show who created this build.
    Default value: the user making the API request.
    clean_checkoutForce the agent to remove any existing build directory and perform a fresh checkout.
    Default value: false.
    envEnvironment variables to be made available to the build.
    Default value: {}.
    ignore_pipeline_branch_filtersRun the build regardless of the pipeline's branch filtering rules. Step branch filtering rules will still apply.
    Default value: false.
    messageMessage for the build.
    Example: "Testing all the things \:rocket\:"
    meta_dataA hash of meta-data to make available to the build.
    Default value: {}.
    meta_dataA JSON object of meta-data to make available to the build.
    Default value: {}.
    pull_request_base_branchFor a pull request build, the base branch of the pull request.
    Example: "main"
    pull_request_idFor a pull request build, the pull request number.
    Example: 42
    pull_request_repositoryFor a pull request build, the git repository of the pull request.
    Example: "git://github.com/my-org/my-repo.git"
    valueA hash containing the value fields for the rule.
    +     		A JSON object containing the value fields for the rule.
    Example: {"source_pipeline_uuid": "16f3b56f-4934-4546-923c-287859851332", "target_pipeline_uuid": "d07d5d84-d1bd-479c-902c-ce8a01ce5aac"}