Supergraph Previews for every Pull Request - WunderGraph

Documentation Index

Fetch the complete documentation index at: /llms.txt

Use this file to discover all available pages before exploring further.

When developing new features, it is crucial to test them in a production-like environment. By generating a preview for each pull request (PR), developers can ensure that their changes are thoroughly tested in such an environment before being merged. By utilizing Graph Feature Flags, the continuous integration (CI) pipeline can deploy a new feature subgraph and corresponding feature flag for each PR, enabling one composition per PR without deploying all subgraphs. The only requirement is a staging environment deployed from the main branches of your subgraphs. Graph feature flags allow you to “override” the subgraphs for a specific pull request.

Usage

Prerequisites

Before using the Cosmo Previews GitHub Action, ensure that the following prerequisites are met:

Cosmo API Key
You must have a valid API key from WunderGraph Cosmo, which should be stored as a secret in your GitHub repository under COSMO_API_KEY.

Configuration File
Create a cosmo.yaml file in the .github directory of your repository. This file should define the configuration for your subgraphs and feature flags.

Subgraphs on Wundergraph Cosmo
All subgraphs referenced in the cosmo.yaml file must be created and published on Wundergraph Cosmo. Ensure that these subgraphs are correctly configured.

GitHub Token
The GitHub token is automatically provided by GitHub Actions, but ensure it is correctly referenced.

Setup

To use this action in your repository:

  1. Create a .github/cosmo.yaml file that defines the configuration for your feature subgraphs and feature flags.
version: '0.0.1'
namespace: '<your-namespace>'
feature_flags:
  - name: '<your-feature-flag>'
    labels:
      - '<label-1>'
      - '<label-2>'

subgraphs:
  - name: '<subgraph-1-name>'
    schema_path: '<path-to-schema-1>'
    routing_url: '<routing-url-1>'

- name: '<subgraph-2-name>'
    schema_path: '<path-to-schema-2>'
    routing_url: '<routing-url-2>'
  1. Add the following GitHub Action workflow to your repository.

Example Workflow

name: Cosmo Previews
on:
  pull_request:
    branches:
      - main
    types:
      - opened
      - reopened
      - closed
      - synchronize

jobs:
  create:
    runs-on: ubuntu-latest
    if: github.event.action == 'opened' || github.event.action == 'reopened'
    steps:
      - name: Checkout
        uses: actions/checkout@v4

- name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20.10.0
          cache: npm

- name: Install wgc
        run: npm i -g wgc@latest

- name: Create Cosmo Previews
        uses: wundergraph/cosmo-previews@v0.1.0
        with:
          config_path: .github/cosmo.yaml
          create: true
          cosmo_api_key: ${{ secrets.COSMO_API_KEY }}
          github_token: ${{ secrets.GITHUB_TOKEN }}

update:
    runs-on: ubuntu-latest
    if: github.event.action == 'synchronize'
    steps:
      - name: Checkout
        uses: actions/checkout@v4

- name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20.10.0
          cache: npm

- name: Install wgc
        run: npm i -g wgc@latest

- name: Update Cosmo Previews
        uses: wundergraph/cosmo-previews@v0.1.0
        with:
          config_path: .github/cosmo.yaml
          update: true
          cosmo_api_key: ${{ secrets.COSMO_API_KEY }}
          github_token: ${{ secrets.GITHUB_TOKEN }}

destroy:
    runs-on: ubuntu-latest
    if: github.event.action == 'closed'
    steps:
      - name: Checkout
        uses: actions/checkout@v4

- name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20.10.0
          cache: npm

- name: Install wgc
        run: npm i -g wgc@latest

- name: Destroy Cosmo Previews
        uses: wundergraph/cosmo-previews@v0.1.0
        with:
          config_path: .github/cosmo.yaml
          destroy: true
          cosmo_api_key: ${{ secrets.COSMO_API_KEY }}
          github_token: ${{ secrets.GITHUB_TOKEN }}

Action Parameters

Jobs

Create

The create job is triggered when a pull request is opened or reopened. It performs the following actions:

  1. Checks out the repository.
  2. Sets up Node.js using the version specified.
  3. Installs the latest version of the wgc CLI tool.
  4. Creates feature subgraphs for all the GraphQL files modified in the pull request, provided that their corresponding subgraph configuration is specified in the cosmo.yaml file.
  5. Creates all the feature flags specified in the cosmo.yaml file.

Update

The update job is triggered when a pull request is synchronized. It performs the following actions:

  1. Checks out the repository.
  2. Sets up Node.js with the specified version.
  3. Installs the latest version of the wgc CLI tool.
  4. Creates/Updates the feature subgraphs for all the newly modified GraphQL files in the pull request, provided that their corresponding subgraph configuration is specified in the cosmo.yaml file.
  5. Updates all the feature flags specified in the cosmo.yaml file.

Destroy

The destroy job is triggered when a pull request is closed. It performs the following actions:

  1. Checks out the repository.
  2. Sets up Node.js using the version specified.
  3. Installs the latest version of the wgc CLI tool.
  4. Destroys all the feature flags and feature subgraphs created for the pull request.

Outputs

Limitations