Part 1 of the DevOps for Non-DevOps Engineers series

- A list of links to future posts in this series will go here

Introduction

You may have seen the .github/ folder in git repositories you’ve cloned or forked on GitHub. Perhaps you’ve looked inside and maybe you’ve edited a file in there, maybe not. Either way, if you’ve made it this far, you are now at least aware of the folder’s existance. It’s a reserved folder name in GitHub repositories and it can hold special files for things like templates, documentation, actions, workflows and more.

We’re going to take a look at that folder and each item that can go inside it to learn how to use them most effectively. Eventually this post will have links to detailed posts on each item that can go in the .github folder. If you don’t see a link to a topic’s detail post yet, it’s on it’s way, so check back soon.

The .github/ Folder

You can add a folder named .github to the root of any .git repository hosted on GitHub. Just to be clear, the ‘dot’ in front of github is included in the folder’s name.

You can also create it as a special repository in your GitHub.com personal account or organization; there it will act as the default for all of your or the organization’s repositories unless a repository has it’s own repo-specific .github folder with a matching filename.

Files and Subdirectories

PULL_REQUEST_TEMPLATE/

PULL_REQUEST_TEMPLATE.md

Add a template for submitting new pull requests on GitHub.

ISSUE_TEMPLATE/

A subdirectory for adding templates to the GitHub ‘Issues’ feature.

ISSUE_TEMPLATE/config.yml

A configuration file for the Issue Templates List page on GitHub, allowing you to customize the template option cards and button labels, as well as the order they appear in, and other properties for the ‘Issues’ feature tab on the GitHub’s page for the repository.

DISCUSSION_TEMPLATE/

A subdirectory for adding templates to the GitHub ‘Discussions’ feature.

DISCUSSION_TEMPLATE/config.yml

A configuration file for the Discussion Templates List page on GitHub, allowing you to customize the template option cards and button labels, as well as the order they appear in, and other properties for the ‘Discussion’ feature tab on the GitHub’s page for the repository.

CODE_OF_CONDUCT

How to engage in a repository’s community and basic set of rules for participating in issues, discussions, pull requests, comments and other activities as they relate to a repository.

CODEOWNERS

A configuration file for assigning Senior Team Members as responsible for reviewing and approving all pull requests containing code written in a given language (.js, .ts, .php, .py, etc).

CONTRIBUTING

A documentation file with a guide for contributing to a project.

FUNDING.yml

A configuration file the GitHub ‘Sponsor Button’ feature.

README.md

Your README.md file for your entire project can go into this folder. You can also holst a second README.md file here with information on you workflows and issues and other things in the .github folder

workflows/

A folder for storing workflows consisting of actions and the trigger events to run them on and use GitHub’s built in CI/CD features and integrate GitHub with other services.

SECURITY.md

A guide explaining how to responsibly report any security vulnerabilities that you find in a project.

dependabot.yml

A configuration file for dependency update monitoring using the GitHub ‘Dependabot’ feature.

settings.yml

A configuration file for your repository settings on GitHub.

.gitignore

A subdirectory .gitignore file, which will choose what files to ignore after entering this subdirectory. i.e. git will only apply this specific .gitignore ruleset to files and folders inside this subdirectory, or only to files and folders with this path relative to the rootsrc/.github/[FILE_NAME]

Other Files

The .github folder isn’t typechecked or otherwise restricted. If you have your own tools or want to integrate your own bots or services into you GitHub repositories, you can add other files here. /.github/stale.yml is a good example of this. The file isn’t a specific file that the GitHub service uses, there is no official mention of it in GitHub’s documentation, but many bots look for that file and use it to clean up stale pull requests. There are also many other apps on the GitHub Marketplace that will place configuration files in the .github folder since they are specifically related to GitHub.

stale.yml

A configuration file for ProBot automations.

Files That Should NOT Go In This Folder

LICENSE or LICENSE.md

Any file containing a software license should be at the root of the repository. You should not place your license file in the .github folder and your code will not be properly legally licensed if you put your license here.

The .github Repository

You can create a default .github folder for all of your GitHub repositories by creating a .github repository. Set it up just like any other GitHub repository, make sure that it is public and initialize it with a README.md file. Then you can upload any of the normal files or subdirectories and their files to the GitHub repository and GitHub will apply it as a default to all of your or your organization’s repositories that don’t already have their own .github folder at the root of the repository.

Conclusion

You can use the .github folder to organize and automate your software development projects on GitHub. It is an often overlooked feature that can standardize, simplify and automate repetitive tasks in your development processes.