Is there an overview of what can go into a .github "dot github" directory?

I keep finding piecemeal examples of things that can go into a .github directory on a GitHub repository.

I can see that it is used for GitHub actions and workflow and for Pull request and issue templates, but I can't see a page outlining what you can put in there with ideally some documentation. I also think I've seen a funding example too.

Basically every time I see something you can do there, I think "that's neat I should do that", but other than examples I can't see a way to discover new things other than by example.

Due to the fact that the directory is called .github it seems to defy Google and SO search as well.


Solution 1:

On Github, folder .github is just a convention folder used to place Github related stuff inside it. Github handles some of these files even when you place it in root of your project (such as CONTRIBUTING.md, CODE_OF_CONDUCT.md etc). Because Github is constantly bringing in new features, these features are documented on their own, so there is no "all possible files in .github" page. Feel free to place anything that is related to Github specifically inside it.

Some of the most used files in .github folder:

  • CODE_OF_CONDUCT.md -> How to engage in community and how to behave yourself.
  • CONTRIBUTING.md -> How to contribute to repo (making pull request, setting development environment...)
  • LICENSE.md - A software license tells others what they can and can't do with your source code (You should place this at the root of your project since GitHub ignores it in .github folder. You can find this file while browsing other Git hosting services such as GitLab, Bitbucket etc.)
  • FUNDING.yml -> Supporting a project
  • ISSUE_TEMPLATE -> Folder that contains a templates of possible issues user can use to open issue (such as if issue is related to documentation, if it's a bug, if user wants new feature etc) P.S. Take a look at tensorflow ISSUE_TEMPLATE
  • PULL_REQUEST_TEMPLATE.md -> How to make a pull request to project
  • stale.yml -> Probot configuration to close stale issues. There are many other apps on Github Marketplace that place their configurations inside .github folder because they are related to GitHub specifically.
  • SECURITY.md -> How to responsibly report a security vulnerability in project
  • workflows -> Configuration folder containing yaml files for GitHub Actions
  • CODEOWNERS -> Pull request reviewer rules. More info here.
  • dependabot.yml -> Configuration options for dependency updates. More info here.

You don't have to create all these files immediately. If there are lot of bugs reported in your project, create ISSUE_TEMPLATE. If several people wants to support you, create FUNDING.yml . You will create more and more files when the need comes.

Solution 2:

Github lists all of the files you can use in the documentation page titled Creating a default community health file and the workflows you can add to the .github directory are detailed in the Introduction to GitHub Actions documentation.