• I keep coming across GitHub’s magic files that have some mystical / magic feeling to them. There’s always a small incantation to accompany them: they must have the right name, the right extension, and be stored in the right directory. Below is a condensed overview of the “magic” files I’ve found so far during my projects.


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

    Filename Location .github
    repo support
    Description Docs
    CNAME root no Alias for the GitHub Pages site Docs
    CONTRIBUTING.md root, /docs or /.github yes How to contribute to a project Guidelines
    CODE_OF_CONDUCT.md root, /docs or /.github yes Code of conduct How to behave for this project 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, CITATION.md, and others root or inst/CITATION no Let others know how to citate your work cff
    LICENSE or LICENSE.md or LICENSE.txt or LICENSE.rst root no License
    FUNDING.yml /.github folder yes Instructions for how to report a security vulnerability Docs
    SECURITY.md root, /docs or /.github yes Instructions for how to report a security vulnerability Security policy
    SUPPORT.md root, /docs or /.github yes Tell people how to get help for the code in the repo Docs
    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
    README.md root yes, see below Project readme, also used on marketplace if the repo is published to the marketplace About readme
    README.md .github/username/username Profile readme About readme
    README.md organization’s .github repo
    .github-private repo: profile/README.md
    Organization readme Organization readme
    release.yml .github Automatically generated release notes Automatically generated release notes
    workflow.yml .github/workflows/ Workflows
    action.yml/action.yaml root Configuration file for an actions repository
    dependency-review-config.yml .github no Dependency review configuration file Dependency review
    $GITHUB_STEP_SUMMARY workflow Job summary output in markdown Job summary

    Then there is a whole list of templates you can configure for issues / pull requests / discussion:

    Filename Location .github
    repo support
    Description Docs
    FORM-NAME.yml .github/ISSUE_TEMPLATE/ Issue templates with forms (in Beta for github.com, not available for GHES) Templates
    config.yml .github/ISSUE_TEMPLATE/ Issue templates configuration settings Template chooser
    issue_template.md .github/ISSUE_TEMPLATE/ yes Issue template Template
    Url query In the url link Create an issue with certain fields filled in with values Create issue with url query
    pull_request_template.md root, /docs, /.github or in the PULL_REQUEST_TEMPLATE directory yes Create the default body for a Pull Request Using a PR template
    Discussion category templates /.github/DISCUSSION_CATEGORY_TEMPLATES ? Create discussion category templates Create discussion category forms

    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: README.md.

    Screenshot of creating the .github repo

    There are also some magic links that can be super useful.

    Link setup Description Documentation
    github.com/OWNER/REPO/releases/latest Permalink to the latest release Permalink to latest release
    github.com/userhandle.keys Get the public part of a users SSH key
    github.com/userhandle.gpg Get the public part of a users GPG key
    github.com/userhandle.png Get the profile picture of a user
    avatars.githubusercontent.com/userhandle?s=32 Easy method to show user profile pictures anywhere. The `s` parameter is the size. Example output of my GitHub avatar: LoreZyra
    github.com/owner/repo#readme Scroll the repo link to open up with the README text on the page. Since GitHub shows the file content of the repo first, this can be helpful to push you users down the page into the README section. This works because the README is based on a header in the page, so this is just normal HTML behaviour.

    Atom feeds

    A lot of things have atom feeds enabled. The things in all caps need to be configured:

    Link setup Description
    github.com/OWNER/REPO/commits.atom Get an RSS feed for the commits in that repo
    github.com/OWNER/REPO/commits/BRANCH.atom Get an RSS feed for all the commits in that branch
    github.com/OWNER/REPO/wiki.atom Feed for the wiki in that repo
    github.com/OWNER/REPO/discussions.atom Get an RSS feed for the discussions in that repo
    github.com/OWNER/REPO/releases.atom Get an RSS feed for the releases in that repo
    github.com/USER.atom Get an RSS feed for the user’s public activity
    github.com/security-advisories Get an RSS feed for ALL the security advisories

    There should also be a feed for issues, but I continuously get HTTP:406 errors on github.com/OWNER/REPO/issues.atom. Other user specific feeds can be loaded by making an authenticated call to `https://api.github.com/feeds`.

    Evolution of Money
    How to Create Content Strategy
    Table of Contents
    Table of Contents