Rules documentation

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"
+        - name: "Manage rules"
+          path: "pipelines/rules/manage"
     - name: "Security"
       children:
         - name: "Overview"
@@ -575,6 +581,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"

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

pages/apis/descriptions/_graphql_organization_id.md

@@ -9,7 +9,7 @@
         ```graphql
         query getCurrentUsersOrgs {
           viewer {
-            organization {
+            organizations {
               edges {
                 node {
                   name

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.

pages/apis/graphql/cookbooks/rules.md

@@ -0,0 +1,94 @@
+# 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
+            type
+            targetType
+            sourceType
+            source {
+              ... on Pipeline {
+                slug
+              }
+            }
+            target {
+              ... on Pipeline {
+                slug
+              }
+            }
+            effect
+            action
+            createdBy {
+              id
+              name
+            }
+          }
+        }
+      }
+    }
+  }
+```
+
+## Create a rule
+
+Create a rule. The value of the `value` field must be a JSON-encoded string.
+
+```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}\"}"
+  }) {
+     rule {
+      id
+      type
+      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
+  }
+}
+```

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)
+- [Rules](/docs/apis/graphql/cookbooks/rules)
 - [Organizations](/docs/apis/graphql/cookbooks/organizations)
 - [Teams](/docs/apis/graphql/cookbooks/teams)

pages/apis/rest_api/rules.md

@@ -0,0 +1,180 @@
+# Rules API
+
+The rules API lets you create and manage rules in your organization.
+
+## Rules
+
+[_Rules_](/docs/pipelines/rules) is a Buildkite feature that can do the following:
+
+<%= render_markdown partial: 'pipelines/rules_summary' %>
+
+### 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",
+    "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": "[email protected]",
+      "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",
+  "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": "[email protected]",
+    "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 '{
+    "type": "pipeline.trigger_build.pipeline",
+    "value": {
+      "source_pipeline_uuid": "16f3b56f-4934-4546-923c-287859851332",
+      "target_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",
+  "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": "[email protected]",
+    "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):
+
+<table class="responsive-table">
+<tbody>
+  <tr>
+    <th><code>type</code></th>
+    <td>The rule type. Must match one of the <a href="/docs/pipelines/rules#rule-types">available rule types</a>.<br>
+    <em>Example:</em>
+      <ul>
+        <li><code>"pipeline.trigger_build.pipeline"</code><br/>or</li>
+        <li><code>"pipeline.artifacts_read.pipeline"</code></li>
+    </td>
+  </tr>
+  <tr>
+    <th><code>value</code></th>
+    <td>A hash containing the value fields for the rule.<br>
+    <em>Example:</em> <code>{"source_pipeline_uuid": "16f3b56f-4934-4546-923c-287859851332", "target_pipeline_uuid": "d07d5d84-d1bd-479c-902c-ce8a01ce5aac"}</code></td>
+  </tr>
+</tbody>
+</table>
+
+Required scope: `write_rules`
+
+Success response: `201 Created`
+
+Error responses:
+
+<table class="responsive-table">
+<tbody>
+  <tr><th><code>422 Unprocessable Entity</code></th><td><code>{ "message": "Reason for failure" }</code></td></tr>
+</tbody>
+</table>
+
+### Delete a rule
+
+Delete a rule.
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  -X DELETE "https://api.buildkite.com/v2/organizations/{org.slug}/rules/{uuid}"
+```
+
+Required scope: `write_rules`
+
+Success response: `204 No Content`
+
+Error responses:
+
+<table class="responsive-table">
+<tbody>
+  <tr><th><code>422 Unprocessable Entity</code></th><td><code>{ "message": "Reason the rule couldn't be deleted" }</code></td></tr>
+</tbody>
+</table>
+

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
                 }
-              } 
+              }
             }
           }
         }

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 to explicitly allow triggering between pipelines in different clusters.
 
 ### How should I structure my queues
 

pages/pipelines/_rules_summary.md

@@ -0,0 +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.