108

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.

Yves M.
  • 29,855
  • 23
  • 108
  • 144
Jeremy French
  • 11,707
  • 6
  • 46
  • 71
  • 6
    May not be complete, but [this](https://help.github.com/en/github/building-a-strong-community/setting-up-your-project-for-healthy-contributions) seems to be a good starting list. – GoodDeeds Mar 03 '20 at 12:33
  • 3
    Yes that is good for community repos, but misses out actions and who knows what else. – Jeremy French Mar 03 '20 at 12:46
  • 1
    @JeremyFrench does my answer provide enough info for your question ? If it does, you can accept it as well – Dinko Pehar Nov 23 '20 at 20:10
  • 2
    @DinkoPehar I have done so, it may be nice to mark as CW (if that's still possible) so that others can update in the future if new things are aded. – Jeremy French Nov 25 '20 at 01:03

2 Answers2

111

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.

Ross Smith II
  • 11,799
  • 1
  • 38
  • 43
Dinko Pehar
  • 5,454
  • 4
  • 23
  • 57
  • 7
    GitHub seems to ignore a license file in .github — only seems to pay attention to it in the project root. – tobyink Nov 23 '20 at 01:52
  • 6
    You can also create settings.yml file in which settings for repository can be set – Pitirus Nov 23 '20 at 14:28
  • 1
    CODEOWNERS is another one I'd add to your list as well https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners – alanwill Feb 05 '21 at 19:17
  • 1
    @alanwill you can edit and add it now. I marked it as community wiki – Dinko Pehar Feb 06 '21 at 23:59
  • 1
    Always put license files in the root of a project, not in the `.github/` folder. – jonschlinkert Apr 03 '21 at 13:43
  • 1
    @jonschlinkert Yes, as stated above. – Dinko Pehar Apr 03 '21 at 18:58
  • 2
    It should just be removed from the list, not have a disclaimer. – jonschlinkert Apr 06 '21 at 16:52
  • 1
    Yes, I agree it doesn't belong here in this list(.github files), but because it's a standard file inside GitHub(and many others), it's included in this list. But it's a community wiki, so you can edit it freely if you want. – Dinko Pehar Apr 07 '21 at 10:40
  • 1
    One addition not yet mentioned in this Q&A to date is the `README`. I'm not recommending it, necessarily, but GitHub does support placing the primary `README` in the `.github` directory per [these docs](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes#about-readmes). – Collin Barrett May 29 '23 at 22:36
17

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.

WikipediaBrown
  • 689
  • 1
  • 8
  • 27