Fedora Docs GitLab permissions

Hi all, because of the way the gitlab SAML authentication works, there are some questions that we need to resolve on how to grant access to the Fedora Docs GitLab subgroup (Fedora Docs · GitLab)

Basically the background here is that if you enable SAML enforcing, only users that have authenticated with their Fedora Account can contribute to the repos. However the side effect that is undesirable is that the repos are then hidden unless you have logged in with your Fedora Account (i.e. Private unless logged in).

To work around this, the Fedora gitlab instance has disabled SAML enforcing – but this means that someone without a Fedora Account can be granted commit access. We can, however, then enforce SAML group links – which means that only someone in a Fedora Accounts group is given a certain role in gitlab.

You can go super granular, but will need a Fedora Accounts group for each gitlab role. Over on Fedora Websites and Apps, the plan is to map:

  • the websites-apps Fedora Accounts group to the developer role in gitlab
  • the websites-apps-admin Fedora Accounts group to the admin role in gitlab

Long story short, what groups in Fedora Accounts should we link to what roles in the Fedora Docs gitlab subgroup?

1 Like

I think we can at least have an admin group (docs-admins for instance) for the whole Fedora docs group.
For the developer role group, I’m not sure. Can we combine both methods, as in having users from the SAML group and users access granted manually?
The reason I’m asking this is we may host, in this group, documentation repositories that are not directly maintained by the Fedora Docs team. Users outside of the team may need access, without being part of the Documentation team, and be granted commit access to all other repositories.

We have a meeting later tonight, and I think we should talk more about this.

1 Like

I am not sure if this effect is negative… as long as “can be granted” does not mean “can automatically commit”. As @darknao said, authors / contributors can be from outside. If they can use their usual GitLab account (which is much more widespread than FAS / pagure accounts), this effect can decrease the “entry barrier” to contribute.

1 Like

If we do this, let’s make sure authors understand that their contributions are CC-BY-SA (or otherwise match the license of the particular doc).

1 Like

I think, now that the SAML authentication is no longer enforced, contributors without Fedora Accounts can still contribute through Merge Request. They will just not be able to push commit/merge MR directly in the repositories. For that, you’ll need to get the developer role.

1 Like

One special repository is package-maintainer-docs.
It is currently under fedora-docs in Pagure
and the plan is to move it to GitLab together with the other docs repos.
However, it is not maintained by the Docs team
but by all package maintainers collectively.
For better or worse, this system was inherited from the old wiki category when it was migrated to become the Package Maintainer Docs.
So, how it should work in Pagure already,
is that the packager group in Fedora Accounts should have commit privileges.
For some technical reason I do not understand,
that is not possible with Pagure and Fedora Accounts.
Maybe it was that the packager group is of wrong type in Fedora Accounts.

If the same restriction does not apply for GitLab,
then the solution would be that packager in Fedora Accounts maps to packager role in GitLab,
and that role has commit access to package-maintainer-docs.
Alternatively, we can keep adding commit rights to individual packagers as needed,
like we have been doing in Pagure
(through a separate Pagure group just for this purpose).

EDIT: In case there are any problems,
just leaving this particular repository behind in Pagure is a valid option.
Pagure has served us well enough.

1 Like

all the other groups seem to be settling on <groupname>-admin could we consider using docs-admin rather than docs-admins?

yes, i believe you can manually add roles to individual repos separately, and as long as a SAML link is not set up for that specific repo, it will stick.

1 Like

Yes, it is possible to add a SAML group link on a subgroup, so granting everyone in the Packager group in Fedora Accounts, the Developer role on, say a “Packaging Docs” subgroup that contains the Packaging Documentation repos will work.

Ok so that’s perfect then.
Let’s start with:

  • the docs Fedora Accounts group to the developer role in gitlab
  • the docs-admin Fedora Accounts group to the owner role in gitlab (or mainteners if you’d rather not grant owner permissions)

@oturpe we agreed in our last meeting that repository not maintained by the team shouldn’t be in the Fedora Docs group on GitLab. That was decided mainly to avoid permission issues.

Since the SAML link only works with Gitlab Group (or sub-group), it might be more interesting for you to have your own group in the Fedora namespace, rather than Fedora Docs.
That will allow you to host other non-docs related in your own group later if you ever need to.
If you’re only planning to have docs repository here, then I guess the Fedora Group is still a valid option now that we know we can mix SAML link with sub-group.

In the end, I’ll leave it up to you to decide if you want to move to gitlab in the first place, and where you want your repository.


This should be set up and ready to go now.

  • All users that are members of the docs group in Fedora Accounts will be granted access as a Developer on the Docs GitLab group (and its repos)

  • All users that are members of the docs-admin group in Fedora Accounts will be granted access as a Owner on the Docs GitLab group (and its repos)

Note that for this to work, all users will need to link (or re-link) their Fedora Account with GitLab. To do this,

  1. first create or log into your GitLab Account
  2. Go to this link: https://gitlab.com/groups/fedora/-/saml/sso and log in with your Fedora Account and follow the prompts to link it to you GitLab Account.

@darknao @bcotton @pbokoc currently you all are the sponsors and only members of the docs-admin group, but you can add new members whenever you want :slight_smile: – just remember that the user will need to log-in with the SAML sso link for the permissions to apply.