Managing access control lists - sauter-hq/git-guidelines GitHub Wiki

Git rights

Due to technical limitations it is only possible to grant rights to individuals or teams on a repository level.

It is not currently possible to grant special rights to specific folders or files within a repository.

This is not specific to Github, most Git servers do not provide deeper granularity with ACLs. The reason for this is that Git has internally a limited concept of folder structure and contents. Filtering on a per-file-level can cause serious issues with certain advanced operations Git does internally. The resulting divergence between client that did accept certain commits and servers that did not will cause a nasty de-synchronisation.

Modifying a repository without write access

If you only have read access and you desperately need to add code, here's what to do:

Fork the repository on the Github webinterface. (This will create a new repo named like username/projectname)
Work on the code, add/fix stuff.
Create a pull request on the Github webinterface. The maintainer of the project can then quickly review and merge your changes into the main repository.

Users, Organizations, Teams

The Github Teams and Organizations may appear a bit unconventional at first. But once you've understood them, they're fairly simple. As an added bonus, they force the ACL system to stay simple and not become full of exceptions and special cases.

Here's how they work:

Team (group)

A Team is a group of users.
A Team always belongs to one Organization.
A Team has one permission type assigned to it. (Read Only, Read+Write, Read+Write+RepoAdmin)
A Team is populated with Users by the Organization owners that the Team belongs to.

User (account)

A User is a user account. Each real life User has one account. Nothing fancy here.
A User can have multiple repositories attached to him/her.
A User is not associated with an Organization at all.
A User can be in multiple teams (and therefore in multiple Organizations).

Organization (account)

An Organization can have multiple repositories attached to it.
An Organization has one or more Users defined as "owner" for management purposes.
An Organization can have multiple Teams

What permission types can a Team have?

A Team can have exactly one (and only one!) permission type. This type applies to this Team over all repositories inside an Organization.

However the Organization owners can decide which repositories are of interest for a Team.

How do I set up a team

Team rights can be configured as explained after the jump : How do I set up a team.

Example:

There is an Organization called "Engineering".
Engineering consists of 3 actual groups of people: Management, BackendCoders and FrontendCoders
Engineering has several projects going, each project has an own repository.

Now we go into the Organization Engineering and create 3 Teams with the names given above.

But upon creation we are asked for a permission type: ReadOnly, Read+Write, Read+Write+Admin.

Now you probably wonder: Why does it ask this upon creation of the Team? Why does it not ask for the type when we assign the Teams to a repository?

==> And this is the special part that you need to always keep in mind: A Team's permission type is fixed and not per-repository!

So what if you need a Team to have ReadWrite on one repo and ReadOnly on another in the same Organisation?

=> You currently have two possibilities:

Add two Teams for each actual team. One with RO and one with RW in the name. (not recommended)
Add a global read-only Team to the Organization containing the total of all people in all the teams. (recommended solution)

So in our example we would go into the management of the repository for Project1 and add the teams: FrontendCoders and EngineeringAllReadOnly. We cannot specify their access at this time, we can only "add" them to the repository at this time.

Now all FrontendCoders can pull and push to Project1, while BackendCoders can only pull and create forks on their own.