How to Split Subgraphs across Repositories

Introduction

For larger teams and larger projects, it can make sense to split your subgraphs into multiple repositories contributing to the supergraph in the "parent" project. This approach enables teams to have independent software development lifecycles (SDLC) and CI/CD pipelines, providing better governance and control over their specific domains.

In this setup, one or more subgraphs are defined in each repository and depending on the role of the user on the cloud project, can be built and applied to the supergraph independently. Each subgraph typically represents a distinct data domain (e.g., users, orders, products) and can be managed by different teams.

Key Concepts

• Supergraph and subgraph builds are immutable and have unique IDs
• A subgraph must exist in the DDN project before inviting collaborators to it
• Each subgraph is namespaced and internal metadata objects cannot conflict with other subgraphs
• The GraphQL API is where subgraphs meet and conflicts can occur with root field and type names
• Subgraph prefixing can automatically remedy naming conflicts

Deployment with a multi-repository setup is effectively the same as deploying from a single repository, but with the considerations of managing your context to reference the shared project, and also being aware of the differences in abilities of the users building and deploying.

See the tables below for the roles and permissions of users on a Hasura DDN project.

DDN Advanced Plan required

In order to utilize multi-repository collaboration, you must have an active DDN Advanced Plan.

How it works

Parent Project:

The project Owner or Admin will need to:

1. Initialize a new local parent project
2. Initialize the corresponding cloud parent project
3. Initialize git for the parent project
4. Provision subgraphs on the cloud parent project
5. Create a base build of the cloud parent project
6. Invite collaborators to the cloud parent project

Independent Subgraphs:

The invited user will need to:

1. Create a new supergraph with a new subgraph and initialize a new repository
2. Initialize their cloud project as the parent project and link the new subgraph
3. Set the subgraph context
4. Create a subgraph build
5. Integrate the subgraph build into the parent project
6. Apply the build to be the official supergraph API (Owner, Admin, Subgraph Admin roles)

Create the Initial Parent Project

Begin by creating a "parent" project that will serve as the coordinated supergraph for your independent subgraph repositories. This central project will manage provisioning subgraphs, inviting collaborators, and maintaining the overall API.

Step 1. Initialize a new local project

This will serve as the parent project.

ddn supergraph init <parent-project> && cd <parent-project> && git init

This will scaffold the local configuration for your DDN project and initialize a Git repository.

Step 2. Initialize the cloud project

This is based on the local parent project.

ddn project init

In your configuration file (e.g., .hasura/context.yaml), you'll see a new project entry with the name of the project returned by the CLI.

Step 3. Create an initial commit

git add . && git commit -m "Initial commit"

Push this repository to your preferred hosting service to share it with collaborators.

Step 4. Provision subgraphs on the cloud parent project

If you know the subgraphs to include, you can provision them using the DDN CLI. Replace <subgraph-name> with the desired name:

ddn project subgraph create <subgraph-name>

You are also able to add a subgraph on the console in the Share > Invite a user > Granular access section.

On-Demand Subgraphs

Subgraphs can be added as needed when collaborators are onboarded.

Step 5. Create a base build of the cloud parent project

ddn supergraph build create

This initial build serves as the foundation for future subgraph builds.

Step 6. Invite collaborators to the cloud parent project

Navigate to your project's console and invite collaborators based on their roles:

Role	Abilities
Owner	All Project abilities including deletion. At this time, project ownership is not transferable.
Admin	Same as a Project Owner, excluding deletion of the project.
Read Only	Only explore and visualize the supergraph.
Subgraph Admin *	All subgraph development-related abilities: create subgraph build, apply subgraph build to endpoint.
Subgraph Developer *	Same as a subgraph admin, excluding the ability to apply subgraph build to endpoint.

* Subgraph roles are only available on DDN Advanced projects.

The following are the detailed permissions for the above roles:

Permissions	Owner	Admin	Read Only	Subgraph Admin *	Subgraph Developer *
View Supergraph Explorer	✅	✅	✅	✅	✅
Make GraphQL API requests	✅	✅	✅	✅	✅
View project insights	✅	✅	✅	✅	✅
Create supergraph builds - using all subgraphs' metadata	✅	✅	❌	❌	❌
Create supergraph builds - using single subgraph's metadata *	✅	✅	❌	✅	✅
Apply supergraph builds to project endpoint	✅	✅	❌	❌	❌
Create subgraph builds *	✅	✅	❌	✅	✅
Apply subgraph builds to project endpoint *	✅	✅	❌	✅	❌
Admin permissions on all subgraphs	✅	✅	❌	❌	❌
Create / Delete subgraphs	✅	✅	❌	❌	❌
Add / Remove collaborators	✅	✅	❌	❌	❌
Manage project plans and billing	✅	✅	❌	❌	❌
Delete project	✅	❌	❌	❌	❌

