Metadata-Version: 2.4
Name: splent_feature_github
Version: 0.3.0
License-Expression: LGPL-3.0-or-later
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: COPYING
License-File: COPYING.LESSER
Dynamic: license-file

# splent_feature_github

The `github` feature of a [SPLENT](https://splent.io) product line.

Sign in and sign up with GitHub, and connect a GitHub account to an account
from its profile. identities runs the sign-in for every provider, and this
feature describes GitHub to it: its endpoints, its scope (`GITHUB_SCOPE`),
and how to read who signed in from its API, the verified address included.
A new account takes an address GitHub verified (from `/user/emails`, the
primary one first, never the public one on `/user`) and the name it gives,
and the person adds the surname before it is opened. A GitHub account
always signs in to the account it is linked to, and never to an existing
account because the email matches. It needs `auth`, `profile` and
`identities`, which keeps the linked accounts.

A SPLENT feature is a Python package that a product composes with others.
Its models, routes, services, templates and hooks are registered when the
product starts. What this feature provides and requires is listed in the
`[tool.splent.contract]` section of `pyproject.toml`, which
`splent feature:contract --write` keeps in sync with the source.

## Settings

| Setting | Default | What it is |
|---|---|---|
| `GITHUB_CLIENT_ID` | empty | The client id of the OAuth app registered at https://github.com/settings/developers |
| `GITHUB_CLIENT_SECRET` | empty | Its secret |
| `GITHUB_SCOPE` | `user:email` | What the sign-in asks GitHub for. `user:email` lets `/user/emails` say which addresses GitHub verified; without it every new account asks for an address, which then has to be confirmed by mail |

Without both, GitHub sign-in is off: the app logs a warning at start, and
whoever tries is told it is not available. The callback registered with
GitHub is `<OAUTH_REDIRECT_BASE_URL>/github/authorize` (identities' setting).

## Where it shows

It fills the slots other features open, by name, so it composes with
whatever the product has and overrides nothing.

| Slot | Opened by | What GitHub draws |
|---|---|---|
| `auth.login.providers` | auth | The GitHub button, under "or continue with" |
| `signup.providers` | signup, when the product has it | The same button, after the sign-up form |
| `profile.edit.sections` | profile | The linked account, as a link to it on GitHub, with a disconnect button, or a "Connect GitHub" link |
| `layout.head.css` | the product's app shell | Its stylesheet, `assets/css/github.css` |

It takes order 10 in the first three, before ORCID's 20. The button carries
where the reader was heading (`?next=`), and only a path on this site. The
disconnect button opens identities' modal.

GitHub's dark grey is in `assets/css/github.css`, never on the elements. The
public shell loads the file from the asset registry (`register_asset`), and
the app shell, which does not render the registry, through
`layout.head.css`. A product that wants another look overrides
`.btn.btn-github` and the `github-identity__*` classes in a stylesheet of its
own.

## A product without signup

A product that does not install `splent_feature_signup` is closed, and its
accounts are opened by an administrator. GitHub follows the rule identities
holds for every provider.

| Visitor | With signup | Without signup |
|---|---|---|
| Signs in with a GitHub account already linked | Signed in | Signed in |
| Connects GitHub from their profile | Linked | Linked |
| Signs in with a GitHub account linked to nobody | Asked for the details of a new account, which opens at once with GitHub's verified address, or, when GitHub verified none and the person typed one, once the person follows the link mailed to it and signs in with GitHub again, if the product confirms addresses | Sent back to the login page with a translated message that asks them to request access from an administrator, or to connect GitHub from their profile if they have an account |

## The github table

Earlier versions kept every linked GitHub account twice: in
`external_identity`, which signs people in, and in a `github` table keyed by
profile, which only `get_github()` read and nothing called.
`github0002_into_ext_identity` folds the table into `external_identity` and
drops it, and `get_github()` goes with it. Each row becomes the account's
GitHub identity (its numeric id as text, its login as the username), or
completes the one it already has. A row that would lose a link or give it to
another account stops the migration before anything changes, and the
message names the rows. The downgrade puts the table back with a row for
every GitHub identity of an account with a profile.

## Translations

The edit-profile row and the messages about GitHub's answers ship with a
Spanish catalog.

## Use it in a product

```bash
splent feature:add splent_feature_github
```

## Develop

The tests simulate GitHub (`tests/conftest.py`): the flow's OAuth client
answers the token exchange, `/user` and `/user/emails` as each test chooses.

```bash
splent feature:test splent_feature_github --with identities --with orcid
splent feature:contract splent_feature_github
```

## Release

```bash
splent feature:release splent_feature_github --dry-run --bump patch
splent feature:release splent_feature_github
```

The first command rehearses the release and changes nothing. The second
publishes it to the git forge and to PyPI, and a PyPI version is permanent.
This version needs the identities that brings the shared flow and
`provider_email_verified`, so the two are released together.
