Manage rules

This page provides details on how to manage rules within your Buildkite organization.

Create a rule

New rules can be created by Buildkite organization administrators using the Rules page, as well as Buildkite's REST API or GraphQL API.

Using the Buildkite interface

To create a new rule using the Buildkite interface:

Select Settings in the global navigation to access the Organization Settings page.
In the Pipelines section, select Rules > New Rule to open its page.
For Rule Type, select the type of rule to be created, that is, either pipeline.trigger_build.pipeline or pipeline.artifacts_read.pipeline.
Specify a short Description for the rule.
In the Rule Document field:
- Specify the relevant values (either a pipeline UUID or a pipeline slug) for both the source_pipeline and target_pipeline pipelines, of your pipeline.trigger_build.pipeline or pipeline.artifacts_read.pipeline rule. You can find the UUID values for these pipelines on the pipelines' respective Settings page under the GraphQL API integration section.
- Specify any optional conditions that must be met for the source pipeline to trigger or access artifacts built by its target pipeline.
Select Create Rule.

The rule is created and presented on the Rules page, with a brief description of the rule type and the relationship between both pipelines.

Using the REST API

To create a new rule using the REST API, run the following example curl command:

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",
    "description": "A short description for your rule",
    "value": {
      "source_pipeline": "{pipeline-uuid-or-slug}",
      "target_pipeline": "{pipeline-uuid-or-slug}",
      "conditions": ["{condition-1}", "{condition-2}"]
    }
  }'

where:

$TOKEN is an API access token scoped to the relevant Organization and REST API Scopes that your request needs access to in Buildkite.

{org.slug} can be obtained:
- From the end of your Buildkite URL, after accessing Pipelines in the global navigation of your organization in Buildkite.
- By running the List organizations REST API query to obtain this value from slug in the response. For example:
```
curl -H "Authorization: Bearer $TOKEN" \
  - X GET "https://api.buildkite.com/v2/organizations"
```

rule is the type of rule to be created, that is, either pipeline.trigger_build.pipeline or pipeline.artifacts_read.pipeline.
description (optional) is a short description for the rule.
source_pipeline and target_pipeline accept either a pipeline slug or UUID.

Pipeline UUID values for source_pipeline and target_pipeline 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.
  2. Once on the Pipeline Settings page, copy the UUID value from the GraphQL API Integration section
- By running the List pipelines REST API query to obtain this value from id in the response from the specific pipeline. For example:
```
curl -H "Authorization: Bearer $TOKEN" \
  - X GET "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines"
```
conditions (optional) is an array of conditions that must be met for the source pipeline to trigger or access artifacts built by its target pipeline. Some example values could include:
- source.build.creator.teams includes 'core'
- source.build.branch == 'main'

Using the GraphQL API

To create a new rule using the GraphQL API, use the ruleCreate mutation based on the following example, where the contents of the value field must be a JSON-encoded string:

mutation {
  ruleCreate(input: {
    organizationId: "organization-id",
    type: "pipeline.trigger_build.pipeline",
    description: "An short description for your rule",
    value: "{\"source_pipeline\":\"pipeline-uuid-or-slug\",\"target_pipeline\":\"pipeline-uuid-or-slug\",\"conditions\":[\"condition-1\",\"condition-2\"]}"
  }) {
    rule {
      id
      type
      description
      targetType
      sourceType
      source {
        ... on Pipeline {
          uuid
        }
      }
      target {
        ... on Pipeline {
          uuid
        }
      }
      effect
      action
      createdBy {
        id
        name
      }
    }
  }
}

where:

organizationId (required) can be obtained:
- From the GraphQL API Integration section of your Organization Settings page, accessed by selecting Settings in the global navigation of your organization in Buildkite.
- By running a getCurrentUsersOrgs GraphQL API query to obtain the organization slugs for the current user's accessible organizations, followed by a getOrgId query, to obtain the organization's id using the organization's slug. For example:
  
  Step 1. Run getCurrentUsersOrgs to obtain the organization slug values in the response for the current user's accessible organizations:
```
query getCurrentUsersOrgs {
  viewer {
    organizations {
      edges {
        node {
          name
          slug
        }
      }
    }
  }
}
```
  Step 2. Run getOrgId with the appropriate slug value above to obtain this organization's id in the response:
```
query getOrgId {
  organization(slug: "organization-slug") {
    id
    uuid
    slug
  }
}
```
  Note: The organization-slug value can also be obtained from the end of your Buildkite URL, by selecting Pipelines in the global navigation of your organization in Buildkite.

