Date posted: 26 Nov 2021, 2 minutes to read

GitHubs magic files

I keep coming across files in GitHub that have some mystic magic feeling to them. There’s always a small incantation to come with them: the have to have the right name, the right extension and have to be stored in the right directory. I wanted to have an overview of all these spells for myself, so here we are 😉.

Photo of a cauldron with a person pointing a want to it, mist coming out of the cauldron

Photo by Artem Maltsev on Unsplash


A list of all the magic files / links that I came across in GitHub.

Filename Location .github repo support Description Docs
CNAME root   Alias for the GitHub Pages site root, /docs or /.github yes How to contribute to a project Guidelines   yes Code of conduct  
CODEOWNERS root, /docs or /.github   List of people who can make changes to the files or folders Code owners info
CITATION.cff root no Let others know how to citate your work cff or LICENSE.txt or or LICENSE.rst root no   License   yes   yes   yes    
FORM-NAME.yml .github/ISSUE_TEMPLATE/   Issue templates with forms (in Beta for, not available for GHES) Templates
config.yml .github/ISSUE_TEMPLATE/   Issue templates configuration settings Template chooser .github/ISSUE_TEMPLATE/   Issue template Template
Url query In the url link   Create an issue with certain fields filled in with values Create issue with url query root, /docs, /.github or in the PULL_REQUEST_TEMPLATE directory   Create the default body for a Pull Request Using a PR template
workflow.yml workflow-templates only available in .github repo Store starter workflows for your organizations Starter workflow templates
dependabot.yml .github/   Dependabot configuration file Dependabot configuration
codeql-config.yml .github/codeql/codeql-config.yml (convention, not required) sort of CodeQL configuration file. Can also be stored in an external repository (hence .github repo works). If using external repo, referencing can by done by using owner/repository/filename@branch CodeQL config
secret_scanning.yml .github/secret_scanning.yml   Secret scanning configuration file Secret scanning root / ?   Project readme, also used on marketplace if the repo is published to the marketplace .github/username/username   Profile readme About readme’s organizations .github repo or .github-private repo: profile/   Organization readme Organization readme
workflow.yml .github/workflows/     Workflows
action.yml/action.yaml root   Configuration file for an actions repository  
$GITHUB_STEP_SUMMARY workflow   Job summary output in markdown Job summary
/releases/latest link   To permalink to the latest release as any time. Permalink to latest release

Some of these are extra tricky, like for example the organization profile lives in a different directory and repo then the user profile readme: .github or in .github-private repo in the org and then in a folder named profile:

Screenshot of creating the .github repo