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 the REST API's or GraphQL API's create a rule feature.

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.
Under Rule Type, select the type of rule to be created, that is, either pipeline.trigger_build.pipeline or pipeline.artifacts_read.pipeline.
Under Rule Document, 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.
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 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",
    "value": {
      "source_pipeline": "{pipeline-uuid-or-slug}",
      "target_pipeline": "{pipeline-uuid-or-slug}"
    }
  }'

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.
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"
```

Using the GraphQL API

To create a new rule using the GraphQL API, run the following example mutation:

mutation {
  ruleCreate(input: {
    organizationId: "organization-id",
    type: "pipeline.trigger_build.pipeline",
    value: "{\"source_pipeline\":\"pipeline-uuid-or-slug\",\"target_pipeline\":\"pipeline-uuid-or-slug\"}"
  }) {
     rule {
      id
      type
      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.
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
        }
      }
    }
  }
}
```

Delete a rule

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

Using the Buildkite interface

To delete a 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.

Using the REST API

To delete a 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 a rule using the GraphQL API, run the following example mutation:

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, 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 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.