What GitHub permissions does my team need for Zenhub?
Set up GitHub permissions, organizational access, and authentication for team collaboration
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. These permissions control access to repositories and determine the level of interaction users have with issues and projects.
Read permissions: Users can view repositories, issues, pull requests, and project boards but cannot 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: Users can create, edit, and modify issues, pull requests, and project content. This is the standard permission level for active team members who need to update work, move issues through pipelines, and collaborate on projects. Write permissions also enable drag-and-drop functionality in Zenhub boards.
Admin permissions: Users have full control over repository settings and can manage collaborators, webhooks, and integrations. Repository admins can configure advanced Zenhub features and manage workspace settings that affect the entire team.
Maintain permissions: Users can manage issues and pull requests without access to sensitive repository settings. This permission level works well for project leads who need more control than write permissions provide but don't require full administrative access.
Configuring GitHub organizational access
Your GitHub organization settings directly affect how team members can access and use Zenhub across your projects.
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. This approval process ensures Zenhub can read repository information, sync issue data, and provide reporting capabilities across your organization's projects.
Organization owners should review member access levels regularly, as GitHub organization membership affects Zenhub workspace visibility and creation permissions. Team members who are repository collaborators but not organization members may experience limited Zenhub functionality.
Setting up SAML authentication
Teams using SAML single sign-on need additional configuration to maintain seamless Zenhub access while meeting security requirements.
SAML SSO gives organization owners control over access to GitHub resources, which extends to Zenhub integration. 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. This prevents authentication disruptions that could interrupt project management workflows and ensures team members maintain consistent access to workspaces and reports.
Monitor SAML authentication status regularly, especially after policy changes or when team members report access issues. Re-authentication requirements can sometimes create temporary access disruptions that affect productivity.
Managing cross-organization collaboration
Teams working across multiple GitHub organizations need careful access configuration to maintain project visibility and collaboration capabilities.
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.
Consider the implications of different permission levels across organizations. Team members might have write access in one organization but only read access in another, which affects their ability to collaborate on cross-organizational projects.
Repository transfers between organizations require reconfiguring access settings and may affect existing Zenhub workspace configurations. Plan these transfers carefully to avoid disrupting ongoing project management workflows.
Troubleshooting common access issues
Address frequent collaboration and access problems that affect team productivity.
Organization not appearing in Zenhub: Check GitHub third-party application restrictions and ensure Zenhub has organizational approval. Organization owners may need to explicitly 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 functionality: 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.
Configuring repository-specific settings
Fine-tune access settings at the repository level to match your team's collaboration needs and security requirements.
Repository visibility settings affect how team members discover and access projects in Zenhub. Private repositories require explicit access grants, while public repositories allow broader organizational access depending on your Zenhub organizational settings.
Branch protection rules in GitHub can affect how Zenhub integrations work with pull requests and issue management. Configure these rules to support your workflow while maintaining appropriate code quality controls.
Webhook configurations ensure Zenhub receives timely updates about repository changes. Verify that webhooks are properly configured when setting up new repositories or when experiencing synchronization issues.
Best practices for access management
Implement systematic approaches to collaboration and access configuration that scale with your team's growth and changing needs.
Review organizational access permissions quarterly to ensure they align with current team structures and project requirements. Remove access for departed team members and adjust permissions for team members whose roles have changed.
Document your access configuration decisions and policies so team members understand permission levels and know how to request appropriate access for their work requirements.
Test access configurations with new team members during onboarding to identify potential issues before they affect productivity. This proactive approach helps maintain smooth collaboration workflows.
Consider implementing gradual permission escalation, starting new team members with read access and increasing permissions based on their responsibilities and familiarity with your workflows.
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 as a third-party application, 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), while 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. Some organizations require daily authentication, while others allow longer sessions. 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 if they have Zenhub workspace access. Workspace membership doesn't override GitHub repository security.
Q: What happens when we transfer a repository between GitHub organizations?
A: Repository transfers may affect Zenhub workspace configurations and access permissions. Plan transfers carefully, reconfigure access settings in the destination organization, and verify that team members maintain appropriate permissions after the transfer.
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.