Complete step-by-step guide for obtaining a permanent Zenodo DOI for your REMARK
For Published REMARKs (Tier 3), a permanent Zenodo DOI is required. Obtain your Zenodo DOI only after your REMARK is otherwise complete—it should be the very last thing you do before submitting your REMARK for incorporation into the Econ-ARK ecosystem. That way the archived version matches exactly what you submit. This guide walks you through the process.
Table of Contents¶
Prerequisites¶
Before starting, ensure you have:
✅ A REMARK repository that fully meets Standard (Tier 2) REMARK requirements and is ready to submit—Zenodo DOI is the last step before submission
✅ GitHub repository is public (Zenodo cannot archive private repos)
✅ No uncommitted changes in your repository
✅
CITATION.cfffile with complete metadata✅ GitHub account with admin access to the repository
✅ Zenodo account (free - create at https://zenodo.org using GitHub login)
Quick Checklist¶
Use this checklist to track your progress:
Phase 1: Pre-Flight (5 minutes)¶
1.1 Verify repository is clean (no uncommitted changes)
1.2 Verify CITATION.cff exists and is complete
1.3 Test
reproduce.shruns successfully1.4 Ensure all required files are present
Phase 2: Git Tagging (2 minutes)¶
2.1 Create annotated git tag (e.g.,
v1.0.0)2.2 Push tag to GitHub
Phase 3: Zenodo Setup (5-10 minutes)¶
3.1 Log in to Zenodo with GitHub account
3.2 Navigate to GitHub settings on Zenodo
3.3 Enable Zenodo-GitHub integration
3.4 Find and toggle your repository on Zenodo
3.5 Sync repositories if needed
Phase 4: GitHub Release (2 minutes)¶
4.1 Go to GitHub repository releases page
4.2 Click “Draft a new release”
4.3 Select your tag from dropdown
4.4 Add release title and description
4.5 Publish release
Phase 5: Zenodo Archival (5-10 minutes)¶
5.1 Wait for Zenodo to archive (automatic)
5.2 Find your upload on Zenodo
5.3 Obtain DOI from Zenodo page
5.4 Copy DOI badge markdown
Phase 6: Update CITATION.cff (2 minutes)¶
6.1 Add DOI to CITATION.cff
6.2 Commit and push update
6.3 Verify DOI badge appears on GitHub
Phase 7: Verification (5 minutes)¶
7.1 Download archive from Zenodo
7.2 Verify files are complete
7.3 Test basic functionality
7.4 Verify commit hash matches
Total Time: 30-45 minutes
Detailed Step-by-Step Instructions¶
Step 1: Pre-Flight Checks (5 minutes)¶
1.1 Verify Repository is Clean¶
cd /path/to/your-remark
git statusExpected output: nothing to commit, working tree clean
If you see uncommitted changes, commit them first:
git add .
git commit -m "Prepare for v1.0.0 release"
git push origin main # or master1.2 Verify CITATION.cff¶
Check that your CITATION.cff has all required fields:
cat CITATION.cffRequired fields:
cff-version(e.g., “1.2.0”)titleauthors(with names)repository-code(GitHub URL)license(e.g., “Apache-2.0”)
Helpful but not required:
keywordsabstractORCIDs for authors
1.3 Test Reproduction Script¶
./reproduce.sh --helpShould display help information without errors.
1.4 Verify Required Files¶
ls -la reproduce.sh CITATION.cff binder/environment.yml LICENSEAll should exist and be readable.
Step 2: Create Git Tag (2 minutes)¶
2.1 Create Annotated Tag¶
Choose a version number following semantic versioning:
v1.0.0 for first release
v1.1.0 for minor updates
v1.0.1 for bug fixes
git tag -a v1.0.0 -m "First published release"Verify tag was created:
git tag -l
git show v1.0.02.2 Push Tag to GitHub¶
git push origin v1.0.0Verify on GitHub:
Go to:
https://github.com/YOUR_USERNAME/YOUR_REMARK/tagsYour tag should appear in the list
Step 3: Enable Zenodo-GitHub Integration (5-10 minutes)¶
3.1 Log in to Zenodo¶
Go to https://zenodo.org
Click “Log in” (top right)
Select “Log in with GitHub”
Authorize Zenodo if prompted
3.2 Navigate to GitHub Settings¶
Click your username (top right)
Select “GitHub” from dropdown menu
This opens: https://
zenodo .org /account /settings /github/
3.3 Grant Repository Access¶
If this is your first time using Zenodo:
You’ll see a message: “Authorize application access on GitHub”
Click the link to GitHub settings
On GitHub, find “Zenodo” in Applications
Click “Configure”
Under “Repository access”:
Select “Only select repositories”
Choose your REMARK repository
Click “Save”
Return to Zenodo and refresh the GitHub settings page.
3.4 Enable Your Repository¶
On the Zenodo GitHub settings page:
Find your repository in the list
Toggle the switch to ON (green)
If you don’t see your repository, click “Sync now”
Common issues:
Repository not appearing? Click “Sync now” and wait 30 seconds
Toggle doesn’t work? Check GitHub authorization settings
Still not working? See Troubleshooting
Step 4: Create GitHub Release (2 minutes)¶
4.1 Navigate to Releases¶
Go to: https://github.com/YOUR_USERNAME/YOUR_REMARK/releases
4.2 Draft New Release¶
Click “Draft a new release” button
4.3 Fill in Release Details¶
Choose a tag: Select v1.0.0 from dropdown
Release title: Use a clear, descriptive title
Good: “Initial Published Release”
Good: “Version 1.0.0 - QE Submission”
Avoid: Just “v1.0.0”
Description: Include key information (example):
## Version 1.0.0 - Initial Published Release
This release accompanies the submission to [Journal Name].
### What's Included
- Complete replication package
- All data and code
- Comprehensive documentation
- Automated reproduction workflow
### System Requirements
- See `binder/environment.yml` for dependencies
- Reproduction time: ~X minutes on standard laptop
### Citation
See CITATION.cff for bibliographic information.
### License
Apache License 2.04.4 Publish Release¶
Leave “This is a pre-release” unchecked
Click “Publish release”
Verification:
Release appears at:
https://github.com/YOUR_USERNAME/YOUR_REMARK/releases/tag/v1.0.0You’ll receive a GitHub notification
Step 5: Obtain Zenodo DOI (5-10 minutes)¶
5.1 Wait for Zenodo Archival¶
Zenodo automatically archives your release when you publish it.
Timeline:
Archival starts: Immediately after release
Processing time: 2-10 minutes
Factors: Repository size, Zenodo server load
Monitoring:
Go to Zenodo uploads: https://
zenodo .org /deposit Look for your repository name
Status will show “Processing...” then “Published”
Alternative: Check your email for Zenodo notification
5.2 Find Your Upload¶
Go to: https://
zenodo .org /deposit Click on your REMARK name
This opens the Zenodo landing page
Or navigate directly (after it’s published):
Search for your repository name on https://zenodo.org
5.3 Obtain the DOI¶
On the Zenodo landing page:
DOI badge: At top right of page
DOI format:
10.5281/zenodo.XXXXXXX(7-digit number)
Copy the DOI number (just the number, e.g., 10.5281/zenodo.1234567)
5.4 Get DOI Badge Markdown¶
On the same Zenodo page:
Look for “DOI” badge (top right)
Click the badge
Select “Markdown” format
Copy the code, which looks like:
[](https://doi.org/10.5281/zenodo.1234567)Step 6: Update CITATION.cff (2 minutes)¶
6.1 Add DOI to CITATION.cff¶
Edit your CITATION.cff file and add the DOI:
cff-version: 1.2.0
title: "Your REMARK Title"
authors:
- family-names: "Smith"
given-names: "John"
repository-code: 'https://github.com/YOUR_USERNAME/YOUR_REMARK'
doi: 10.5281/zenodo.1234567 # ADD THIS LINE
license: Apache-2.0
keywords:
- REMARK
- ReproducibilityImportant:
Place DOI after
repository-codeUse the plain DOI, not the full URL
Format:
doi: 10.5281/zenodo.XXXXXXX
6.2 Commit and Push¶
git add CITATION.cff
git commit -m "Add Zenodo DOI to CITATION.cff
DOI: 10.5281/zenodo.XXXXXXX
Archive: https://doi.org/10.5281/zenodo.XXXXXXX
Published REMARK complete."
git push origin main # or master6.3 Optional: Add DOI Badge to README¶
Edit your README.md and add the badge at the top:
# Your REMARK Title
[](https://doi.org/10.5281/zenodo.1234567)
[Rest of README...]Step 7: Verification (5 minutes)¶
7.1 Download Archive from Zenodo¶
Test that anyone can download your archive:
# Get download URL from Zenodo page, then:
cd /tmp
curl -L -O "https://zenodo.org/records/XXXXXXX/files/YOUR_USERNAME-YOUR_REMARK-YYYYYYY.zip"7.2 Verify Archive Contents¶
unzip YOUR_USERNAME-YOUR_REMARK-YYYYYYY.zip
cd YOUR_USERNAME-YOUR_REMARK-YYYYYYY
ls -laCheck for:
reproduce.shexists and is executablebinder/environment.ymlexistsCITATION.cffexistsAll code and data files present
7.3 Test Basic Functionality¶
./reproduce.sh --helpShould display help without errors.
7.4 Verify Commit Hash Matches¶
# In the Zenodo download directory:
git rev-parse HEAD
# In your original repository:
cd /path/to/your-remark
git rev-parse v1.0.0Both should show the same commit hash - this is cryptographic proof they’re identical.
Troubleshooting¶
Problem: Repository Not Appearing on Zenodo¶
Symptoms: Your repository doesn’t appear in Zenodo’s GitHub settings page
Solutions:
Click “Sync now” on Zenodo GitHub settings page
Wait 30-60 seconds
Refresh page
Check GitHub authorization:
Find “Zenodo”
Click “Configure”
Verify your repository is selected under “Repository access”
Save changes
Check repository is public:
Zenodo cannot access private repositories
Go to repository settings on GitHub
Under “Danger Zone”, ensure it’s public
Check organization permissions (if applicable):
Organization settings → Third-party access
Ensure Zenodo is authorized
Grant access to repositories
Problem: Release Created but No Zenodo Archive¶
Symptoms: GitHub release exists, but no Zenodo archive created
Solutions:
Verify Zenodo toggle is ON:
Find your repository
Ensure toggle is green (ON)
Check release is not a “pre-release”:
Pre-releases don’t trigger Zenodo archival
Edit release on GitHub
Uncheck “This is a pre-release”
Wait longer:
Large repositories take longer to archive
Check back in 15-30 minutes
Create a new release:
Sometimes the webhook fails
Create a new tag:
v1.0.1Create a new release
Should trigger archival
Problem: DOI Badge Not Showing on GitHub¶
Symptoms: Added DOI to CITATION.cff but badge doesn’t appear
Solutions:
Verify CITATION.cff syntax:
# Validate YAML syntax python -c "import yaml; yaml.safe_load(open('CITATION.cff'))"Check DOI format:
Correct:
doi: 10.5281/zenodo.1234567Incorrect:
doi: https://doi.org/10.5281/zenodo.1234567
Wait for GitHub cache:
GitHub caches CITATION.cff
Wait 5-10 minutes
Hard refresh browser (Ctrl+F5 or Cmd+Shift+R)
Problem: Archive Missing Files¶
Symptoms: Downloaded Zenodo archive is incomplete
Solutions:
Check .gitignore:
Files in
.gitignorewon’t be archivedReview and update
.gitignoreCreate new tag and release
Verify files were committed:
git ls-tree -r v1.0.0 --name-onlyThis shows all files in the tag
Large files:
GitHub releases have file size limits
Consider data download instructions instead
Use Git LFS for large files
Verification Checklist¶
After completing all steps, verify:
On GitHub¶
Tag
v1.0.0exists in tags listRelease published with tag
v1.0.0CITATION.cff contains DOI
DOI badge appears in repository sidebar
On Zenodo¶
Repository archived and published
DOI assigned and visible
Landing page shows correct information
Archive can be downloaded
Cryptographic Verification¶
Commit hash from Zenodo matches tag
Downloaded archive extracts successfully
reproduce.shexists and is executable
Documentation¶
README mentions Zenodo archive
CITATION.cff has DOI
Release notes are clear and complete
FAQ¶
Q: Do I need to create a new DOI for every version?¶
A: No. Zenodo automatically creates version-specific DOIs, but all versions share a “concept DOI” that always points to the latest version. You can use either:
Version-specific DOI:
10.5281/zenodo.1234567(points to v1.0.0)Concept DOI:
10.5281/zenodo.1234566(always points to latest)
For Published REMARKs, use the version-specific DOI in CITATION.cff.
Q: What version number should I use?¶
A: Follow semantic versioning:
v1.0.0- First published releasev1.1.0- New features/functionality addedv1.0.1- Bug fixes, no new featuresv2.0.0- Breaking changes
Q: Can I delete a Zenodo upload?¶
A: No. Zenodo is a permanent archive. However, you can:
Upload a new version (becomes the latest)
Hide old versions (but they remain accessible via DOI)
Plan carefully before creating releases.
Q: How long does Zenodo preserve data?¶
A: Minimum 20 years, but likely indefinitely. Zenodo is operated by CERN and has long-term preservation commitments.
Q: What if my repository changes after archival?¶
A: The Zenodo archive is frozen at the tagged commit. Your repository can continue to evolve. Create new releases/tags for updated versions.
Q: Do I need Zenodo for Standard REMARKs?¶
A: No. Zenodo DOI is only required for Published REMARKs. Standard REMARKs can be submitted without a DOI.
Q: When should I obtain my Zenodo DOI?¶
A: Only after your REMARK fully meets all other Tier 3 requirements (reproduce.sh works, documentation complete, tagged release, etc.). Obtaining the Zenodo DOI should be the very last thing you do before submitting your REMARK for incorporation into the Econ-ARK ecosystem—so the archived version matches exactly what you submit.
Q: Can I use a different archive service?¶
A: Zenodo is preferred for REMARKs because:
Free and open
GitHub integration
Academic-friendly
CERN-backed (reliable)
Widely recognized
Other services (Figshare, OSF) can work but require manual steps.
Q: What’s the difference between the econ-ark fork and Zenodo?¶
A:
econ-ark fork: Created by Econ-ARK on acceptance to preserve the state at which the REMARK was tested and verified. The catalog and website point to this fork until the author submits a new version; Econ-ARK will then update the fork as long as
reproduce.shruns and the draft still meets REMARK requirements.Zenodo archive: Frozen snapshot at a specific version (immutable).
Both should have identical content at the tagged commit at the time of acceptance.
Q: How do I cite a Zenodo-archived REMARK?¶
A: The CITATION.cff provides the format. Generally:
AuthorLastName, F. (YEAR). Title of REMARK.
https://doi.org/10.5281/zenodo.XXXXXXXExample: Complete Workflow¶
Here’s a complete example walkthrough:
# Step 1: Verify repository is ready
cd ~/my-remark
git status # Should be clean
# Step 2: Create tag
git tag -a v1.0.0 -m "First published release"
git push origin v1.0.0
# Step 3: Go to Zenodo (via browser)
# - Log in at https://zenodo.org
# - Enable GitHub integration
# - Toggle on your repository
# Step 4: Create GitHub release (via browser)
# - Go to github.com/yourname/your-remark/releases
# - Click "Draft a new release"
# - Select tag v1.0.0
# - Add title: "Version 1.0.0 - Initial Release"
# - Publish
# Step 5: Wait for Zenodo archival (2-10 minutes)
# Check: https://zenodo.org/deposit
# Step 6: Update CITATION.cff with DOI
echo "doi: 10.5281/zenodo.1234567" >> CITATION.cff
git add CITATION.cff
git commit -m "Add Zenodo DOI"
git push
# Step 7: Verify
curl -L -O "https://zenodo.org/records/1234567/files/archive.zip"
unzip archive.zip
cd yourname-your-remark-abc1234
./reproduce.sh --help # Should workTotal time: 30-45 minutes from start to finish.
Additional Resources¶
Official Documentation¶
Zenodo Help: https://
help .zenodo .org/ GitHub + Zenodo Guide: https://
guides .github .com /activities /citable -code/ CITATION.cff Spec: https://
citation -file -format .github .io/
Tools¶
CFF Initializer: https://
citation -file -format .github .io /cff -initializer -javascript/ CFF Validator: https://
github .com /citation -file -format /cffconvert
REMARK Resources¶
STANDARD.md: Full REMARK requirements
How-To-Make-A-REMARK.md: General REMARK creation guide
REMARK Starter Example: https://
github .com /econ -ark /REMARK -starter -example
Summary¶
Quick Reference Command Sequence¶
# 1. Create tag
git tag -a v1.0.0 -m "Published release"
git push origin v1.0.0
# 2. Enable on Zenodo (browser): https://zenodo.org/account/settings/github/
# 3. Create GitHub release (browser): github.com/you/repo/releases
# 4. Wait for Zenodo archival
# 5. Add DOI to CITATION.cff
# Edit CITATION.cff, add line: doi: 10.5281/zenodo.XXXXXXX
# 6. Commit and push
git add CITATION.cff
git commit -m "Add Zenodo DOI"
git push
# Done!Timeline¶
| Phase | Duration | Activity |
|---|---|---|
| Pre-flight | 5 min | Verify repository ready |
| Tagging | 2 min | Create and push git tag |
| Zenodo setup | 5-10 min | Enable integration (first time only) |
| Release | 2 min | Create GitHub release |
| Archival | 5-10 min | Wait for Zenodo processing |
| Update | 2 min | Add DOI to CITATION.cff |
| Verification | 5 min | Download and test archive |
| Total | 30-45 min | Complete workflow |
Getting Help¶
If you encounter issues not covered in this guide:
Check Zenodo documentation: https://
help .zenodo .org/ Search existing issues: https://
github .com /econ -ark /REMARK /issues Open a new issue: https://
github .com /econ -ark /REMARK /issues /new Contact REMARK maintainers: Via GitHub issues
Document Version: 1.0
Last Updated: December 2025
Maintained by: econ-ark REMARK team