Skip to main content

Create a Zenodo DOI

TL;DR​

If you just want to create or update, jump to the section you need:

First timeUpdate

CaseWhenWhat you do on Zenodo
First timeNo Zenodo record exists yetCreate a new upload, reserve a DOI, publish
UpdateA Zenodo record already existsOpen that record → New version → publish (new sub-ID; main ID stays)
info

The Zenodo DOI workflow fits into the broader Trust over IP process for publishing a Spec-Up-T specification as a ToIP Approved Deliverable.

This page explains how to assign a Zenodo DOI to a Spec-Up-T specification. It is written for people who need a permanent citation link and do not want to learn Zenodo in depth.

What you get​

A DOI is a permanent, citable link. Zenodo stores a ZIP copy of your specification repository and gives you:

  • Main ID (Zenodo calls this the Concept DOI) — one ID for the work as a whole. It never changes. It always resolves to the latest published version.
  • Sub-ID (Zenodo calls this a Version DOI) — one ID per published snapshot. Each new published version gets a new sub-ID.

Prefer embedding the main ID in the specification once you have it (after the first publish). That keeps one stable link in the document forever. Until then, embed the reserved sub-ID so the first release ZIP already contains a DOI.

Example main ID (Concept DOI): 10.5281/zenodo.18792085

Example sub-ID (Version DOI): 10.5281/zenodo.18797357

Example markdown link (use the main ID when available):

[https://doi.org/10.5281/zenodo.18792085](https://doi.org/10.5281/zenodo.18792085)

Where you must do this​

note

Zenodo itself does not care which GitHub branch or repository you use. Here we will do this on the main branch of the original repository, to keep it simple.

Do the following there:

  • Embed or update the DOI in the specification source when needed (and merge that change to main first)
  • Create the Git tag and GitHub Release
  • Upload the release ZIP to Zenodo and publish

Automatic versus Manual​

There are two ways to integrate Zenodo with a GitHub repository:

  • Automatic — connect Zenodo directly to the GitHub repository so releases are uploaded automatically
  • Manual — upload the release ZIP to Zenodo yourself

This guide uses the manual approach (you upload the GitHub Release ZIP yourself). That is required if you need the DOI before the ZIP is published — Zenodo’s automatic GitHub integration cannot reserve a DOI in advance.

note

For a first publish, reserve the DOI before you publish. Zenodo lets you reserve it so you can put it in the document first. It becomes official only when you click Publish. After that, prefer the main ID in the specification; later updates usually do not need a new reserved DOI in the source.

Grant yourself manage access​

If a Zenodo record already exists and is owned by an organization account, grant yourself manage access on that record before you try to publish updates. Repeat the steps below for every repository (and its Zenodo record) you need to work on.

  1. Create an account on zenodo.org if you do not have one.
    • An institutional email address is preferred. A personal or custom-domain address can also work.
  2. After you create the account, your username may not appear in Zenodo’s user search right away. Waiting overnight has been enough in practice for the account to become findable.
  3. Someone who already has manage rights — typically while logged in with the organization Zenodo account — must add you with Can manage rights on the relevant record (or community).
  4. When searching for users in Zenodo’s share/access UI, the search is not debounced. Type the name and let the search finish before assuming there is no match.

First time​

Goal:

  • create the Zenodo record
  • get the main ID + first sub-ID
  • put a DOI link in the specification.

1. Reserve a DOI on Zenodo​

  • Go to https://zenodo.org/uploads/new

    Zenodo new upload page

  • When asked whether you already have a DOI, choose "No, I need one"

    Zenodo shows: "Reserve a DOI by pressing the button (so it can be included in files prior to upload). The DOI is registered when your upload is published."

    Reserve DOI option

  • Click the button to reserve a DOI

    Generated DOI

  • Build the URL: https://doi.org/ + the reserved DOI (this is the first sub-ID; the screenshot above shows 10.5281/zenodo.18785919)
    Example: https://doi.org/10.5281/zenodo.18785919

Keep this Zenodo draft open. You will return to it in step 4.

2. Put the DOI in the specification on main​

note

Zenodo itself does not care which GitHub branch or repository you use. Here we will do this on the main branch of the original repository, to keep it simple.

  • Paste a markdown link with the reserved DOI near the top of the source (for example in spec-head.md)
  • Commit and push so the change lands on the original repository’s main branch

The reserved DOI is the first sub-ID. After you publish (step 4), Zenodo also shows the main ID. Prefer updating the specification to the main ID once it is available, so the link in the document stays stable forever.

3. Create a GitHub Release from main​

On the original repository:

  • Open Releases → Create a new release
  • Create a new tag from main (for example v1.0)
  • Enter a title, publish the release

GitHub builds a ZIP of the repository at that tag. Download that ZIP.

4. Upload the ZIP and publish​

  • Return to the Zenodo draft from step 1
  • Upload the GitHub Release ZIP
  • Fill in the required metadata (title, creators, description, …)
  • Click Publish

You now have:

  • a sub-ID for this first snapshot (the DOI you reserved)
  • a main ID for the work as a whole (shown on the Zenodo record; never changes)

If the specification still embeds the reserved sub-ID, update it to the main ID when convenient (follow Update below).

Details: Zenodo — reserve a DOI.

Update​

Goal: publish an updated ZIP without creating a second, unrelated Zenodo record. The main ID stays. Zenodo issues a new sub-ID for the new snapshot.

Do not start a fresh upload at /uploads/new for the same specification. Use New version on the existing record.

1. Update the specification on main (if needed)​

note

Zenodo itself does not care which GitHub branch or repository you use. Here we will do this on the main branch of the original repository, to keep it simple.

  • Make source changes on the original repository’s main branch
  • If you are switching the embedded link from the first sub-ID to the main ID, do that here and merge to main before releasing

2. Create a new GitHub Release from main​

(same as First time step 3)

On the original repository:

  • Open Releases → Create a new release
  • Create a new tag from main (for example v1.0)
  • Enter a title, publish the release

GitHub builds a ZIP of the repository at that tag. Download that ZIP.

3. Create a new Zenodo version (new sub-ID)​

  • Open the existing Zenodo record
  • Click New version
  • Upload the new GitHub Release ZIP (and adjust metadata if needed)
  • Click Publish

Result:

  • Main ID — unchanged
  • New sub-ID — for this snapshot only

If the specification already embeds the main ID, you usually do not need to change the DOI text again.

Details: Zenodo — manage versions.

warning

Do not overwrite a published Zenodo record’s files as the normal update path. Zenodo treats published files as fixed. For real updates, use New version.
Minor file fixes are only allowed briefly after publish (Zenodo’s own grace window); prefer New version unless Zenodo’s UI explicitly offers a minor file correction and you are still within that window.

Quick troubleshooting​

Wrong ZIP or missing DOI in the release​

note

Zenodo itself does not care which GitHub branch or repository you use. Here we will do this on the main branch of the original repository, to keep it simple.

The release ZIP is generated from the commit the tag points to. Fix the source on main, create a new tag at the corrected commit (same as Update step 2), confirm the release ZIP contents, then publish a Zenodo New version with that ZIP.

git checkout main
git pull
# ... commit fixes on main ...
git tag v1.0.1
git push origin v1.0.1

Then download the new release ZIP and upload it as a Zenodo New version (update), not as a brand-new unrelated record. If the bad tag was never published to Zenodo, you may instead delete and recreate that same tag; once a Zenodo version exists for it, prefer a new tag and New version.