-
Notifications
You must be signed in to change notification settings - Fork 251
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #2932 from buildkite/pipeline-rules
Rules documentation
- Loading branch information
Showing
16 changed files
with
630 additions
and
8 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -9,7 +9,7 @@ | |
| ```graphql | ||
| query getCurrentUsersOrgs { | ||
| viewer { | ||
| organization { | ||
| organizations { | ||
| edges { | ||
| node { | ||
| name | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
| } | ||
| } | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 JSON object 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> | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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). | ||
|
|
||
| - 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. |
Oops, something went wrong.