feat: add support for repo team/collaborator permissions

[ruizink]

Description

Adds the ability to configure permissions for both Teams and Collaborators inside a Repository

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Chore (refactoring, CI changes, dependency updates, etc.)

Checklist

• My commits follow the Conventional Commits format
• I have added/updated unit tests for any new or changed templates
• I have updated documentation (README, CONTRIBUTING, values comments) if needed
• I have updated the generated CRDs and Manifest

Related Issues

[tstollin]

Thank you @ruizink for your contribution!

I like the design on referencing the team from the repository spec in contrast to the way the GitHub API handles this (repos are added to teams), as this approach keeps the relevant information in one spec.

Unfortunately, I found some issues that would need to be addressed before being able to merge this PR. Please refer to the attached comments.

Of course, feel free to ask if something is unclear or you want to discuss some points. :)

[tstollin]

i see an important design gap in this reconciler: collaborators are invited upon being added to a repository. Until they have accepted the invite they will not be returned as collaborators and the reconcile loop would try to send out further invitations by adding the user to the repository as collaborator (if that is even possible).

This reconciler needs to be redesigned to handle open invitations and take them into consideration with regards to the desired state stored in github. additionally, it needs to update or even recall any open invitations if the permissions change.

This should map out the possible states:

Desired	GitHub state	Action
✅ Present	Not collaborator, no pending invite	AddCollaborator (send invite)
✅ Present	Pending invite, same permission	No-op
✅ Present	Pending invite, different permission	Cancel invite → AddCollaborator
✅ Present	Accepted collaborator, same permission	No-op
✅ Present	Accepted collaborator, different permission	AddCollaborator (updates permission)
❌ Not present	Pending invite	Cancel invitation
❌ Not present	Accepted collaborator	RemoveCollaborator

[tstollin]

also we need to consider the case where users decline invitations. I'm not sure how to handle this, but I'm sure that it would be bad design to just reinvite them until they accept the invitation.

[ruizink]

This completely flew under the radar for me, because my Orgs belong to an Enterprise with EMU, in which case, there's no invitation workflow. Definitely something super important!

[tstollin]

As far as I understand you, you only need both features for an enterprise environment. I think it would be way easier for now if you just add the support for enterprise orgs (using func (o *Organization) HasEnterpriseFeatures() bool and skipping reconciliation if it returns false). This way you need not care about the invitation flow and the distiction between external or org collaborators.

The implementation for non-enterprise orgs could then be added later.

[ruizink]

The thing is, an Organization with Enterprise plan can still follow the invitation workflow, as long as the Enterprise doesn't use EMU (external IdP).

Team permissions on repository are not affected by this intitation workflow.

Another option for collaborators would be to check if the user is a member of the organization. Skip if it's not a member, so that no invite is ever sent. (Pretty much what's done when managing team members here). This will limit the functionality to org members, though. External collaborators, which require an invite would be skipped.

WDYT?

[tstollin]

Sounds good to me. Just to double-check, that I understood you correctly; this would amount to

• reconciling repository team permissions
• reconciling repository collaborators while limiting it to usernames of org members for now

If this is correct I would like to see clear documentation of the org-members-only restriction, but otherwise you are good to go.

[tstollin]

closed+reopen to trigger workflows after fix #73

[tstollin]

@ruizink I'm not sure about the state of this PR (i.e. whether you are still working on it). If you want me to review it again, please request a review via the GitHub UI. Thanks

[ruizink]

@tstollin I'm going to give this a thought during my holidays. I'll get back to you as soon as I have something new. In the meantime, I'm going to mark this PR as draft.
Thanks!