The CDCGov organization on GitHub is designated for use by CDC programs to publish open source code. This is a set of practices to help programs release secure and compliant open source projects successfully. If you are interested in using GitHub for non-open source projects, please see information on our enterprise organization.
We designed these practices to be straightforward and helpful, and we accept feedback from the community on updating them. For Required Practices, Projects that don't adhere to the Required Practices could be subject to archival or removal.
Before you can publish your project, you must request access to be added to the CDCgov organization. Complete these steps:
- Review the Rules of Behavior.
- Confirm your Github profile is setup properly.
- Complete the project request form.
- This will require your CDC login, so if you don't have a login, ask someone to request on your behalf, or get in touch.
You should receive an email or notification when you are given access and your first repository should be setup for you. For subsequent projects, you will be able to create a repository in the organization using Github's interface. The template repository is maintained and an easy way to quick start your repository that complies with the guidelines. Once this is completed you're ready to follow the required guidelines to publish code.
You must follow these practices before you publish real code into your repository.
- Get Clearance. Always obtain clearance from your organization prior to setting up and publishing a repository.
- GitHub is a third party service used by CDC to collaborate with the public. Official CDC health messages will always be distributed through www.cdc.gov and through appropriate channels, so make sure to plan your project along with your official public health program on cdc.gov.
- Naming. Set a meaningful project name and short description for your project. The form to do this is in your repositories settings.
- Add topics to improve discovery and use of your project. For AI-related projects, the Code.gov Implementation Guidance to Federal Agencies Regarding Enterprise Data and Source Code Inventories must be followed when setting topics.
- Create a README. Add a
README.mdfile at the root with the following:- An overview of your project, including the purpose, goals and the team responsible.
- A description of your development process in the
README.mdfile. If your project is no longer active, mark it as archived. - Include the following notice sections. You can modify the verbiage and adapt as necessary based on your program need.
- Choose a license. Assign an open source license based on program need.
- If you need help choosing a license, please review this article, refer to existing CDCgov projects, or ask for consultation support in choosing a license.
- Security scanning and review.
- This is the final step before publishing and the most critical.
- All source code used within CDC systems must comply with all cybersecurity processes prior to production use, including static and dynamic scanning. The same applies to code published as open source.
- If you are unsure about compliance, reach out to your organization's security officers.
- Never commit sensitive information, including usernames, passwords, tokens, PII, PHI. To automate this, you can integrate pre-commit tools like Clouseau to systematically review material before committing.
- Make sure that the commit history of your Github repository also doesn't have these things. In many cases it's easier to start a new repository and push up the code that has all sensitive information removed as the first commit.
- Enable GitHub automated security alerts and configure notification for the repo admin to see.
- Setup your profile. Active project committers need to add profile info to help collaboration.
- Two-factor authentication (2FA). Project admins must secure their account with two-factor-authentication.
- Maintain your repository. Once your repository is published, you must do the following to remain in compliance:
- Respond to critical security issues and communication from administrators. Ignoring security issues or not responding to communication from administrators can result in archiving or removal.
- Archive old projects. If you're no longer updating the project or have moved it's location, update your
README.mdfile to let users know and archive the repository.
Optional improvements to make your open source project more successful.
- Establish pull request templates to make it easier for contributors to send pull requests. For example SDP-V has a checklist for each PR to match their development practices.
- Agree on project conventions and include them in your
README.mdfile. Depending on what type of project, this includes folder structure for data, linters, editor configuration (eg, MicrobeTrace's .editorconfig). This will help improve the quality of your project and make it easier for others to contribute to your project. - Add support and community procedures. CDC does not provide warranty or official support for open source projects, but describing how you would like questions and issues will assist users of your project. If you use a wiki, or project board, or package manager, describe and link to that. Official contribution steps will make it easier for people outside of CDC to contribute to your project.
- Include references to publications, presentations, and sites featuring your project.
- Add an entry to open.cdc.gov to the data, code, api, or event page to help people find your project on cdc.gov
- Add versions and tags describing major releases and milestones. For example, open.cdc.gov's releases each time a new version is published to the web site or geneflow's changelog.
- Follow Semantic Versioning 2.0.0 when creating versions for your project.
- Describe and test reproducible practices to install and build your project. For example, injury_autocoding's code section on running the project's scripts).
- Recognize contributors and existing resources that have helped the project. For example, fdns-ms-hl7-utils' AUTHORS file.
- Automate build and test procedures to reduce the effort of outside contributors to send pull requests (eg, Travis CI, Circle CI, GitHub Actions)
- Appropriately gather metrics on how your project is used and incorporate this into your feature planning process.
- Incorporate documentation into your development cycle, and where possible, automate the generation of documentation so it is more likely to be up to date and useful to people interested in your project.
If you need additional support with your setting up project, or have any feedback or ideas about this guidance please open an issue or send an email to data@cdc.gov. We also accept pull requests if you want to directly edit the guidance.
Projects in this organization are reviewed occasionally for compliance with the Required Practices. If your project is found to not be in compliance, you will be contacted by administrators to help bring your project into compliance. Projects that do not respond or that habitually fail to meet these practices will be archived or removed from the organization, depending on severity.
Please make sure your profile is set up properly to help us work better together. Specifically, keep your profile up to date with:
- Name: Your first and last name.
- Company: Your government agency or contracting company. (If you also use GitHub for personal projects, consider specifying “CDC (work) + personal projects” to make it clear that some of your GitHub projects may be personal in nature.)
- Location: Your primary work location (city, state).
- Photo: A headshot photo, or an appropriate image that is unique to you.
If you admin any projects, make sure to secure your account with two-factor authentication (2FA). Although you probably already did this because you are smart.
So you've decided to set up an open source project at CDC. Here are the steps to do that, in the most common order.
- Create a new project using the template repo.
- Update your readme.md following the CDC GitHub Practices for Open Source Projects
- Choose a license. Most projects are ASL2, but license should meet public health program need. See https://www.philab.cdc.gov/index.php/2012/03/27/open-source-development-for-public-health-informatics/ for more info on choosing a license.
- Remove all sensitive info.
- Talk with your ADI, ADS, and ISSO for review and clearance.
- After approval, create a GitHub user.
- Fill out the Request a Repo form for a new repo on CDCGov or CDCai.
- When you get an email or push alert that your repo is ready, push to GitHub
- Add an entry in open.cdc.gov on their code page to officially be linked from cdc.gov. This helps users find and use your project.
- Keep your project up to date, when you're finished flag it as archived.
This checklist was adapted from the CDC IT Guard Rail and put here to help people who don't have access to the intranet.
Our CDCent organization is used for private, non-public projects so only CDC staff and approved outside collaborators work on these projects, you can request access through the GitHub Enterprise Cloud form.
These are helpful links from across the Federal Government regarding open sourcing code.
- CFPB Open Tech
- TTS Engineering Practices Guide
- 18F Open Source Policy and Practicing our open source policy
- GitHub and Government: How agencies build software
- code.gov
- Federal Source Code and Open Source Toolkit
- Federal Source Code Policy (M-16-21)
- openCDC
- Digital Services Playbook
- CDC/ATSDR Policy on Public Health Research and Nonresearch Data Management and Access
- CDC/ATSDR Policy on Releasing and Sharing Data (old version, but still a useful reference)
- Clearance of Information Products Disseminated Outside CDC for Public Use
- Federal Source Code Toolkit