Zenhub Repository for Zenhub Epics

⚠️ DEPRECATION NOTICE

This documentation describes Zenhub epics and legacy epics which have been removed from the Zenhub platform as part of the sub-issues migration in June 2025. It's kept for reference purposes only and the functionality will be removed in the coming months.

ℹ️ UPDATED DOCUMENTATION

Epics and Projects have been replaced with Issue Types and Sub-Issues. For current documentation, see:

• Issue Types - Creating and managing Epic, Project, and Initiative issue types
• Sub-Issues - Hierarchical relationships for breaking down work
• Working with Issues - Using issue types when creating strategic work items
• Getting Entity IDs - Finding repository and organization IDs for issue types

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

At the time, Zenhub Epics were organization-wide, which meant that every Epic created was accessible in all workspaces within the organization. However, in the future, Zenhub Epics were planned to 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 was required when creating Zenhub Epics through the public GraphQL API. Although the zenhubRepositoryId was optional to prevent disruptions, starting from October 1st, 2023, it became mandatory. Therefore, it was highly recommended to begin including this argument in requests to ensure they remained unaffected when the requirement came into effect.

Migration to Issue Types

The concept of repositories for epics has been replaced with Issue Types that can be created in any repository:

• Zenhub Issues: Create strategic issue types in your Zenhub repository
• GitHub Issues: Create issue types that sync with GitHub repositories
• Flexible Hierarchy: Use levels 1-5 to organize your work appropriately

For current implementations:

1. Get Repository IDs using the Getting Entity IDs guide
2. Create Issue Types using the Issue Types guide
3. Create Strategic Issues with appropriate types using the Working with Issues guide
4. Organize Hierarchically using the Sub-Issues guide

Legacy Examples (Deprecated)

The following examples are kept for reference only. Do not use these for new implementations.

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 did not need to specify the Zenhub Organization ID or the Zenhub Repository ID since these values were resolved from the Roadmap itself. The following steps demonstrated 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 required the Zenhub Repository argument, as a roadmap could 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
    }
  }
}