Skip to content

Latest commit

 

History

History
126 lines (96 loc) · 14.4 KB

open_practices.md

File metadata and controls

126 lines (96 loc) · 14.4 KB

CDC GitHub Practices for Open Source Projects

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.

Getting Started

Before you can publish your project, you must request access to be added to the CDCgov organization. Complete these steps:

  1. Review the Rules of Behavior.
  2. Confirm your Github profile is setup properly.
  3. 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.

Required Practices

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.
  • Create a README. Add a README.md file at the root with the following:
  • 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.
  • 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.md file to let users know and archive the repository.

Recommended Practices

Optional improvements to make your open source project more successful.

Guidance

Support and Feedback

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 [email protected]. We also accept pull requests if you want to directly edit the guidance.

Non-Compliance Procedure

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.

Profile Setup

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.

Open Source Checklist

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.

This checklist was adapted from the CDC IT Guard Rail and put here to help people who don't have access to the intranet.

CDC Enterprise

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.

Reference Links

These are helpful links from across the Federal Government regarding open sourcing code.