Merge pull request #2479 from buildkite/edge-1520-create-pipeline-tem…

…plate-rest-api-documentation

[EDGE-1520] Add pipeline templates rest & graphql api documentation

app/models/beta_pages.rb

@@ -10,7 +10,8 @@ def self.all
       'apis/rest-api/analytics/runs',
       'apis/rest-api/analytics/tests',
       'agent/clusters',
-      'apis/rest-api/clusters'
+      'apis/rest-api/clusters',
+      'apis/rest-api/pipeline-templates'
     ]
   end
 end

data/nav.yml

@@ -410,31 +410,34 @@
           children:
             - name: "Access token"
               path: "apis/rest-api/access-token"
-            - name: "Organizations"
-              path: "apis/rest-api/organizations"
-            - name: "Pipelines"
-              path: "apis/rest-api/pipelines"
-            - name: "Builds"
-              path: "apis/rest-api/builds"
-            - name: "Jobs"
-              path: "apis/rest-api/jobs"
             - name: "Agents"
               path: "apis/rest-api/agents"
-            - name: "Clusters"
-              pill: "beta"
-              path: "apis/rest-api/clusters"
-            - name: "Artifacts"
-              path: "apis/rest-api/artifacts"
             - name: "Annotations"
               path: "apis/rest-api/annotations"
+            - name: "Artifacts"
+              path: "apis/rest-api/artifacts"
+            - name: "Builds"
+              path: "apis/rest-api/builds"
+            - name: "Clusters"
+              path: "apis/rest-api/clusters"
+              pill: "beta"
             - name: "Emojis"
               path: "apis/rest-api/emojis"
-            - name: "User"
-              path: "apis/rest-api/user"
+            - name: "Jobs"
+              path: "apis/rest-api/jobs"
             - name: "Meta"
               path: "apis/rest-api/meta"
+            - name: "Organizations"
+              path: "apis/rest-api/organizations"
+            - name: "Pipelines"
+              path: "apis/rest-api/pipelines"
+            - name: "Pipeline templates"
+              path: "apis/rest-api/pipeline-templates"
+              pill: "beta"
             - name: "Teams"
               path: "apis/rest-api/teams"
+            - name: "User"
+              path: "apis/rest-api/user"
         - name: "Agent REST API"
           children:
             - name: "Overview"
@@ -446,12 +449,12 @@
             - name: "Flaky tests"
               pill: "beta"
               path: "apis/rest-api/analytics/flaky-tests"
-            - name: "Suites"
-              pill: "beta"
-              path: "apis/rest-api/analytics/suites"
             - name: "Runs"
               pill: "beta"
               path: "apis/rest-api/analytics/runs"
+            - name: "Suites"
+              pill: "beta"
+              path: "apis/rest-api/analytics/suites"
             - name: "Tests"
               pill: "beta"
               path: "apis/rest-api/analytics/tests"

data/nav_graphql.yml

@@ -7,16 +7,18 @@
   children:
   - name: Overview
     path: apis/graphql/graphql-cookbook
-  - name: Pipelines
-    path: apis/graphql/cookbooks/pipelines
-  - name: Builds
-    path: apis/graphql/cookbooks/builds
-  - name: Jobs
-    path: apis/graphql/cookbooks/jobs
   - name: Agents
     path: apis/graphql/cookbooks/agents
+  - name: Builds
+    path: apis/graphql/cookbooks/builds
   - name: Clusters
     path: apis/graphql/cookbooks/clusters
+  - name: Jobs
+    path: apis/graphql/cookbooks/jobs
+  - name: Pipelines
+    path: apis/graphql/cookbooks/pipelines
+  - name: Pipeline templates
+    path: apis/graphql/cookbooks/pipeline-templates
   - name: Organizations
     path: apis/graphql/cookbooks/organizations
   - name: Teams

pages/apis/agent_api.md

@@ -17,7 +17,7 @@ curl https://agent.buildkite.com
 
 ```json
 {
-"message":"👋"
+  "message":"👋"
 }
 ```
 

pages/apis/graphql/cookbooks/clusters.md

