GitHub Permissions
Set up GitHub permissions, organizational access, and authentication for team collaboration in Zenhub.
Configuring collaboration and access settings ensures your team can work together effectively in Zenhub while maintaining appropriate security controls. This involves setting up GitHub permissions, managing organizational access, and configuring authentication systems like SAML.
Understanding GitHub permission levels
GitHub permissions form the foundation of what team members can do in Zenhub workspaces.
Read permissions allow users to view repositories, issues, pull requests, and project boards but not make changes. In Zenhub, this means they can see workspace content and reports but cannot move issues between pipelines, create new issues, or modify existing work.
Write permissions allow users to create, edit, and modify issues, pull requests, and project content. This is the standard level for active team members who need to update work and move issues through pipelines. Write permissions also enable drag-and-drop functionality on the Work Tracker.
Maintain permissions allow users to manage issues and pull requests without access to sensitive repository settings. This works well for project leads who need more control than write permissions provide but don't require full admin access.
Admin permissions give full control over repository settings and the ability to manage collaborators, webhooks, and integrations. Repository admins can configure advanced Zenhub features and workspace settings that affect the entire team.
Configuring organizational access
Navigate to your GitHub organization settings and review the third-party application access policies. Zenhub requires approval as a third-party application to access your organization's repositories and provide project management capabilities. If your organization restricts third-party applications, you'll need to explicitly approve Zenhub access.
Organization owners should review member access levels regularly. Team members who are repository collaborators but not organization members may experience limited Zenhub functionality.
Setting up SAML authentication
When your GitHub organization uses SAML authentication, team members must periodically re-authenticate their Zenhub access to maintain connection to organizational resources. Configure your SAML settings to include Zenhub as an approved application to prevent authentication disruptions. Monitor SAML authentication status regularly, especially after policy changes or when team members report access issues.
Cross-organization collaboration
Each GitHub organization requires separate Zenhub access approval and configuration. When workspaces span repositories from multiple organizations, ensure each organization has appropriate third-party application settings and team member permissions. Repository transfers between organizations require reconfiguring access settings and may affect existing Zenhub workspace configurations.
Troubleshooting access issues
Organization not appearing in Zenhub
Check GitHub third-party application restrictions and ensure Zenhub has organizational approval. Organization owners may need to grant access through GitHub's application management settings.
"Workspace cannot be loaded" errors
Usually indicate insufficient GitHub permissions or third-party application restrictions. Verify that users have appropriate repository access and that organizational settings permit Zenhub integration.
Inconsistent drag-and-drop
Requires write permissions for underlying repositories. Team members with read-only access cannot move issues between pipelines even if they have Zenhub workspace membership.
Intermittent access issues
Often relate to SAML re-authentication requirements or changes in GitHub organization membership. Review authentication status and organizational membership when access problems occur sporadically.
FAQ
Q: Why can't some team members see our GitHub organization in Zenhub?
A: This usually indicates third-party application restrictions in your GitHub organization settings. Organization owners need to approve Zenhub, or team members need to be organization members rather than just repository collaborators.
Q: What's the difference between GitHub repository permissions and Zenhub workspace access?
A: GitHub permissions control what users can do with issues and repositories (read, write, admin). Zenhub workspace access controls visibility of workspace-specific features like boards and reports. Both must be appropriately configured for full functionality.
Q: How often do team members need to re-authenticate when using SAML?
A: Re-authentication frequency depends on your organization's SAML policy settings. Check with your IT team for your organization's specific requirements.
Q: Can team members work on issues from repositories they don't have direct access to?
A: No. Team members need appropriate GitHub repository permissions to view and interact with issues, even with Zenhub workspace access. Workspace membership doesn't override GitHub repository security.
Q: How do we grant Zenhub access for a new GitHub organization?
A: Navigate to your GitHub organization settings, find the third-party applications section, and approve Zenhub access. Organization owners or members with appropriate permissions can complete this approval process.