Making your research software citable means others can credit your work precisely — and that your contribution is traceable through the systems used for research assessment, impact reporting, and exercises such as REF. This guide walks you through the key steps.
For a more in-depth and comprehensive guide to research software development good practices, check out our SWD3 Training Materials.
Before you start
Your code should be in a GitHub repository before following the steps below. If you haven’t done this yet, see our guidance on code management.
Step 1: Define your authorship criteria and create an AUTHORS.md file
A question worth putting to your team early — ideally at the start of the project — is: who counts as an author of this software? Authorship criteria vary between projects and disciplines, and revisiting this retrospectively can be complicated. Agreeing and documenting your criteria from the outset makes everything that follows much more straightforward.
Once agreed, record your criteria and your author list explicitly in an AUTHORS.md file in the root of your repository. This file will directly inform your citation file (Step 2) and your Zenodo record.
What to consider when defining authorship
Software authorship is not the same as having commit access or being listed as a repository contributor on GitHub. In some projects, authorship may include people who made significant intellectual contributions without writing code — such as a PI who shaped key design decisions. The important thing is that your criteria are explicit and agreed by the team.
Ensuring that Research Software Engineers (RSEs) and Digital Research Technical Professionals (dRTPs) who built the software are credited as authors is consistent with the University’s Research Culture strategic objectives around valuing diverse contributions — and is simply good practice. Their contributions should be visible in the scholarly record, not just in commit histories.
For projects with many contributors, deciding who qualifies as an author for a given release can be genuinely difficult — this is a recognised, ongoing challenge in the research software community. The Fatiando a Terra project provides a useful example of explicit, documented authorship criteria, including an opt-in process where contributors add their own details to an AUTHORS.md file. See also this Pangeo community discussion on software authorship for a frank exploration of the issues that arise in practice.
For discipline-specific advice on authorship, or if you are considering submitting your software to a journal such as JOSS (Journal of Open Source Software), request help from our team via a Research IT Query (login required) or email the Research Services team via [email protected]. You can also access peer support and guidance through the Open Research UK Network — Leeds branch (login required).
Step 2: Add a citation file (CITATION.cff)
A CITATION.cff file tells others how to cite your software. GitHub renders it automatically, adding a “Cite this repository” button to your repo. When you connect to Zenodo (Step 4), this file populates the author list on your Zenodo record — which in turn creates entries on contributors’ ORCID profiles.
Your AUTHORS.md file should directly inform who you list here. Create a file called CITATION.cff in the root of your repository. Here’s a minimal example:
yaml
cff-version: 1.2.0
message: "If you use this software, please cite it as below."
title: "My Research Software"
authors:
- family-names: Smith
given-names: Jane
orcid: "https://orcid.org/0000-0000-0000-0000"
- family-names: Patel
given-names: Arjun
orcid: "https://orcid.org/0000-0000-0000-0001"
version: 1.0.0
date-released: 2025-01-01 Full documentation of available fields is available from the Citation File Format documentation.
Step 3: Add a licence file
Your repository should contain a LICENSE file — Zenodo will use this information when creating your record. Check out this web page for help choosing an open source software license, or contact your faculty representative from Research and Innovation if you think your software has commercial potential. If in doubt, feel free to get in touch with our team via a Research IT Query.
Step 4: Connect your repository to Zenodo
Zenodo is an open research repository that will automatically generate a Digital Object Identifier (DOI) for your software each time you create a release on GitHub.
- Log in to Zenodo using your GitHub account
- Go to your Zenodo account settings and navigate to the GitHub section
- Find your repository in the list and toggle it on
- Zenodo will set up a webhook in your GitHub repository to listen for new releases
About the Zenodo webhook secret GitHub and Zenodo communicate via a webhook secured with a secret token. This is set automatically when you connect your repository, but may need to be refreshed periodically as part of routine maintenance. If the integration stops working, check whether the webhook secret needs updating in your repository’s settings (Settings → Webhooks). You only need to set a new secret on the GitHub side — there is nothing to update in Zenodo when doing this.
Step 5: Create a release on GitHub
Zenodo generates a DOI each time you publish a new release of your software on GitHub. To create your first citable version:
- Go to your repository on GitHub
- Click Releases → Draft a new release
- Create a version tag (e.g. v1.0.0), add release notes, and publish
- Zenodo will automatically archive the release and assign it a DOI
Your DOI will appear in your Zenodo record shortly after the release is published. Each subsequent release receives its own DOI, with a separate DOI representing all versions of the software collectively.
Step 6: Use your DOI
Once you have a DOI, you can:
- Reference it in your publications — cite the specific version of the software used in your research
- Deposit it on Symplectic as a diverse output — use the Zenodo DOI when depositing your research code. See the Library’s guidance for depositing research outputs in Symplectic.
Your CITATION.cff can also be updated to include the DOI once you have it.
Need help?
If you’re unsure about any of these steps, raise a Research IT query (login required) and we’ll be happy to guide you through the technical side.
For broader guidance on open research principles and practice, visit the Library Open Research pages.
