[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/graphql/schema.graphql

@@ -4078,7 +4078,7 @@ type Mutation {
   """
   Sets an allowlist of IP addresses for API access to an organization. Please
   note that this is a beta feature and is not yet available to all
-  organizations. 
+  organizations.
   """
   organizationApiIpAllowlistUpdate(
     """
@@ -6630,6 +6630,23 @@ input PipelineCreateInput {
   """
   branchConfiguration: String
 
+  """
+  Choose to keep builds or remove them after a set time period. Pipelines are
+  scanned once a day for builds that can be removed according to these settings.
+  Some billing plans require this setting to be enabled.
+  """
+  buildRetentionEnabled: Boolean @deprecated(reason: "Build retention is now determined by your billing plan. This field is no longer used and always returns null.")
+
+  """
+  The minimum number of builds to keep in the pipeline regardless of how old the builds are.
+  """
+  buildRetentionNumber: Int @deprecated(reason: "Build retention is now determined by your billing plan. This field is no longer used and always returns null.")
+
+  """
+  How long is a build kept before it is automatically removed.
+  """
+  buildRetentionPeriod: BuildRetentionPeriods @deprecated(reason: "Build retention is now determined by your billing plan. This field is no longer used and always returns null.")
+
   """
   If intermediate builds should be canceled as new builds are created
   """
@@ -7434,6 +7451,23 @@ input PipelineUpdateInput {
   """
   branchConfiguration: String
 
+  """
+  Choose to keep builds or remove them after a set time period. Pipelines are
+  scanned once a day for builds that can be removed according to these settings.
+  Some billing plans require this setting to be enabled.
+  """
+  buildRetentionEnabled: Boolean @deprecated(reason: "Build retention is now determined by your billing plan. This field is no longer used and always returns null.")
+
+  """
+  The minimum number of builds to keep in the pipeline regardless of how old the builds are.
+  """
+  buildRetentionNumber: Int @deprecated(reason: "Build retention is now determined by your billing plan. This field is no longer used and always returns null.")
+
+  """
+  How long is a build kept before it is automatically removed.
+  """
+  buildRetentionPeriod: BuildRetentionPeriods @deprecated(reason: "Build retention is now determined by your billing plan. This field is no longer used and always returns null.")
+
   """
   If intermediate builds should be canceled as new builds are created
   """

data/nav.yml

@@ -414,6 +414,9 @@
               path: "apis/rest-api/organizations"
             - name: "Pipelines"
               path: "apis/rest-api/pipelines"
+            - name: "Pipeline templates"
+              path: "apis/rest-api/pipeline-templates"
+              pill: "beta"
             - name: "Builds"
               path: "apis/rest-api/builds"
             - name: "Jobs"

data/nav_graphql.yml

@@ -17,6 +17,8 @@
     path: apis/graphql/cookbooks/agents
   - name: Clusters
     path: apis/graphql/cookbooks/clusters
+  - 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,145 @@
+# 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
+    }
+  }
+}
+```
+
+## Updating 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
+    }
+  }
+}
+```
+
+## Deleting 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
+  }
+}
+```
+
+## Managing pipeline template assignment on a pipeline
+
+Admins and users with manage pipeline permissions 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
+    }
+  }
+}
+```
+
+Conversely, pipeline templates can be removed 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

@@ -13,5 +13,6 @@ There are recipes for a range of different topics, including:
 - [Jobs](/docs/apis/graphql/cookbooks/jobs)
 - [Agents](/docs/apis/graphql/cookbooks/agents)
 - [Clusters](/docs/apis/graphql/cookbooks/clusters)
+- [Pipeline templates](/docs/apis/graphql/cookbooks/pipeline-templates)
 - [Organizations](/docs/apis/graphql/cookbooks/organizations)
 - [Teams](/docs/apis/graphql/cookbooks/teams)