How to Optimize Your GitHub Repository with README, LICENSE, CODEOWNERS, and More

README File

A README file is a common self‑describing document that, when placed in the root of a repository, is displayed on the repository’s GitHub home page.

Typical filenames and formats include:

README (plain text)

README.txt (plain text)

README.md (GitHub‑style Markdown)

README.adoc (Asciidoctor)

Avoid using raw HTML in the README because GitHub will render it as literal code.

You can also set an organization README by adding a README file under .github/profile in an organization repository.

License Files

Most projects include a LICENSE (or LICENSE.txt) file in the root directory. GitHub provides a UI to add a license when creating a new file.

Common open‑source licenses you can select include:

Apache License 2.0

GNU General Public License v3.0

MIT License

BSD 2‑Clause "Simplified" License

BSD 3‑Clause "New" or "Revised" License

Boost Software License 1.0

Creative Commons Zero v1.0 Universal

Eclipse Public License 2.0

GNU Affero General Public License v3.0

GNU General Public License v2.0

GNU Lesser General Public License v2.1

Mozilla Public License 2.0

The Unlicense

After adding a license, GitHub displays it on the repository page’s right side.

CODEOWNERS

GitHub automatically adds repository configurators to pull requests. You can define owners in a CODEOWNERS file, similar to a .gitignore file.

Rules summary:

The CODEOWNERS file can be placed in the root or .github folder.

Each branch can have a different CODEOWNERS file.

Lines consist of a pattern and one or more owners. *.txt @nfrankel This gives @nfrankel ownership of all .txt files.

@johndoe
docs     @nfrankel

@johndoe

owns everything, but @nfrankel specifically owns the docs folder. @johndoe @nfrankel Multiple owners can be listed on a single line. Owners can be individuals or teams (e.g., @org/team).

SECURITY File

A SECURITY file (plain text, .txt, or Markdown .md) lets projects define private channels for reporting security issues.

Like CODEOWNERS, it can be placed in the repository root or a .github folder.

The simplest way to create it is via the GitHub UI: go to the Security tab and click “Set up security policy”. GitHub provides a default Markdown template that you can edit.

CITATION File

If your project is cited in academic works, include a CITATION.cff file (Citation File Format) with citation metadata.

Example content:

cff-version: 1.2.0
title: Beautify GitHub sample repository
message: If you really want to cite this repository, here's how you should cite it.
type: software
authors:
  - given-names: Nicolas
    family-names: Fränkel
repository-code: 'https://github.com/ajavageek/beautifygithub'
license: Unlicense

After adding the file, a “Cite this repository” link appears on the right side, offering formats such as APA or BibTeX.

Funding Configuration

To enable sponsorship, add a FUNDING.yml file. GitHub UI helps create the file; you can specify GitHub and custom funding URLs.

github:
  - nfrankel
custom:
  - https://paypal.me/nicofrankel

The preview tab validates the content. If the user is not registered in the GitHub Sponsors program, validation will fail.

Conclusion

GitHub offers multiple ways to enhance a repository’s presentation and usability. Adding proper license and README files is essential, and the additional files described above—CODEOWNERS, SECURITY, CITATION, and FUNDING—provide further polish and professionalism for any open‑source project.

The full source code for this guide is available at https://github.com/ajavageek/beautifygithub .