* Only available on DDN Advanced projects.

Each collaborator will receive an invitation to join the project and can proceed to add their subgraphs.

Independent Subgraphs

Each independent subgraph contributing to the parent project resides in its own separate repository and has it's own local supergraph. The repository could be an existing or newly initialized one.

Step 1. Create a new supergraph with a new subgraph and initialize a repository

The invited user will need to create a new supergraph on their machine with a new subgraph and initialize a repository.

They will use the same name for the subgraph as was created in the parent project.

ddn supergraph init <subgraph-name-as-supergraph-name> --create-subgraph <subgraph-name> && cd <subgraph-name> && git init

This scaffolds the necessary structure and initializes a Git repository.

Step 2. Initialize the cloud project as the parent project and link the new subgraph

This will initialize the cloud project as the parent project.

ddn project init --with-project <parent-project-name>

Your configuration file will now link the local subgraph to the parent project.

Local Development

You can add data sources and develop locally at this point. Check out relevant tutorials for adding sources.

Step 3. Set the subgraph context

ddn context set subgraph ./<subgraph-name>/subgraph.yaml

This sets the subgraph as the default for future CLI commands.

Step 4. Create a subgraph build

ddn subgraph build create

The CLI returns a build version for later integration into the parent supergraph.

Step 5. Integrate the subgraph build into the parent project

ddn supergraph build get

Use the latest build version from the parent supergraph and the subgraph build version in the following command:

ddn supergraph build create --subgraph-version <subgraph-name:build-version> --base-supergraph-version <parent-build-id>

This integrates the subgraph changes into an existing build of the parent supergraph.

Step 6. Apply the build

ddn supergraph build apply <supergraph-build-version>

This finalizes the integration, making the changes available to all collaborators. This command is only available to Owner and Admin roles. A Subgraph Admin can run:

Apply a single subgraph. Unavailable for Subgraph Developer role

ddn subgraph build apply <subgraph-build-version>

Build Summary

Supergraph and all subgraphs

Even though all subgraphs are not in the same repo, the ddn supergraph build create command will build the supergraph including all subgraphs which are on DDN cloud.

Once your context is set to the shared project, an Owner or an Admin role can build and apply the supergraph including all subgraphs.

As always, ddn supergraph build apply <supergraph-build-version> will make it the active supergraph API.

Subgraph Admin and Subgraph Developer cannot build or apply supergraphs.

Supergraph and specific subgraphs

An Owner or an Admin role can build and apply new supergraph and specify subgraphs to be built and applied.

You can also list the available builds of subgraphs to use with:

ddn subgraph build get

Build a supergraph based on a specific build and with mutiple specific subgraphs

ddn supergraph build create --subgraph-version <subgraph_name:subgraph_version> --subgraph-version <subgraph_name:subgraph_version>  --base-supergraph-version <supergraph_version>

See more about incremental builds here.

A single subgraph

An Owner, Admin, Subgraph Admin and Subgraph Developer role can build a single subgraph. All except Subgraph Developer can apply a single subgraph.

Build a single subgraph

ddn subgraph build create --subgraph-version <subgraph_name:subgraph_version> --base-supergraph-version <supergraph_version>

Apply a single subgraph. Unavailable for Subgraph Developer role

ddn subgraph build apply --subgraph-version <subgraph_name:subgraph_version>

Merging Existing Projects

If you have two independently developed projects on Hasura DDN that you want to merge into a single project with independent subgraph development, follow these steps:

1. Choose which project will be the main project and which will be the subgraph project
2. In the main project, create a new subgraph placeholder:

ddn project subgraph create <subgraph-name>

3. Invite the subgraph project collaborators with appropriate permissions
4. Once collaborators accept the invitation, they should set their project context:

ddn context set project <main-project-name>

5. Set up subgraph prefixes if needed to prevent naming conflicts
6. Create a subgraph build on the main project:

ddn subgraph build create

7. The main project owner/admin can then apply the subgraph build:

ddn subgraph build apply <subgraph-build-version>

Next steps

• Follow an end-to-end tutorial