Open source Github repository pre-launch checklist
What?
Open source a Github repository, based on our experience with dozen of projects at https://www.binbash.com.ar
Why?
At Binbash Leverage we have a Community subscription plan where our work is accesible as open source, thanks to it, there is a lower barrier to get started. That’s why dozens of companies use it. As a result, we receive several community adopters Github Pull Requests every month to improve our modules and fix bugs.
Check our repos at https://github.com/binbashar
- ✅ Collaboration: Open source projects can accept changes from anybody in the world.
- ✅ Adoption and remixing: Open source projects can be used by anyone for nearly any purpose. People can even use it to build other things. WordPress, for example, started as a fork of an existing project called b2.
- ✅ Transparency: Anyone can inspect an open source project for errors or inconsistencies. Transparency matters to governments like Bulgaria or the United States, regulated industries like banking or healthcare, and security software like Let’s Encrypt.
How?
1. Use a credential manager to protect your access credentials.
Example by using specific tools such as
2. Configure two-factor authentication (2FA)
Activate Github MFA
3. Enforce signed commits
Git makes it a little bit too easy to spoof commits and allow attackers to make their code to look like yours. GitHub supports cryptographic protection against such attacks.
4. Protect the release branch:
master branch protection must be setup when making the repo public.
5. Require pull request reviews and approvals.
PRs to master branch merge policies will be setup when making the repo public.
6. Scan source code for sensitive data leaks.
Mistakes happen and we sometimes commit sensitive data to public repositories. GitHub integrates with multiple services and can detect their leaked secrets. Options:
- https://docs.github.com/en/developers/overview/secret-scanning
- https://geekflare.com/github-credentials-scanner/
- https://github.com/anshumanbh/git-all-secrets
- https://github.com/trufflesecurity/truffleHog
- https://www.gitguardian.com/
7. Scrub leaked secrets from git history:
Sensitive data leaked into a public GitHub repository might be out of your control. Git and GitHub allow you to contain the damage by rewriting git history to remove the sensitive data.
8. No matter which stage you decide to open source your project, every project should include the following documentation:
✅ Open source license
✅ README (https://www.makeareadme.com/)
A CONTRIBUTING file tells your audience how to participate in your project. For example, you might include information on:
- How to file a bug report (try using issue and pull request templates)
- How to suggest a new feature
- How to set up your environment and run tests
In addition to technical details, a CONTRIBUTING file is an opportunity to communicate your expectations for contributions, such as:
- The types of contributions you’re looking for
- Your roadmap or vision for the project
- How contributors should (or should not) get in touch with you
✅ Code of conduct
- Helps set ground rules for behavior for your project’s participants. This is especially valuable if you’re launching an open source project for a community or company. A code of conduct empowers you to facilitate healthy, constructive community behavior, which will reduce your stress as a maintainer.
- Ref doc: https://github.com/kubernetes/community/blob/master/code-of-conduct.md
📒 NOTE: As a maintainer, these components will help you communicate expectations, manage contributions, and protect everyone’s legal rights (including your own). They significantly increase your chances of having a positive experience.
If your project is on GitHub, putting these files in your root directory with the recommended filenames will help GitHub recognize and automatically surface them to your readers.
9. README, try to answer the following questions:
- What does this project do?
- Why is this project useful?
- How do I get started?
- Where can I get more help, if I need it?
- How to contribute?
- Under which open source license the project is being developed?
10. Only use trusted GitHub Actions.
GitHub Actions are tremendously useful, but if you are not careful, you may end up running malicious or sloppy code in your build pipeline. Make sure you only run Actions you trust.
11. Protect the secrets used by GitHub Actions.
GitHub Actions that handle software releases and deployment often require credentials to work. Make sure these credentials are appropriately protected.
12. Review project vulnerabilities
- Review project dependencies for vulnerabilities.
- Patch dependencies with vulnerabilities.
- Scan project source code for vulnerabilities.
- https://snyk.io/ || https://dependabot.com/
13. Publish a security policy.
If your project is successful, there is a chance that someone will discover a security flaw in your code. Make it easy for them to report it and be very clear about what you will do with that report.
Examples
14. Collaborate on fixes for security vulnerabilities in private forks.
Working in the open means that it is impossible to hide things. And yet, sometimes you will want to work on some changes in the code in private, for example when fixing a security vulnerability. Working on a fix in the open might allow attackers to reverse engineer the bug and attack your users. GitHub provides a mechanism to easily create a private fork of your repo. Use this private fork to collaborate on a fix.
15. Publish maintainer advisories for security fixes.
Fixing a security vulnerability is no small feat and you should tell your users about it. You should do it in a way that will make it easy for them to learn about it and patch (see point 11 above). GitHub provides an easy way to publish a security advisory that will be incorporated into security scanning tools that your users depend on to keep their applications secure.
Summary Pre-launch Checklist
Documentation
- ☑️ Project has a LICENSE file with an open source license
- ☑️ Project has basic documentation (README, CONTRIBUTING, CODE_OF_CONDUCT)
- ☑️ The name is easy to remember, gives some idea of what the project does, and does not conflict with an existing project or infringe on trademarks
- ☑️ The issue queue is up-to-date, with issues clearly organized and labeled
Code
- ☑️ Project uses consistent code conventions and clear function/method/variable names
- ☑️ The code is clearly commented, documenting intentions and edge cases
- ☑️ There are no sensitive materials in the revision history, issues, or pull requests (for example, passwords or other non-public information)
People
If you’re an individual:
- ☑️ You’ve talked to the legal department and/or understand the IP and open source policies of your company (if you’re an employee somewhere)
If you’re a company or organization:
- ☑️ You’ve talked to your legal department
- ☑️ You have a marketing plan for announcing and promoting the project
- ☑️ Someone is committed to managing community interactions (responding to issues, reviewing and merging pull requests)
- ☑️ At least two people have administrative access to the project
