Zenhub

This connector uses the Zenhub GraphQL API (https://api.zenhub.com/public/graphql). Schema and examples: https://developers.zenhub.com/ (the Explorer shows the full schema).

Setup:

1. In Zenhub open the dashboard's API section (https://app.zenhub.com/settings/tokens) and create a Personal API Key for the GraphQL API. A user can have up to 5 keys.
2. Copy the key (it is shown once) into ZENHUB_API_KEY.

Authentication: Authorization: Bearer <key>. A 401 means the key is wrong or revoked. The key acts as its user: workspaces and repositories that user cannot see are missing from every result.

Where to start: zenhub_get_viewer checks the key and lists the organizations. Find a workspace with zenhub_search_workspaces (by name) or zenhub_list_organizations. Then zenhub_list_pipelines for the board columns and zenhub_list_pipeline_issues for the issues in one column. Sprints: zenhub_list_sprints then zenhub_list_sprint_issues. Epics: zenhub_list_epics then zenhub_list_epic_issues.

Ids: Zenhub uses its own opaque ids (for example Z2lkOi8vcmFwdG9yL0lzc3VlLzEwNzQyOQ) for issues, pipelines, sprints, epics and repositories; workspace ids are 24-character hex strings. An issue number plus a repository identifies an issue in zenhub_get_issue; the mutations need the Zenhub issue id.

Limits: each API key gets 90 seconds of processing time per minute (token bucket, headers X-RateLimit-Limit, X-RateLimit-Used, X-RateLimit-Remaining) and at most 30 concurrent requests. A single query may not exceed a complexity of 200 points: every field counts 1 and a connection multiplies its children by first. That is why the list tools default to 10 to 30 items and request few fields. Avoid polling; Zenhub offers webhooks for change notifications.

Pagination: Relay cursors. Pass pageInfo.endCursor back as after while pageInfo.hasNextPage is true. first may not exceed 100, and the complexity limit usually bites first.

Errors: a GraphQL answer can be HTTP 200 with an errors list; the tool then reports the message. "Field doesn't exist" means the query does not match the schema.

Beyond the typed tools: every GraphQL connector also gets zenhub_graphql_query (read-only, any query document), zenhub_graphql_mutation, and a schema tool, for operations not covered here (releases, roadmaps, dependencies, priorities, labels).

Writes: zenhub_move_issue, zenhub_set_estimate, zenhub_add_issues_to_sprints, zenhub_create_issue and zenhub_add_comment change the board or post content visible to the team.