# How to Use Release Tagging for Reproducible Research By the end of this guide, you will be able to attach a permanent, citable label to a frozen snapshot of a research project so that you, a reviewer, or a stranger five years from now can regenerate your figures from that exact snapshot. The workflow covers code, computing environment, data references, and output verification. To follow along, have these installed and ready: - Git (version 2.30 or newer is comfortable for every command shown here) - A hosted repository such as GitHub, GitLab, or a university-hosted Git server - An environment manager such as Conda or pip, or a container runtime such as Docker or Apptainer - A checksum tool. Linux and macOS ship with `sha256sum` or `shasum`, and Windows users can use PowerShell's `Get-FileHash` - An account with an archival repository such as Zenodo, which mints DOIs for released code Reproducible research means that a documented result can be reobtained later from the recorded materials, parameters, and procedures. Release tagging is the practice that makes this possible in practice. You tag, in one atomic action, the precise state of everything that produced a result. ## What Release Tagging Means in Reproducible Research A release tag is a named, immutable pointer to a specific commit, paired with an environment specification, a data manifest, and a record of the outputs. The tag is the handle. Everything frozen behind the tag is the payload. The principle is borrowed directly from quantitative laboratory science, where a tag is only useful if its chemistry and handling are fully specified. In proteomics, solid-phase isotope tagging of peptides through a site-specific capture and release process was shown to be simpler, more efficient, and more sensitive than an earlier affinity-tag method precisely because the labeling reaction was standardized and automated [1]. Likewise, absolute protein quantification with amine-reactive isobaric tagging reagents such as iTRAQ succeeds only when the standard peptides are selected carefully and enzymatic digestion is optimized to ensure complete release of the peptides from the protein [2]. In both cases, reproducibility came from pinning every variable, not from talent. A release tag applies the same discipline to a computational project. The tag fixes the code. The environment file fixes the software. The data manifest fixes the inputs. The checksum file fixes the outputs. Nothing is left to memory. ## Release Tagging for Reproducible Research, Step by Step The walkthrough below assumes a small analysis project with a script or notebook, some input data, and a results directory. Adapt the file names to your project. ### Step 1. Commit every file the analysis depends on Open a terminal in the project root and check the state of the repository. ```bash cd ~/projects/gexp-analysis git status ``` Expected output for a project with unstaged edits: ``` On branch main Changes not staged for commit: modified: scripts/plot_figures.py Untracked files: config/params.yaml nothing added to commit but untracked files present ``` Stage and commit everything the analysis needs. Add large raw data files to `.gitignore` rather than the repository, and record them in a manifest instead (Step 6 covers that). ```bash git add scripts/ config/ environment.yml README.md .gitignore git commit -m "Final analysis code for manuscript revision" ``` Expected output: ``` [main 3f9c1ab] Final analysis code for manuscript revision 5 files changed, 42 insertions(+), 7 deletions(-) ``` Confirm the tree is clean before moving on. A tag on a dirty working directory captures code that exists only on your laptop. ```bash git status ``` Expected output: ``` On branch main nothing to commit, working tree clean ``` ### Step 2. Pin the computing environment Two levels of pinning are standard. The first is an environment file, which lists exact package versions. ```bash conda env export -n gexp-analysis > environment.yml ``` The file will contain lines like these: ```yaml name: gexp-analysis channels: - conda-forge dependencies: - python=3.11.5 - pandas=2.1.1 - matplotlib=3.8.0 - pip=23.2.1 ``` For pip-based projects, the equivalent is: ```bash pip freeze > requirements.txt ``` The second and stronger level is a container image, which freezes the operating system libraries along with the packages. Build and push an image tagged with your release version. ```bash docker build -t yourlab/gexp-analysis:v1.0.0 . docker push yourlab/gexp-analysis:v1.0.0 ``` After pushing, capture the image digest, which is an immutable fingerprint of the image contents: ```bash docker inspect --format='{{index .RepoDigests 0}}' yourlab/gexp-analysis:v1.0.0 ``` Expected output: ``` yourlab/gexp-analysis@sha256:9c1f7a2b4d8e0f31a5c6b7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8 ``` The digest matters because a tag name such as `v1.0.0` on a registry can be overwritten, while a digest cannot. Record the digest string in your tag annotation. ### Step 3. Run the final analysis from a clean state and hash the outputs Delete generated results, rerun the full pipeline from scratch, and record checksums of every output file. This proves the release can regenerate its own results rather than relying on stale files. ```bash rm -rf results/ python scripts/run_all.py sha256sum results/* > results.sha256 cat results.sha256 ``` Expected output: ``` a3f5c9e2b1d84f6a0c7e5b2d9f1a8c34e6b7d9021f4a5c8e7b3d9f0a1c2e4f56 results/figure1.pdf 77e0d1b2a3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f7a8b9c0d1e2f3a4 results/table1.csv 02b1c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90 results/figure2.pdf ``` ### Step 4. Create an annotated tag An annotated tag stores a tagger name, a date, and a message, which is why it is the correct choice for research releases. A lightweight tag is just a name on a commit and carries no provenance. Use semantic versioning, which is the widespread convention of `MAJOR.MINOR.PATCH`: the major number increases when results or interfaces change incompatibly, the minor number when you add capability without changing existing results, and the patch number for corrections that do not alter conclusions. ```bash git tag -a v1.0.0 -m "Release v1.0.0: final figures and tables for manuscript submission. Environment: environment.yml (conda), container yourlab/gexp-analysis@sha256:9c1f7a2b... Data: manifest in data/manifest.csv (see archive DOI) Outputs: results.sha256 Run: conda env create -f environment.yml && python scripts/run_all.py" ``` Inspect the tag to confirm the annotation was recorded: ```bash git show v1.0.0 ``` Expected output: ``` tag v1.0.0 Tagger: Jane Doe Date: Tue Nov 11 09:14:32 2026 -0500 Release v1.0.0: final figures and tables for manuscript submission. ... commit 3f9c1ab (HEAD -> main, tag: v1.0.0) Author: Jane Doe Date: Tue Nov 11 08:52:10 2026 -0500 Final analysis code for manuscript revision ``` Parameters that matter in this step: - **Tag name.** Keep one convention per project, for example `v` followed by the three-number version. Do not mix `v1.0.0`, `final`, and `final2`. - **Message content.** Name the manuscript or milestone, the environment file, the container digest, and the checksum file. A tag message is the cheapest place to store the release context. - **Tag target.** The tag should point at the last commit in a clean tree, which you confirmed in Step 1. ### Step 5. Push the tag to the remote Tags are local until pushed. Push the specific tag: ```bash git push origin v1.0.0 ``` Expected output: ``` Enumerating objects: 1, done. Counting objects: 100% (1/1), done. Writing objects: 100% (1/1), 480 bytes | 480.00 KiB/s, done. Total 1 (delta 0), reused 0 (delta 0) To github.com:yourlab/gexp-analysis.git * [new tag] v1.0.0 -> v1.0.0 ``` ### Step 6. Archive the release and record the data On GitHub, open the repository, go to Releases, and choose Draft a new release. Select the tag `v1.0.0`, add release notes, and publish. If your repository is connected to Zenodo, publishing the release creates an archival snapshot with a versioned DOI. That DOI is what the manuscript cites. For data that cannot live in the repository, create a manifest that lists each file, its size, and its checksum, then deposit the data in an institutional repository or a public data archive and record the accession in the tag message and the README. A manifest for a wet-lab project should also record reagent identities and conditions, the way published proteomics methods do. The cleavable bioorthogonal tagging (CBOT) study, for example, specifies the isotope-labeled azidohomoalanine pair (AHA and hAHA) used for quantification, the 6 h rapamycin stimulation window, and the 2 mg of starting material that yielded 4335 newly synthesized proteins in a single LC-MS/MS run at 97.1% enrichment specificity [3]. Every one of those values is the wet-lab equivalent of a line in `environment.yml`. The follow-up TOP-CBOT strategy goes further and documents the probe design itself, a solid-phase-conjugated probe carrying a clickable moiety and a protease-cleavable site released by trypsin and TEV protease, along with the combined dataset sizes of 3699 proteins in the tryptic set and 1931 confirmed newly synthesized proteins in the TEV set with over 90% overlap between them [4]. A reader can reproduce the method because nothing was left implicit. ### Step 7. Verify the release by cold reproduction This is the step most people skip and the one that catches nearly every mistake. In a temporary directory, clone the repository, check out the tag, rebuild the environment, run the analysis, and compare checksums. ```bash cd /tmp git clone https://github.com/yourlab/gexp-analysis.git verify-release cd verify-release git checkout v1.0.0 ``` Expected output: ``` Note: switching to 'v1.0.0'. HEAD is now at 3f9c1ab Final analysis code for manuscript revision ``` Rebuild and run: ```bash conda env create -f environment.yml conda activate gexp-analysis python scripts/run_all.py sha256sum -c results.sha256 ``` Expected output: ``` results/figure1.pdf: OK results/table1.csv: OK results/figure2.pdf: OK ``` Every line must end in `OK`. Any line ending in `FAILED` means the release is not reproducible yet, and you should not cite it until you understand why. ### Step 8. Cite the release Reference the DOI in the manuscript, thesis, or report, and keep the tag name in the text so readers can navigate the repository directly. A sentence in the methods section such as "Analysis code release v1.0.0 (DOI archived via Zenodo)" is all it takes. ### Exact errors you will hit and how to fix them ![Decision path through three common tag errors, each with a fix, ending in a cold reproduction check.](/article-images/illustrations/release-tagging-reproducible-research-tag-error-triage.webp) | Error message | Cause | Fix | |--|--|--| | `fatal: not a git repository (or any of the parent directories): .git` | The command was run outside a repository | `cd` into the project root, or run `git init` if the project is not yet versioned | | `fatal: tag 'v1.0.0' already exists` | The tag name was reused | Publish under a new version number. Never delete and recreate a tag that has been pushed | | `! [rejected] v1.0.0 -> v1.0.0 (already exists)` followed by `error: failed to push some refs to ...` | You tried to move a tag that already exists on the remote | Do not move it. Keep the published tag and cut a new version. The remote refusal is a feature that protects provenance | | `error: pathspec 'v1.0.0' did not match any file(s) known to git` | The tag exists on the remote but was not fetched locally | Run `git fetch origin tag v1.0.0`, then `git checkout v1.0.0` | | `results/figure1.pdf: FAILED` from `sha256sum -c` | An output file differs byte for byte from the recorded checksum | Diff against the archived results, check random seeds and input paths, and fix the cause before relying on the release | | `ResolvePackageNotFound: - pandas=2.1.1` during `conda env create` | A package version recorded in `environment.yml` is unavailable in the listed channels | Rebuild the environment file from the container in which the analysis actually ran, then re-verify | ## Why Released Versions Carry Scientific Weight Reviewers, collaborators, and readers judge a study partly by whether its computational and procedural details are complete enough to repeat. Published studies show what that completeness looks like. One cross-sectional clinical study stated the exact software and version used for the statistical analyses (SPSS version 25), the significance threshold applied (p < 0.05), the specific risk assessment tool with its validation region, and the 13-month study window [5]. A quantitative histology study documented an automated image-analysis pipeline built on QuPath, runnable on a standard laptop, that processed more than 250,000 endocrine cells across more than 3500 islets from ten donors, with each cell recorded as an (x, y) coordinate in a region of interest [6]. Neither study needed to explain the concept of reproducibility. The recorded versions, thresholds, and pipeline details did the work. Your release tag is the container for the same kind of detail in a computational project. When a tag annotation names the container digest, the environment file, the data accession, and the checksum file, a reader has everything the published methods section would list, plus the exact bytes. ## The Reproducibility Checklist Run through this reproducibility checklist before you publish a tag. Each item is binary. Either the tag satisfies it or it does not. - [ ] The working tree was clean when the tag was created - [ ] The tag is annotated, with a message naming the milestone - [ ] The tag name follows one consistent versioning convention across the project - [ ] An environment file (`environment.yml` or `requirements.txt`) is committed at the tagged commit - [ ] A container image exists, and its immutable digest is recorded in the tag message - [ ] Input data is either committed, deposited with an accession, or listed in a manifest with checksums - [ ] Analysis parameters and random seeds are set in a committed configuration file, not typed interactively - [ ] Output checksums were regenerated from a clean run and committed as `results.sha256` - [ ] A cold reproduction from a fresh clone passed `sha256sum -c` - [ ] The tag is pushed, a release is published, and an archival DOI exists - [ ] The DOI and tag name appear in the manuscript If any box stays empty, the release is a snapshot of intent rather than a snapshot of evidence. ## Release Tagging Tips for Research Projects **Tag at natural milestones, not daily.** A tag marks a claim: the figures submitted for review, the data release accompanying a talk, the state of the code at the moment a collaborator repeated the analysis. Tag when a claim is made. **Write tag messages for a stranger.** Assume the reader knows nothing about your lab. Name the manuscript, the environment, the data source, and the run command. **Never move a published tag.** If a bug appears in v1.0.0, fix the code and release v1.0.1. Renaming a tag that others have already fetched silently changes what the old name points to, which destroys the provenance the tag existed to provide. **Record seeds and configuration, not just code.** A stochastic analysis is only reproducible if the random seed is written into a committed config file. Place `set.seed(42)` in R scripts or `np.random.seed(42)` in Python scripts under version control, or better, pass the seed from `config/params.yaml`. **Automate tagging with continuous integration.** Platforms such as GitHub Actions and GitLab CI can, on a pushed tag, build the container, run the pipeline, generate checksums, and attach outputs to the release. Automation removes the human shortcut of verifying only on the day the paper is due. **Tag analyses and pipelines separately when both change.** If your lab maintains a shared preprocessing pipeline and individual downstream analyses, tag each repository on its own schedule and record the pipeline version inside each analysis release. **Treat checksums as a floor, not a ceiling.** Matching checksums prove the recorded files are intact. They do not prove the analysis is correct or that unrecorded intermediate files were identical. Verification and validation remain separate activities. ## Common Mistakes and Limitations **Tagging dirty trees.** The most frequent failure is running `git tag -a` while files are modified or untracked. The tag then points at code that does not include the changes you believe it does. The fix is mechanical: require a clean `git status` before every tag. **Environment drift.** An environment file written months after the analysis often records a different package set than the one that produced the results, because packages were upgraded between the analysis and the write-up. Rebuild environments at analysis time, or run everything inside a container whose digest is captured immediately. **Stuffing data into the repository.** Git is built for text, not for hundreds of gigabytes of imaging or sequencing data. Repositories slow to a crawl and collaborators clone the wrong things. Commit small metadata and manifests, and deposit data in an archive with an accession. **Skipping cold reproduction.** A release that was never regenerated from a fresh clone is a hypothesis. The single cheapest quality control in this entire workflow is Step 7, and it takes minutes on a small project. **Confusing a commit hash with a release.** Every commit has a hash, so hashes are abundant and uncommunicative. A release is a curated, named, documented, archived claim. The hash identifies a state, while the release asserts that the state is worth reproducing. **Overwriting container tags.** Pushing a new build under the same registry tag silently replaces the old image. Anyone who recorded only `yourlab/gexp-analysis:v1.0.0` without the digest now gets different software. Always record the digest alongside the tag name. **Assuming all outputs need to be byte-identical.** Some file formats embed timestamps or write nondeterministic ordering, so checksums can differ even when the scientific content matches. In that case, compare the scientific content of the outputs and record which files are expected to vary in the README. One practical limitation applies across the board. Project policies on data sharing, containers, and archival deposits differ by institution and funder, so check the specific requirements that govern your own study before choosing which archival service and repository settings to use. ## Frequently Asked Questions ### What is release tagging in reproducible research? It is the practice of attaching a permanent, named label to a frozen snapshot of a research project, including code, environment, data references, and output checksums, so that the exact conditions behind a result can be recovered and re-executed later. ### What is the difference between an annotated tag and a lightweight tag? An annotated tag stores a tagger, date, and message, which gives it provenance, while a lightweight tag is only a name attached to a commit. Use annotated tags for research releases because the message and metadata are part of the record. ### What version numbering should I use for research releases? Use semantic versioning, the `MAJOR.MINOR.PATCH` convention. Increase the major number when results change incompatibly, the minor number when you add capability without changing existing results, and the patch number for corrections. ### Can I change a tag after pushing it? No. Moving or deleting a published tag breaks the provenance of every claim tied to that name, and Git will refuse the push by default. Publish a new version number instead. ### How do I handle data files that are too large for the repository? Commit a manifest that lists each data file with its size and checksum, deposit the data in an archival repository, and record the accession in the tag message and README. ### Do I need containers to make a release reproducible? Not strictly, but an environment file alone leaves operating system libraries unpinned, so containers are the stronger guarantee. At minimum, commit an exact environment specification for every release. ### How is a release tag different from a commit hash? Every commit has a hash, so hashes identify states but assert nothing. A release is a curated, documented, archived version that a human chose to stand behind, and the tag names that choice. ### When should I tag a release during a project? Tag whenever a claim becomes citable: at manuscript submission, at the revision responding to reviewers, at each published data release, and at any point a collaborator or reviewer needs to regenerate a result. ## Sources 1. [Quantitative proteome analysis by solid-phase isotope tagging and mass spectrometry.](https://pubmed.ncbi.nlm.nih.gov/11981568/) 2. [Amine-reactive isobaric tagging reagents: requirements for absolute quantification of proteins and peptides.](https://pubmed.ncbi.nlm.nih.gov/18510936/) 3. [Enhancing Comprehensive Analysis of Newly Synthesized Proteins Based on Cleavable Bioorthogonal Tagging.](https://pubmed.ncbi.nlm.nih.gov/34197092/) 4. [Peptide- and Protein-Level Combined Strategy for Analyzing Newly Synthesized Proteins by Integrating Tandem Orthogonal Proteolysis with Cleavable Bioorthogonal Tagging.](https://pubmed.ncbi.nlm.nih.gov/36549687/) 5. [Beyond blood pressure and glucose: exploring potential biochemical predictors of cardiovascular disease risk in patients with type 2 diabetes mellitus and co-morbid hypertension.](https://pubmed.ncbi.nlm.nih.gov/40866890/) 6. [Beyond the loss of beta cells: a quantitative analysis of islet architecture in adults with and without type 1 diabetes.](https://pubmed.ncbi.nlm.nih.gov/40011232/)