A starter repo for new projects. Adds CI and build/release defaults, and setup instructions using good practices.
It currently includes:
- Setup instructions for a new repo
- Repo configurations for
- Having a protected and clean
mainbranch - Disabling undesirable GitHub features (i.e. wiki, etc.)
- Having a protected and clean
- GitHub Actions for
- Pull request status checks, at PR creation and update (i.e. where you might want to run tests)
- Automatically tag changes to the
mainbranch based on auto-incremented SemVer version numbers - ^ Then publish your build artifacts for that version tag
- For web apps:
- Dockerfile and Docker Compose (with PostgreSQL and Redis commented out defaults)
- For native mobile apps:
- (nothing yet)
This will guide you through getting setup with this repo's default files and practices. Skip a step or remove config files as relevant to your own workflows and needs.
This will setup a new repo with the files from within this one.
- Create a new repo on GitHub
- Clone your repository locally
- Clone this repository:
git clone https://github.com/jeffmaher/github-starter-template.git - Using your terminal, navigate into the cloned github-starter-template directory:
cd <path to your template clone> - Delete Git metafiles from the template repository:
rm -rf .git - Copy the template's files into your repository:
cp -r ./* <path to your repository> - Go back to your new repository, and commit the copied files:
cd <path to your new repository> && git add . && git commit -m "Setting up repo with jeffmaher/github-repo-starter-template" && git push
(Alternately, you can fork this repository and then reference it as a template during the repository creation process.)
By only allowing squash merging in pull requests, your changes will only be merged in as atomic commits and reduces the amount of noise in your commit log. This makes it easier to rollback changes and see when your main branch definitely changed.
To do this, follow these steps:
- From your repository's page, go to Settings.
- From the Pull Requests section, have the following settings:
- Allow merge commits
- Allow squash merging
- Allow rebase merging
- Automatically delete head branches
The last checkbox makes sure you don't have a lot of dead branches lingering in your repository.
You'll likely be running tests or running static analysis tools when pull requests are created, updated (i.e. a new commit comes in), or re-opened (after being closed). For any job that you want GitHub Actions to run at pull request time, either modify or add steps to the .github/workflows/pull_request.yml file. Commands in the file say how to do this.
Additionally, all of the provided pull request steps rely on CI script skeletons that are stored in the ci folder. It's a good practice to use these scripts, which makes for easier and consistent runs between GitHub Actions and local runs before committing.
Lastly, these instructions assume you're using a web application via Docker container. If that's not the case (i.e. mobile apps, not using Docker, etc.), adjust the workflow files according. For example, for a non-Docker app, you might remove the Docker commands and just use the shell scripts (i.e. remove the Docker command: docker-compose -f docker-compose.yml -f ci/docker-compose.ci.yml run app, then leave sh ci/<script>.sh).
Note: To make the next section easier for requiring status checks, create one pull request to trigger the PR checks.
To ensure that anything that gets merged to your main branch goes through peer review, perform the following steps:
- In your web browser, go to your repo
- Go to your repo's Settings section
- Go to Branches
- Choose Add rule in the Branch protection rules section
- Configure the following settings, then click Create (leave a setting as the default if not mentioned):
- Branch name pattern:
main - Require pull request reviews before merging
- Dismiss stale pull request approvals when new commits are pushed
- Require review from Code Owners (see later section to configure)
- Require status checks to pass before merging
- Require branches to be up to date before merging
- (After your first pull request, come back here and select required checks)
- Require branches to be up to date before merging
- Require signed commits (Optional: if you want your commits to be end-to-end encrypted in transit)
- Include administrators
- Branch name pattern:
Doing these steps will automatically version your main branch whenever you merge a pull request to it (i.e. cut a version whenever the code changes) using a SemVer-style versioning scheme. This will help with the creation and labeling of build artifacts, make it easier for release processes and managers to deploy deliberate versions of the codebase, and make investigation and fixing of the issues simpler since you'll know exactly what the code looked like for any deployed artifact.
Start by adding some release labels:
- In your web browser, go to your repo
- Go to the Issues tab
- Go to the Labels tab
- Add the following New labels:
release-majorrelease-minorrelease-patch
- Enable the
one_release_labelPR status check as mandatory on any PRs to yourmainbranch (see Protect yourmainbranch for instructions). - Create a
0.0.0tag on your repo (you can do this from the Releases section of your repo on GitHub) - Next time you merge a PR to
main, a new version tag will get cut incrementing from the last highest version number AND it will run the build/publish script (which you should setup with the appropriate commands).
Wikis created via GitHub Wiki's tab aren't easy to backup, aren't version controlled in the same stream as the code (i.e. which version of the code does your wiki doc belong to?), and don't have pull requests as a change control mechanism. The feature is better left off and documentation can be stored in the docs folder and referenced images for documentation can be put into docs/images.
To make sure folks don't use the GitHub Wiki feature, turn it off with the following steps:
- From your repository's page, go to Settings.
- From the Features section, uncheck Wikis.
If there are files that you want to have extra protections on or that you want folks with specific expertise to review, you might consider configuring a CODEOWNERS file. A file with commented out examples of when you might want to do this is provided at .github/CODEOWNERS. Some of these examples might include:
- In continuous delivery environments, requiring a product owner and a developer to sign-off on any change
- Getting your UX visual design group to review any UI change (i.e. changes to any UI code)
- When a security policy is changed, requiring your security group to review
- Any GitHub configuration changes should be reviewed by a core contributor
This feature is more powerful in GitHub repos that live within a GitHub org rather than individual accounts since you can reference groups within your org. This not only makes it easier to maintain, but allows "OR" like behaviour. For example, if you mark README.md as being owned by three individual users, then all 3 need to review the file before it is approved. If you place these three individuals in a GitHub org group, then the file can be owned by the group and only one of them needs to review the file for approval.
More information can be found in GitHub's docs.
There are a few files that explain to others what your repository is for and how to use it. You should replace the content of these files with your own stuff. Those files are:
This describes your repository in plain language. Important things to include are:
- Name of the repository
- 1-3 paragraph summary of what it does and who it's for
- Instructions on how to use it (or a link to them) from a new computer or blank virtual machine
What you allow people to do with your code should be described in here. Consider starting with an already existing license.
These are instructions for how people can contribute to your repository (or whether contributions are even accepted). Mozilla Science has a good explanation of what might go into this file.
Use these next instructions...
Lots of web applications use PostgreSQL and Redis for their database and session stores, respetively. If this is your case, see docker-compose.yml to uncomment lines that include this in your Docker Compose setup.