bot user and access token requirements

[ekallevig]

Maybe I'm missing it somewhere, but the start-to-finish steps for running this seem a little unclear. I've gleaned that you need a bot server running gu-who (done that) and you also need a people repo (done that), but there's some other details that are referenced in passing without enough detail, such as:

1. I'm assuming a bot github user needs to be created -- what kind of access? just to the people repo? etc.
2. What scopes should be enabled on the access token (per https://developer.github.com/v3/oauth/#scopes)?

Would really love a step-by-step list for the whole process like this:

1. setup bot server
2. create people repo
3. create bot user
4. generate key

Even if those steps just link off to existing READMEs.

Thanks! Looks like a cool tool.

[ekallevig]

I just saw the scope: repo, write:org message on the bot server page -- might be more clear to have all those steps in one place though.

[rtyley]

Hi there @ekallevig - thanks for your interest in gu:who, hope it can be of use to you!

It was our aim was for the running instance of gu:who to guide you with all the bits of information you need - we haven't probably quite managed to do that as clearly as we should, but most of what you need is there. So if you look at the opening page of a gu-who instance (for instance at https://gu-who.herokuapp.com/ ), you'll see:

...as you can see, the required scopes are repo & write:org.

If you login, or provide an access token, you'll see a page like this:

You're told that all the GitHub issues raised by gu:who will appear to be raised by the account you just logged in with. So it's up to you, you can have them raised as yourself, or you can have them raised by a fresh bot account you create (which I would recommend) - either way, it's best to be consistent on subsequent runs.

The one other wrinkle about the bot account is that due to GitHub restrictions, it can't do the Two-Factor-Authentication checking unless the bot is an owner for that org - this is mentioned in really small type on the opening page:

Aside from that aspect, at the moment bot only needs access to the people repo (tho' if it's an owner, it can access all repos in the organisation).

There are also some instructions on setting up gu:who on Heroku here:

https://github.com/guardian/gu-who/blob/53e806/heroku.md

I'll have a think about presenting this information in a different way, in the mean time, let me know how you go!

[ekallevig]

@rtyley Perfect thanks -- exactly the kind of info I'm looking for (and you're right it mostly is all available in various spots). Thanks again.

[ekallevig]

@rtyley One other question -- I'm a little nervous to grant write:org access, would prefer to keep this experiment scoped to the one repo. Is it necessary to write group membership?

[rtyley]

I'm a little nervous to grant write:org access, would prefer to keep this experiment scoped to the one repo.

The write:org permission is actually surprisingly weak, all it does is allow gu:who to 'conceal' organisation membership - so if you have org members who are not passing your requirements, they won't be visible to the general public as members of your org.

After 4 weeks of a user failing requirements, gu:who does actually remove them from your org, but this actually requires them to be an organization admin (which is also required for 2FA support).

https://developer.github.com/v3/orgs/members/#remove-organization-membership

Currently gu:who is all about auditing org membership, not the collaborators on a single repo, so if you just want to control access to a single repo, it's probably not suitable for you right now.

[ekallevig]

It's only the writing of data that I was concerned with keeping scoped to the one (people) repo -- just out of an abundance of caution with a 3rd party bot. But you're right that write:org is limited enough that I'm fine with it. So to be clear, the token would need additional admin:org permissions to do the 4-week removal process, correct? Is that something that can be turned on/off easily?

[rtyley]

Surprisingly, GitHub doesn't seem to require the admin:org permission in order to be able to remove a user - we don't add that permission for our own gu:who bot:

"In order to remove a user’s membership with an organization, the authenticated user must be an organization admin."
https://developer.github.com/v3/orgs/members/#remove-organization-membership

The repo scope is the one you want to be aware of. It grants read/write access to all public and private repositories that the bot-user can see. I have asked GitHub to support finer-grained read:private_repo & write:labels scopes, but unfortunately, for the time being, this scope is the only one available to allow gu:who bot to read & set labels on the private people repository.

So this brings you down to a single choice so far as security goes- you can't do anything useful with scopes, but you can decide how powerful the bot user is. There are two meaningful choices:

a) bot is an org-owner - it can check 2FA and remove users
b) bot only has write access to the people repo - it can't do 2FA checks, or evict users

It's up to you which you choose, but we only run gu:who as with option a) in our organisation.

[afeld]

Currently gu:who is all about auditing org membership, not the collaborators on a single repo

We can take this to a separate issue, but would there be interest in gu-who also auditing collaborators on repositories?