type is the type of rule to be created, that is, either pipeline.trigger_build.pipeline or pipeline.artifacts_read.pipeline.
description (optional) is a short description for the rule.
source_pipeline and target_pipeline accept either a pipeline slug or UUID.

Pipeline UUID values for source_pipeline and target_pipeline 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.
  2. Once on the Pipeline Settings page, copy the UUID value from the GraphQL API Integration section
- By running the getCurrentUsersOrgs GraphQL API query to obtain the organization slugs for the current user's accessible organizations, then getOrgPipelines 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:
```
query getCurrentUsersOrgs {
  viewer {
    organizations {
      edges {
        node {
          name
          slug
        }
      }
    }
  }
}
```
  Step 2. Run getOrgPipelines with the appropriate slug value above to obtain this organization's uuid in the response:
```
query getOrgPipelines {
  organization(slug: "organization-slug") {
    pipelines(first: 100) {
      edges {
        node {
          id
          uuid
          name
        }
      }
    }
  }
}
```
conditions (optional) is an array of conditions that must be met for the source pipeline to trigger or access artifacts built by its target pipeline. Some example values could include:
- source.build.creator.teams includes 'core'
- source.build.branch == 'main'

Edit a rule

Rules can be edited by Buildkite organization administrators using the Rules page, as well as Buildkite's GraphQL API.

When editing a rule, you can modify its Description and Rule Document details, where the latter is contained within the value field of API requests, although a rule's type is fixed once it is created and its value cannot be modified.

Using the Buildkite interface

To edit an existing rule using the Buildkite interface:

Select Settings in the global navigation to access the Organization Settings page.
In the Pipelines section, select Rules to access its page.
Expand the existing rule to be edited.
Select the Edit button to open the rule's Edit Rule page.
If required, modify the rule's short Description, or clear this field to remove this value.
In the Rule Document field:
- Modify the relevant values (either a pipeline UUID or a pipeline slug) for both the source_pipeline and target_pipeline pipelines, of your pipeline.trigger_build.pipeline or pipeline.artifacts_read.pipeline rule. You can find the UUID values for these pipelines on the pipelines' respective Settings page under the GraphQL API integration section.
- Modify any optional conditions that must be met for the source pipeline to trigger or access artifacts built by its target pipeline. To remove a condition, remove its specific value from the array, or to remove all conditions, remove the entire conditions array.
Select Save Rule.

The rule is updated and you are returned to the Rules page. The rule's Description and other details can be accessed when the rule is expanded.

Using the GraphQL API

To edit an existing rule using the GraphQL API, use the ruleUpdate mutation based on the following example, where the contents of the value field must be a JSON-encoded string:

mutation {
  ruleUpdate(input: {
    organizationId: "organization-id",
    id: "rule-id",
    description: "A optional, new short description for your rule",
    value: "{\"source_pipeline\":\"pipeline-uuid-or-slug\",\"target_pipeline\":\"pipeline-uuid-or-slug\",\"conditions\":[\"condition-1\",\"condition-2\"]}"
  }) {
    rule {
      id
      type
      description
      targetType
      sourceType
      source {
        ... on Pipeline {
          uuid
        }
      }
      target {
        ... on Pipeline {
          uuid
        }
      }
      effect
      action
      createdBy {
        id
        name
      }
    }
  }
}

where:

organizationId (required) can be obtained:
- From the GraphQL API Integration section of your Organization Settings page, accessed by selecting Settings in the global navigation of your organization in Buildkite.
- By running a getCurrentUsersOrgs GraphQL API query to obtain the organization slugs for the current user's accessible organizations, followed by a getOrgId query, to obtain the organization's id using the organization's slug. For example:
  
  Step 1. Run getCurrentUsersOrgs to obtain the organization slug values in the response for the current user's accessible organizations:
```
query getCurrentUsersOrgs {
  viewer {
    organizations {
      edges {
        node {
          name
          slug
        }
      }
    }
  }
}
```
  Step 2. Run getOrgId with the appropriate slug value above to obtain this organization's id in the response:
```
query getOrgId {
  organization(slug: "organization-slug") {
    id
    uuid
    slug
  }
}
```
  Note: The organization-slug value can also be obtained from the end of your Buildkite URL, by selecting Pipelines in the global navigation of your organization in Buildkite.

