Skip to main content

This version of GitHub Enterprise Server was discontinued on 2024-03-26. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise Server. For help with the upgrade, contact GitHub Enterprise support.

About CITATION files

You can add a CITATION file to your repository to help users correctly cite your software.

About CITATION files

You can add a CITATION.cff file to the root of a repository to let others know how you would like them to cite your work. The citation file format is plain text with human- and machine-readable citation information.

Example CITATION.cff file:

cff-version: 1.2.0
message: "If you use this software, please cite it as below."
authors:
- family-names: "Lisa"
  given-names: "Mona"
  orcid: "https://orcid.org/0000-0000-0000-0000"
- family-names: "Bot"
  given-names: "Hew"
  orcid: "https://orcid.org/0000-0000-0000-0000"
title: "My Research Software"
version: 2.0.4
doi: 10.5281/zenodo.1234
date-released: 2017-12-18
url: "https://github.com/github-linguist/linguist"

The GitHub citation prompt on your repository will show the example CITATION.cff content in these formats:

APA

Lisa, M., & Bot, H. (2017). My Research Software (Version 2.0.4) [Computer software]. https://doi.org/10.5281/zenodo.1234

BibTeX

@software{Lisa_My_Research_Software_2017,
  author = {Lisa, Mona and Bot, Hew},
  doi = {10.5281/zenodo.1234},
  month = {12},
  title = {{My Research Software}},
  url = {https://github.com/github-linguist/linguist},
  version = {2.0.4},
  year = {2017}
}

Note the example above produces a software citation (that is, @software type in BibTeX rather than @article).

For more information, see the Citation File Format website.

When you add a CITATION.cff file to the default branch of your repository, a link is automatically added to the repository landing page in the right sidebar, with the label "Cite this repository." This makes it easy for other users to cite your software project, using the information you've provided.

Screenshot showing the landing page for a repository. The "Cite this repository" link in the right sidebar is highlighted with a dark orange outline and a dropdown menu with the citation details is expanded underneath.

Citing something other than software

If you would prefer the GitHub citation information to link to another resource such as a research article, then you can use the preferred-citation override in CFF with the following types.

ResourceCFF typeBibTeX typeAPA annotation
Journal article/paperarticle@articleNot applicable
Bookbook@bookNot applicable
Booklet (bound but not published)pamphlet@bookletNot applicable
Conference article/paperconference-paper@inproceedings[Conference paper]
Conference proceedingsconference, proceedings@proceedingsNot applicable
Data setdata, database@misc[Data set]
Magazine articlemagazine-article@articleNot applicable
Manualmanual@manualNot applicable
Misc/generic/othergeneric, any other CFF type@miscNot applicable
Newspaper articlenewspaper-article@articleNot applicable
Softwaresoftware, software-code, software-container, software-executable, software-virtual-machine@software[Computer software]
Report/technical reportreport@techreportNot applicable
Unpublishedunpublished@unpublishedNot applicable

Extended CITATION.cff file describing the software, but linking to a research article as the preferred citation:

cff-version: 1.2.0
message: "If you use this software, please cite it as below."
authors:
- family-names: "Lisa"
  given-names: "Mona"
  orcid: "https://orcid.org/0000-0000-0000-0000"
- family-names: "Bot"
  given-names: "Hew"
  orcid: "https://orcid.org/0000-0000-0000-0000"
title: "My Research Software"
version: 2.0.4
doi: 10.5281/zenodo.1234
date-released: 2017-12-18
url: "https://github.com/github-linguist/linguist"
preferred-citation:
  type: article
  authors:
  - family-names: "Lisa"
    given-names: "Mona"
    orcid: "https://orcid.org/0000-0000-0000-0000"
  - family-names: "Bot"
    given-names: "Hew"
    orcid: "https://orcid.org/0000-0000-0000-0000"
  doi: "10.0000/00000"
  journal: "Journal Title"
  month: 9
  start: 1 # First page number
  end: 10 # Last page number
  title: "My awesome research software"
  issue: 1
  volume: 1
  year: 2021

The example CITATION.cff file above will produce the following outputs in the GitHub citation prompt:

APA

Lisa, M., & Bot, H. (2021). My awesome research software. Journal Title, 1(1), 1. https://doi.org/10.0000/00000

BibTeX

@article{Lisa_My_awesome_research_2021,
  author = {Lisa, Mona and Bot, Hew},
  doi = {10.0000/00000},
  journal = {Journal Title},
  month = {9},
  number = {1},
  pages = {1--10},
  title = {{My awesome research software}},
  volume = {1},
  year = {2021}
}

Citing a dataset

If your repository contains a dataset, you can set type: dataset at the top level of your CITATION.cff file to produce a data citation string output in the GitHub citation prompt.

Other citation files

The GitHub citation feature will also detect a small number of additional files that are often used by communities and projects to describe how they would like their work to be cited.

GitHub will link to these files in the Cite this repository prompt, but will not attempt to parse them into other citation formats.

# Note these are case-insensitive and must be in the root of the repository
CITATION
CITATIONS
CITATION.bib
CITATIONS.bib
CITATION.md
CITATIONS.md

# CITATION files for R packages are typically found at inst/CITATION
inst/CITATION

Citation formats

We currently support APA and BibTeX file formats.

Are you looking for additional citation formats? GitHub uses a Ruby library, to parse the CITATION.cff files. You can request additional formats in the ruby-cff repository, or contribute them yourself.