Recommended Access method with Github (with documentation)

[rufuspollock]

There are several options:

• Personal access token: easiest to setup and use but means that all access is via that single user
• Github App - see #15: probably the best but more complex - see #15 for details
• OAuth flow (not so relevant as we are not having users on CKAN/DataHub authenticate into github via OAuth flow)

Acceptance

• [x] We have a default method
• [x] It is documented in the README

Tasks

• [x] Analyse options (with estimates / trade offs)
• [x] Choose option
• [x] Implementation work (if any)
• [x] Document option

Analysis

@shevron comment

We prefer something that is not a personal access token because a personal access token is specific to a user and we want commits to be from "XXX" as the system and not personal.

An App is probably the right way, even if it is more cumbersome to set up. Note that what they need is a "GitHub App" and not an "OAuth App" (which is also personal and takes on the identity of the user in OAuth type flow). See https://docs.github.com/en/developers/apps/differences-between-github-apps-and-oauth-apps#token-based-identification for more on this.

It may be good for us to try and set up metastore-lib / ckan as a GitHub App on the Datopian account or a test account so we know what the process looks like and can better guide other users.

[rufuspollock]

@shevron could we not go with a personal access token for the time being? May not be perfect but it would work (and commits can still use the right email/user id of actual user doing the commit right?)

[shevron]

@rufuspollock yes we can, and commits will be assigned to the right owner (should be and this is tested at least on the metastore-lib level).

The only downsides I see to PAT are more administrative - e.g. a user leaves the org or decides to revoke the token not following IT procedures, etc.

[rufuspollock]

@shevron ok, i think we go for PAT for now and have this as a flag in backlog to improve at a later point.

@shevron can you add (brief) docs to README documenting that we use PAT for token, how to get PAT (may just be a link), and possibly a link to this issue with more detail on other options.

[shevron]

@rufuspollock of course. I'm trying to move most of the documentation out of the README and to https://metastore-lib.readthedocs.io/en/latest/ - unless you have any objections, I'll document it in the currently empty GitHub backend section.

[rufuspollock]

@shevron that is ok with me though i have a slight preference for simple / non rtd solution i.e. plain markdown and we deploy on github pages (i like vuepress quite a bit if we need something or mkdocs ...). [Note this is a preference and if you prefer rtd that is ok with me]

[shevron]

readthedocs.io supports plain markdown (as well as combining plain markdown with rst for when you need things for example like automatic Python API documentation generation).

[shevron]

This is now documentated in the GitHub backend docs: https://metastore-lib.readthedocs.io/en/latest/backends/github.html

[shevron]

I am closing this for now as I think we have a recommended method for now (PAT) and in the future we will recommend PAT for quick use in small organizations and GitHub App installation for more robust / production installations, once #15 is implemented