id is the rule ID value of the existing rule to be edited. This value 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. Then, expand the existing rule and copy its GraphQL ID value.

By running a List rules GraphQL API query to obtain the rule's id in the response. For example:

query getRules {
  organization(slug: "organization-slug") {
    rules(first: 10) {
      edges {
        node {
          id
          type
          source {
            ... on Pipeline {
              slug
            }
          }
          target {
            ... on Pipeline {
              slug
            }
          }
        }
      }
    }
  }
}

description (optional) is a short description for the rule. Omitting this value will remove this value from the rule.
source_pipeline and target_pipeline accept either a pipeline slug or UUID.

Pipeline UUID values for source_pipeline and target_pipeline 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.
  2. Once on the Pipeline Settings page, copy the UUID value from the GraphQL API Integration section
- By running the getCurrentUsersOrgs GraphQL API query to obtain the organization slugs for the current user's accessible organizations, then getOrgPipelines 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:
```
  query getCurrentUsersOrgs {
    viewer {
      organizations {
        edges {
          node {
            name
            slug
          }
        }
      }
    }
  }
```
  Step 2. Run getOrgPipelines with the appropriate slug value above to obtain this organization's uuid in the response:
```
  query getOrgPipelines {
    organization(slug: "organization-slug") {
      pipelines(first: 100) {
        edges {
          node {
            id
            uuid
            name
          }
        }
      }
    }
  }
```
conditions (optional) is an array of conditions that must be met for the source pipeline to trigger or access artifacts built by its target pipeline. Some example values could include:
- source.build.creator.teams includes 'core'
- source.build.branch == 'main'
Note: To remove a condition, remove its specific value from this array, or to remove all conditions, remove the entire conditions array.

Delete a rule

Rules can be deleted by Buildkite organization administrators using the Rules page, as well as Buildkite's REST API or GraphQL API.

Using the Buildkite interface

To delete an existing rule using the Buildkite interface:

Select Settings in the global navigation to access the Organization Settings page.
In the Pipelines section, select Rules to access its page.
Expand the existing rule to be deleted.
Select the Delete button to delete this rule.

Note: Exercise caution at this point as this action happens immediately without any warning message appearing after selecting this button.

Using the REST API

To delete an existing rule using the REST API, run the following example curl command:

curl -H "Authorization: Bearer $TOKEN" \
  -X DELETE "https://api.buildkite.com/v2/organizations/{org.slug}/rules/{rule.uuid}"

where:

$TOKEN is an API access token scoped to the relevant Organization and REST API Scopes that your request needs access to in Buildkite.

{org.slug} can be obtained:
- From the end of your Buildkite URL, after accessing Pipelines in the global navigation of your organization in Buildkite.
- By running the List organizations REST API query to obtain this value from slug in the response. For example:
```
curl -H "Authorization: Bearer $TOKEN" \
  - X GET "https://api.buildkite.com/v2/organizations"
```

{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 REST API query to obtain the rule's uuid in the response. For example:
```
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 an existing rule using the GraphQL API, use the ruleDelete mutation, based on the following example:

mutation {
  ruleDelete(input: {
    organizationId: "organization-id",
    id: "rule-id"
  }) {
    deletedRuleId
  }
}

where:

organizationId (required) can be obtained:
- From the GraphQL API Integration section of your Organization Settings page, accessed by selecting Settings in the global navigation of your organization in Buildkite.
- By running a getCurrentUsersOrgs GraphQL API query to obtain the organization slugs for the current user's accessible organizations, followed by a getOrgId query, to obtain the organization's id using the organization's slug. For example:
  
  Step 1. Run getCurrentUsersOrgs to obtain the organization slug values in the response for the current user's accessible organizations:
```
query getCurrentUsersOrgs {
  viewer {
    organizations {
      edges {
        node {
          name
          slug
        }
      }
    }
  }
}
```
  Step 2. Run getOrgId with the appropriate slug value above to obtain this organization's id in the response:
```
query getOrgId {
  organization(slug: "organization-slug") {
    id
    uuid
    slug
  }
}
```
  Note: The organization-slug value can also be obtained from the end of your Buildkite URL, by selecting Pipelines in the global navigation of your organization in Buildkite.

id is the rule ID value of the existing rule to be deleted. This value 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. Then, expand the existing rule and copy its GraphQL ID value.
- By running a List rules GraphQL API query to obtain the rule's id in the response. For example:
```
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.