Content Stages

You can create your own content stages inside the GraphCMS UI, and query content from these stages, as well as publish to.

By default all content is served from the DRAFT stage, unless configured otherwise via a Permanent Auth Token, or by filtering.

You can create custom content stages to publish to from draft. Each project comes with stages DRAFT, and PUBLISHED.

Content stages are available to paid plans. Upgrade your plan.

Create a content stage

Navigate to your project settings.
Open the Content Stages tab.
Press "Add Stage" at the bottom of the list of stages.
Provide the Display name, API ID, a Color for the label and Description in the modal.
Press create.

Edit a content stage

Navigate to the content stage you want to edit.
Press "edit" in the lower left corner of the stage card.
Press "update" in the lower right corner of the card.

Delete a content stage

Navigate to the content stage card you want to delete.
Press "delete" and confirm your choice.

Publishing content

GraphCMS automatically generates a publish mutation for each of your content models, including the asset model.

If the models have localized fields, you can greater control the locales you want to publish, and if you want to publish the base entry.

Each time you publish to a content stage, you will create a snapshot of the data as a version.

For example, if we have a product model, the mutation publishProduct will exist. You can use this mutation to publish content to a content stage.

Argument	Input Tpye	Description
`where`	`ProductWhereUniqueInput`	The content entry you want to publish, using a filter.
`to`	`[Stage!]! = [PUBLISHED]`	The target published content stage.
`locales`	`[Locale!]`	Optional locales to publish.
`publishBase`	`Boolean = true`	Whether to publish the base content entry.
`withDefaultLocale`	`Boolean = true`

mutation {
  publishProduct(where: { id: "..." }, to: PUBLISHED) {
    id
  }
}

mutation {
  publishProduct(
    where: { id: "..." }
    to: PUBLISHED
    publishBase: true
    locales: [en]
    withDefaultLocale: true
  ) {
    id
  }
}

Unpublishing content

Similar to publishing content, you can unpublish from a selected content stage.

For example, if we have a product model, the mutation unpublishProduct will exist. You can use this mutation to unpublish content from a content stage.

Argument	Input Tpye	Description
`where`	`ProductWhereUniqueInput`	The content entry you want to unpublish, using a filter.
`from`	`[Stage!]! = [PUBLISHED]`	The target content stage to unpublish from.
`locales`	`[Locale!]`	Optional locales to unpublish.
`unpublishBase`	`Boolean = true`	Whether to unpublish the base content entry or not.

mutation {
  unpublishProduct(where: { id: "..." }, to: PUBLISHED) {
    id
  }
}

mutation {
  unpublishProduct(
    where: { id: "..." }
    from: PUBLISHED
    unpublishBase: true
    locales: [en]
  ) {
    id
  }
}

Versioning

Versioning allows you to work non-destructively with content. Make changes, and recover previous versions with GraphCMS.

Each time you publish to a content stage, history is written.

Versions of documents are kept for a minimum of 30 days, for paid plans. Upgrade your plan for longer history retention.

Fetching version history

You can fetch all of the history by stage. history is a system field.

For example, let's get all of the history for products.

{
  products(stage: PUBLISHED) {
    history {
      id
      stage
      revision
      createdAt
    }
  }
}

{
  "data": {
    "products": [
      {
        "history": [
          {
            "id": "ckdt47uio02al01044grc4ehf",
            "stage": "PUBLISHED",
            "revision": 4,
            "createdAt": "2020-11-02T10:28:24.273413+00:00"
          },
          {
            "id": "ckdt47uio02al01044grc4ehf",
            "stage": "PUBLISHED",
            "revision": 3,
            "createdAt": "2020-11-02T10:01:40.453523+00:00"
          },
          {
            "id": "ckdt47uio02al01044grc4ehf",
            "stage": "PUBLISHED",
            "revision": 2,
            "createdAt": "2020-11-02T10:01:36.351916+00:00"
          },
          {
            "id": "ckdt47uio02al01044grc4ehf",
            "stage": "PUBLISHED",
            "revision": 1,
            "createdAt": "2020-11-02T10:00:22.14774+00:00"
          }
        ]
      }
    ]
  }
}

Replace stage: PUBLISHED with stage: QA to get history from custom stage QA.

Fetching a single version

You can use a the generated [model]Version query to fetch a single version of a content entry.

Since models can be complex, and change over time. The data field is a JSON field that returns a snapshot of the content entry at that time.

Using the id, and revision from the previous query, we can fetch the data of the version, including the relations metadata.

{
  productVersion(
    where: { id: "ckdt47uio02al01044grc4ehf", revision: 4, stage: PUBLISHED }
  ) {
    id
    stage
    revision
    data
  }
}

{
  "data": {
    "productVersion": {
      "id": "ckdt47uio02al01044grc4ehf",
      "stage": "PUBLISHED",
      "revision": 4,
      "data": {
        "id": "ckdt47uio02al01044grc4ehf",
        "name": "Snapback",
        "slug": "snapback",
        "image": {
          "id": "ckdt47ocg02af0104ek5dinsj",
          "__typename": "Asset"
        },
        "stage": "PUBLISHED",
        "prices": [
          {
            "id": "cke1f4fow022h0151b46dd64d",
            "__typename": "Price"
          },
          {
            "id": "cke1f4pq0022f0146btokysn8",
            "__typename": "Price"
          }
        ],
        "category": {
          "id": "cke1erm9s01ov0151p2h1k6bw",
          "__typename": "Category"
        },
        "createdAt": "2020-08-13T18:07:36.201803+00:00",
        "updatedAt": "2020-08-19T13:35:19.916504+00:00",
        "description": {
          "raw": {
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "text": ""
                  }
                ]
              }
            ]
          },
          "__typename": "RichText"
        },
        "publishedAt": "2020-11-02T10:28:24.273413+00:00"
      }
    }
  }
}