GitHub Teams in the VA

Teams

Teams are the best way to group users and provide access to repositories. Teams give you the ability to create groups of organization members with read, triage, write, maintain, or admin permissions to repositories that belong to the organization. Teams are also central to many of GitHub’s collaborative features, such as team @mentions, which notify appropriate groups of people that you’d like their input or attention. Teams can be both project or subject-matter focused, and can relate to job titles or roles. Teams are also useful for CODEOWNERS files to define and automate the pull request review process.

Repository permission levels

Teams allow you to create groups with separate levels of access and visibility within an organization:

• Read: Recommended for non-code contributors who want to view or discuss your project
• Triage: Recommended for contributors who need to proactively manage issues and pull requests without write access
• Write: Recommended for contributors who actively push to your project
• Maintain: Recommended for project managers who need to manage the repository without access to sensitive or destructive actions
• Admin: Recommended for people who need full access to the project, including sensitive and destructive actions like managing security or deleting a repository

To read more granular action-availability information for each permission level, see repository access for each permission level.

Team maintainers

Team maintainers are primarily responsible for adding and removing team members day-to-day, as needed. Each team should have at least a couple team maintainers, but could need more depending on team size. Team maintains should know what they’re responsible for, including adding another appropraite maintainer if they leave the team.

Members with team maintainer permissions can:

• Change the team’s name and description
• Change the team’s visibility
• Request to add a child team
• Request to add or change a parent team
• Set the team profile picture
• Edit team discussions
• Delete team discussions
• Add organization members to the team
• Remove organization members from the team
• Promote an existing team member to team maintainer
• Remove the team’s access to repositories
• Manage code review assignment for the team
• Manage scheduled reminders for pull requests

Adding and removing team members

A maintainer needs to know the team and the GitHub.com username of the person they want to add or remove. There is only one removal process, but there are two processes to add team members:

• Adding users who are members of the VA organization
• Adding users who are not members of the VA organization

Adding users who are members of the VA organization

As long as the users are already a part of the VA organization on GitHub.com, team maintainers can add them without needing help from the GitHub team.

As an example:

• The VertX team in the VA organization on GitHub.com is: @department-of-veterans-affairs/vertx-write
• The maintainers of this team have a maintainer label next to their username
• Any maintainer can remove or invite users to the team and thereby revoke or grant access to all of the team’s repositories

To remove members from the vertex-write team, maintainers should

1. Ensure they’re in the members area
2. Search for the user or find them in the member list
3. Check the box to the left of their username
4. Click the dropdown for member selected at the top of the list
5. Click Remove from team...
6. Confirm the action by clicking Remove members

Note: You can remove multiple members at once by checking multiple boxes next to the appropriate usernames.

To add members to the vertex-write team, maintainers should

1. Ensure they’re in the members area
2. Click on the Add a Member button at the top-right of the page
3. Enter the GitHub.com username of the person they wish to invite to the team
   • Ensure you have the correct username
   • You could also invite by VA email (the user must have this email address associated with their account)

The invited user will get an email notifying them they have been invited to the team, and they must accept that invitation to complete the process.

Adding users who are not members of the VA organization

If the users are not already members of the VA organization on GitHub.com, then they need to fill out the access request form on the VA OIT website. This form requires they register for GitHub.com first, if they don’t already have a GitHub.com username.

When maintainers attempt to add users that are not a part of the organization, they will be notified when searching for that username:

Need help?

For further assistance with user management, file an issue in the github-user-requests repository on GitHub.com.

Return to Guides