Set up Zenodo - GitHub integration

Note: there is also a vignette in the checklist package for R, that covers below topics and more, such as integration with ORCID. If you are working with R and wish to control some of the below steps from R, then definitely read the vignette!

GitHub and Zenodo: background

GitHub hosts a remote Git server that you can use for distributed version control with Git. For more information about Git and GitHub, see other tutorials on this website! In short, Git helps you with version control (maintaining snapshots) of a directory (file folder) – a repository – and GitHub helps you with distributing versions and with collaboration.

On GitHub, one can designate specific snapshots (commits) as a release. Each release will typically have its version number. In this way, you can release a version 1.2.0, 1.3.0 etcetera of your source code – typically a software package, a report, a website, a note or whatever you wish to maintain and distribute.

Zenodo is a scientific repository funded by the European Commission and hosted at CERN. It allows researchers to deposit research papers, data sets, research software, reports, and any other research related digital artefacts (enumeration from Wikipedia). Zenodo is aimed at preserving the deposits for the long term, which is great for reproducibility purposes. Also, it keeps multiple versions of your stuff together under the same record. Moreover, it provides a stable DOI link for each version and for each record as whole!

Integrating GitHub and Zenodo

Just having a public code repository at GitHub is not enough for long-term reproducibility. This is where Zenodo comes in! From within Zenodo, you can setup a webhook in the GitHub repository which is triggered when you make a new release at GitHub. Then, GitHub will send the entire repository snapshot to Zenodo where it will be published as a zip-file.

Also, Zenodo will increment the version number or take that (and other metadata) from a .zenodo.json metadata file, if you provide such a file in the repository. Do know that you can still manually edit all metatadata of an existing publication at the Zenodo website (authors, title, description, version number, etc.). See further to discover this ‘Edit’ button! You cannot change the uploaded data themselves however, since a Zenodo publication is fixed (stable in time). Changing data is what versions are meant for.

Let’s suppose you already have a GitHub repository and you want to set up such integration.
Let’s do it!

Oh, wait!
Did you know that you cannot just undo a publication at Zenodo? So make sure to get familiar first!

If you are just taking your first steps and you want to do a safe exercise, then replace ‘https://zenodo.org’ by ‘https://sandbox.zenodo.org’! Consider the Zenodo Sandbox a playground for your exercise.

The Zenodo Sandbox creates the publications at https://sandbox.zenodo.org, e.g. https://sandbox.zenodo.org/record/1139470, but those are not perpetual and the displayed DOI’s will not work (since they aren’t actually created).

First of all, make an account at https://zenodo.org (or the Sandbox!) and log in.

Step 1: in Zenodo, go to ‘GitHub’ in your account settings

Go to the GitHub settings in Zenodo.

Step 2: find your repository, and flip the toggle to ‘on’

Your list of repositories.

Flip the toggle!

Now you are ready for your first release.

Releasing at GitHub triggers a Zenodo publication

Step 1: draft a new release

In GitHub, go to the releases page, and click ‘Draft new release’. Alternatively, extend the repository URL with /releases/new.

You get a page where you can:

• select or create a tag. This is required: releases always refer to a tag. A Git tag is a label that is fixed to a specific snapshot (commit). It will typically contain a version number that you decide yourself (e.g. v2 or v2023).
• choose a title for your release. You will typically want to include the version number.
• add a description. This is not required, but most commonly you will enumerate the most important changes compared to a previous release.

Step 2: make the release

Just push ‘publish release’!

Step 3: inspect the result at Zenodo

In seconds, the record (or the new version) will be created at Zenodo.

How do you know the URL?
In the GitHub settings at Zenodo, you can see a DOI badge for each enabled repository. Click on it to get the URL!¹

Navigate to the URL:

Tune your repository metadata for Zenodo

As referred above, you can include a .zenodo.json file in your repository to provide specific metadata for Zenodo.

You can find more explanation and an example at the developer’s site of Zenodo.

A simple example of the content of .zenodo.json is:

{
    "title": "test title",
    "description": "test description",
    "license": "GPL-3.0",
    "upload_type": "software",
    "access_right": "open",
    "version": "0.14.0",
    "creators": [
        {
            "name": "Vanderhaeghe, Floris",
            "affiliation": "Research Institute for Nature and Forest",
            "orcid": "0000-0002-6378-6229"
        }
    ],
    "keywords": [
        "T",
        "my strange keyword",
        "another"
    ]
}

But you can do more with .zenodo.json. As an example, see this one in the protocolhelper repository!

R users can also use functionality of the checklist package to generate .zenodo.json from a README.md file.

For an existing publication, you can always change metadata manually if needed. This can be done directly in Zenodo, as is demonstrated next with relation to communities (= part of the metadata).

Zenodo communities

A Zenodo community can be regarded as a collection of Zenodo records. A community has a name and a description, and one Zenodo record can belong to more than one community.

An example is the INBO community at Zenodo: all Zenodo content uploaded by INBO.

In the above referred example of .zenodo.json, you can also find how to add your record to a community via .zenodo.json, e.g. the INBO community in case of INBO staff.

Alternatively, after a first version of your record has been created at Zenodo, you can do it manually in Zenodo:

Step 1: push the ‘Edit’ button

You need to be logged in of course, and you must have administrator rights for the record at hand.

Step 2: search for the community and select it

For example, add the INBO community if you are INBO staff:

Step 3: click ‘Publish’ at the top or bottom of the page

That’s all!
Have fun with GitHub and Zenodo!