Ontology Curation - Github Sync

[wenzel_int]

Concept

Each working ontology is stored as a public repository in the mds-ontologies organization. The canonical RDF file is ontology.ttl at the repo root. Fuseki holds the live graph; Git holds the versioned snapshot you commit and share. All kinds of ontology curation methods in MAT-X will use this.

GitHub personal access token (fine-grained)

MAT-X uses a fine-grained token (not a classic token). You must be a member of mds-ontologies before it appears in the token wizard. An org admin can invite you under the organization's People tab on GitHub.

Open github.com/settings/personal-access-tokens/new
(or: your avatar -> Settings -> Developer settings -> Personal access tokens -> Fine-grained tokens -> Generate new token).

1) Token name and expiration

Choose any name (e.g. Mat-X ontology curation) and an expiration you are comfortable with. You can rotate the token later in Profile.

2) Resource owner - this selects mds-ontologies

Under Resource owner, open the dropdown. You will see your personal GitHub username and, if you are a member, organizations such as mds-ontologies.

• Select mds-ontologies, not your personal username. The token is then scoped to that organization's repositories.
• If mds-ontologies is missing, you are not a member yet - ask an org admin to add you, then refresh and restart the wizard.

3) Repository access

Choose All repositories (essential as otherwise the options below do not work). MAT-X creates a new public repo per working ontology (e.g. mds-ontologies/cement-model), so the token must cover repositories that do not exist yet.

Only select repositories works only if you manually add every ontology repo to the token.

4) Repository permissions

Set these permissions under Repository permissions:

• Contents: Read and write - clone, pull, commit, and push ontology.ttl.
• Metadata: Read-only - usually required automatically.
• Administration: Read and write - allows MAT-X to create new public repositories in mds-ontologies.
• ** Issues**: ** Read and write** allows MAT-X to create issues in case you are unhappy with developments

You do not Pull requests, Actions, or other permissions for ontology curation.

5) Generate token and authorize SSO (if prompted)

Click Generate token and copy it immediately (GitHub shows it once). If your organization uses SAML SSO, go to Settings -> Personal access tokens -> Fine-grained tokens, find the new token, click Configure SSO, and authorize mds-ontologies.

Without SSO authorization, API calls return 403.

Save the token in MAT-X Profile

On the Profile page (/profile), add an API credential:

• Vendor: GitHub (or any label containing github)
• API URL: https://api.github.com
• API key: paste the fine-grained token

Keys are encrypted at rest with NEXTAUTH_SECRET. The server uses the first profile credential whose vendor or URL matches GitHub.

Quick checklist

Resource owner:     mds-ontologies  (not your username)
Repository access:  All repositories
Contents:           Read and write
Metadata:           Read-only
Administration:     Read and write
Issues: Read and write 
SSO:                Authorized for mds-ontologies (if your org uses SAML)