Zenhub Repository for Zenhub Epics

Note: This documentation is specifically focused on Zenhub Epics. If your organization utilizes Legacy Epics, the information provided in this article does not apply to you. For further details, please refer to the Zenhub Epics vs Legacy Epics guide.

At present, Zenhub Epics are organization-wide, which means that every Epic created is accessible in all workspaces within the organization. However, in the future, Zenhub Epics will be scoped to individual workspaces, allowing them to be shared among other workspaces similar to Zenhub Issues.

To facilitate this change, a new parameter called zenhubRepositoryId will be required when creating Zenhub Epics through the public GraphQL API. Although the zenhubRepositoryId is currently optional to prevent disruptions, starting from October 1st, 2023, it will become mandatory. Therefore, it is highly recommended to begin including this argument in your requests now to ensure they remain unaffected when the requirement comes into effect.

Examples

Create Zenhub Epic

Retrieve the Zenhub Repository ID and the Zenhub Organization ID for your workspace:

query zenhubRepositoryandOrganization($workspaceId: ID!) {
  workspace(id: $workspaceId) {
    zenhubRepository {
      id
    }
    zenhubOrganization {
      id
    }
  }
}

Create the Zenhub Epic:

mutation createZenhubEpic($zenhubRepositoryId: ID!, $zenhubOrganizationId: ID!, $title: String!, $body: String) {
	createZenhubEpic(input: {
    zenhubRepositoryId: $zenhubRepositoryId,
    zenhubOrganizationId: $zenhubOrganizationId,
    zenhubEpic:{
      title: $title,
      body: $body
    }
  }) {
    zenhubEpic {
      id
    }
  }
}

Create Zenhub Epic on Roadmap

To create a Zenhub Epic on the Roadmap, you do not need to specify the Zenhub Organization ID or the Zenhub Repository ID since these values are resolved from the Roadmap itself. The following steps demonstrate how to create a Zenhub Epic on the Roadmap:

Obtain the Roadmap ID for your workspace:

query roadmap($workspaceId: ID!) {
  workspace(id: $workspaceId) {
    roadmap {
      id
    }
  }
}

Create the Zenhub Epic:

mutation createZenhubEpicOnRoadmap($roadmapId: ID!, $title: String!, $body: String) {
  createZenhubEpicOnRoadmap(input: {
    roadmapId: $roadmapId,
    zenhubEpic: {
      title: $title,
      body: $body
    }
  }) {
    zenhubEpic { 
      id
    }
  }
}

Create Zenhub Epic on Project

Creating Zenhub Epics on Projects requires the Zenhub Repository argument, as a roadmap can contain projects from multiple workspaces. To create a Zenhub Epic within a project, follow these steps:

Retrieve the Zenhub Repository and Project IDs:

query zenhubRepositoryAndProject($workspaceId: ID!,  $query: String) {
  workspace(id: $workspaceId) {
    zenhubRepository {
      id
    }
    projects(query: $query) {
      nodes {
        id
        name
      }
    }
  }
}

Create the Zenhub Epic:

mutation createZenhubEpicOnProject($projectId: ID!, $zenhubRepositoryId:ID!, $title: String!, $body: String) {
  createZenhubEpicOnProject(input: {
    projectId: $projectId,
    zenhubRepositoryId: $zenhubRepositoryId,
    zenhubEpic: {
      title: $title,
      body: $body
    }
  }) {
    zenhubEpic { 
      id
    }
  }
}