Add a Project or Subproject

Use this procedure to add work to the GeoEpi Hub. The Hub describes project context and locates canonical subprojects; the subproject repository describes the science.

Add a new project

Choose a stable lowercase project_id that matches ^[a-z0-9]+(?:-[a-z0-9]+)*$.
In geoepi/geoepi-hub, create projects/<project_id>/.
Create or adapt the project README.md using the project overview template.
Add projects/<project_id>/subprojects.yml, even if the initial subproject list is empty.
Add a Data Management Plan, controlled-data inventory, decisions record, or products record as appropriate. Not every optional project file is required on day one.
Do not place controlled data, credentials, confidential material, or sensitive agreements directly in the Hub.
Submit the changes through the normal focused-branch and pull-request workflow.

Do not guess at project objectives, collaborators, stewardship arrangements, access conditions, milestones, or products. Record them when someone with project knowledge can provide them.

Add a new subproject

Identify the parent project_id.
Choose a stable lowercase subproject_id that matches the ID pattern above.
Identify the canonical GitHub repository. Its name may retain GitHub capitalization.
Add .geoepi.yml to the canonical repository.
Confirm that project_id, subproject_id, and repository.canonical are correct in .geoepi.yml.
Add the same ID and canonical repository to the parent project’s projects/<project_id>/subprojects.yml in the Hub.
If the repository is private or otherwise requires App access, ensure that the geoepi-hub-reader GitHub App installation is allowed to read it.
Open and merge the relevant repository and Hub pull requests after validation passes.
If immediate synchronization is useful, manually run the Hub’s Update GeoEpi Hub Action.
Verify that the subproject appears in the detailed status, portfolio summary, and, when applicable, attention-needed report.

The Hub uses a read-only GitHub App to retrieve .geoepi.yml from registered repositories. When a repository is registered, the App installation must be allowed to read it if it is not already included. The App has read-only Contents access and does not modify subproject repositories.

Examples of the working arrangement include geoepi/hominivorax-geostat, geoepi/cds-datagrab, and geoepi/EpiPlume. They illustrate registration and .geoepi.yml integration, not a required scientific repository layout.

Common validation failures

Failure	Check
Subproject ID contains uppercase letters	Keep `project_id` and `subproject_id` lowercase; repository capitalization is allowed.
Registry ID does not match `.geoepi.yml`	Use the same stable IDs in both files.
Canonical repository does not match	Match the `owner/repository` value exactly in the registry and `.geoepi.yml`.
`.geoepi.yml` is missing	Add it at the root of the canonical repository.
Reader GitHub App cannot access the repository	Include the repository in the App installation’s allowed repositories.

Hub synchronization is strict: an unreadable repository or incompatible record stops generation rather than publishing a partial portfolio.