@@ -11,9 +11,9 @@ Get the first 10 clusters and their information for an organization:
 ```graphql
 query getClusters {
   organization(slug: "organization-slug") {
-    clusters(first: 10){
-      edges{
-        node{
+    clusters(first: 10) {
+      edges {
+        node {
           id
           uuid
           color

pages/apis/graphql/cookbooks/pipeline_templates.md

@@ -0,0 +1,147 @@
+# Pipeline templates
+
+A collection of common tasks with pipeline templates 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 pipeline templates
+
+Get the first 10 pipeline templates and their information for an organization:
+
+```graphql
+query GetPipelineTemplates {
+  organization(slug: "organization-slug") {
+    pipelineTemplates(first: 10) {
+      edges {
+        node {
+          id
+          uuid
+          name
+          description
+          configuration
+          available
+        }
+      }
+    }
+  }
+}
+```
+
+## Get a pipeline template
+
+Get information on a pipeline template, specifying the pipeline templates' UUID as the `uuid` argument of the `pipelineTemplate` query:
+
+```graphql
+query GetPipelineTemplate {
+  pipelineTemplate(uuid: "pipeline-template-uuid") {
+    id
+    uuid
+    name
+    description
+    configuration
+    available
+  }
+}
+```
+
+## Create a pipeline template
+
+Create a pipeline template for an organization using the `pipelineTemplateCreate` mutation:
+
+```graphql
+mutation CreatePipelineTemplate {
+  pipelineTemplateCreate(input: {
+    organizationId: "organization-id",
+    name: "template name",
+    description: "it does a thing",
+    configuration: "steps:\n  - command: deploy.sh",
+    available: false
+  }) {
+    pipelineTemplate {
+      id
+      uuid
+      name
+      description
+      configuration
+      available
+    }
+  }
+}
+```
+
+## Update a pipeline template
+
+Update a pipeline template on an organization using the `pipelineTemplateUpdate` mutation, specifying the ID for organization and pipeline template:
+
+```graphql
+mutation UpdatePipelineTemplate {
+  pipelineTemplateUpdate(input: {
+    organizationId: "organization-id",
+    id: "pipeline-template-id",
+    configuration: "steps:\n - comand: updated_steps.sh"
+    available: true
+  }) {
+    pipelineTemplate {
+      id
+      uuid
+      name
+      description
+      configuration
+      available
+    }
+  }
+}
+```
+
+## Delete a pipeline template
+
+Delete a pipeline template using the `pipelineTemplateDelete` mutation, specifying the ID for organization and pipeline template:
+
+```graphql
+mutation DeletePipelineTemplate {
+  pipelineTemplateDelete(input: {
+    organizationId: "organization-id",
+    id: "pipeline-template-id"
+  }) {
+    deletedPipelineTemplateId
+  }
+}
+```
+
+## Assign a template to a pipeline
+
+Admins and users with permission to manage pipelines can assign a pipeline template to a pipeline using the `pipelineUpdate` mutation:
+
+```graphql
+mutation AssignPipelineTemplate {
+  pipelineUpdate(input: {
+    id: "pipeline-id"
+    pipelineTemplateId: "pipeline-template-id"
+  }) {
+    pipeline {
+      id
+      name
+      pipelineTemplateId
+    }
+  }
+}
+```
+
+## Remove a template from a pipeline
+
+Admins and users with permission to manage pipelines can remove from a pipeline by specifying `pipelineTemplateId` as `null` in the mutation input:
+
+```graphql
+mutation UnassignPipelineTemplate {
+  pipelineUpdate(input: {
+    id: "pipeline-id"
+    pipelineTemplateId: null
+  }) {
+    pipeline {
+      id
+      name
+      pipelineTemplateId
+    }
+  }
+}
+```

pages/apis/graphql/graphql_cookbook.md

@@ -8,10 +8,11 @@ The GraphQL cookbook is a collection of recipes detailing how to do common tasks
 
 There are recipes for a range of different topics, including:
 
-- [Pipelines](/docs/apis/graphql/cookbooks/pipelines)
-- [Builds](/docs/apis/graphql/cookbooks/builds)
-- [Jobs](/docs/apis/graphql/cookbooks/jobs)
 - [Agents](/docs/apis/graphql/cookbooks/agents)
+- [Builds](/docs/apis/graphql/cookbooks/builds)
 - [Clusters](/docs/apis/graphql/cookbooks/clusters)
+- [Jobs](/docs/apis/graphql/cookbooks/jobs)
+- [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)