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)