GitHub Best Practices

The Office of Digital Services (ODS) at California Department of Technology (CDT) recommends the following practices

Best practices for GitHub Repos (Best practices for repositories – GitHub Docs)

  1. Create a README file to make it easier for people to understand and navigate your work.
  2. Regular collaborators should favor branching over forking, creating pull requests between branches instead of between repositories.
        • Use GitHub branch protection rules to protect important branches, such as “main”, with required status checks and pull request reviews.
        • Prevent direct commits to the “main” branch.
  3. GitHub repositories should be limited to the files necessary for building projects. Avoid committing large binary files, such as build artifacts.
        • Binary files like spreadsheets and presentations are better suited to be tracked on portals that understand how to serve and version them properly.
  4. Use Git Large File Storage (Git LFS) to track large files in a Git repository to optimize performance.
  5. It is important to use a well thought-out and secure Git workflow for team collaboration.
  6. Keep sensitive files out of your repository with “.gitignore”.
  7. Use a CODEOWNERS file to define individuals or teams that are responsible for code in a repository
  8. Configure automated security checks in a repository.
        • Automated dependency alerts (free for all repo types).
        • Automated dependency updates with Dependabot (free for all repo types).
        • Automated code scanning (free only for public repos).
        • Automated secret scanning (free only for public repos).
  9. For open-source projects, setup contributing guidelines to help collaborators make meaningful, useful contributions to a project
        • Add common files: README.md, LICENSE.md, CONTRIBUTING.md, and SECURITY.md
  10. Training resources:

Best practices for GitHub Actions (Security hardening for GitHub Actions – GitHub Docs)

  1. Using CODEOWNERS to monitor and restrict changes to workflow files.
  2. Take the following steps to ensure secrets are redacted, and limit other risks associated with secrets.
        • Never use structured data (JSON, XML, or YAML) as a secret; this significantly reduces the probability the secrets will be properly redacted.
        • Register all secrets used within workflows; a secret generated from another sensitive value within the workflow will not be redacted in the logs unless you register it.
        • Audit how secrets are handled. For example, check that they’re not sent to unintended hosts, or explicitly being printed to log output.
        • Use credentials that are minimally scoped.
        • Audit and rotate registered secrets.
        • Consider requiring review for access to secrets.
  3. Mitigate script injection attacks ( Security hardening for GitHub Actions – GitHub Docs ).
    Prevent your workflow code from executing untrusted input from attackers.
        • Using an action instead of an inline script.
        • Using an intermediate environment variable.
        • Using starter workflows for code scanning.
        • Restricting permissions for GITHUB_TOKEN.
  1. Using OpenID Connect to access cloud resources.
  2. Mitigate the risks associated with third-party actions.
        • Pin third-party actions to a full length commit SHA.
        • Audit the source code of the action.
        • Pin actions to a tag only if you trust the creator.
  3. Keep GitHub Actions up to date.
  4. Hardening self-hosted runners
        • Self-hosted runners should almost never be used for public repositories on GitHub because any user can open pull requests against the repository and compromise the environment.
  5. Preventing GitHub Actions from creating or approving pull requests.

Best practices for GitHub Organizations (Best practices for organizations – GitHub Docs)

  1. Assign multiple owners
        • The organization’s projects can become inaccessible if the owner is unreachable.
        • At least two people within each organization should have the owner role; keep in mind that organization owners have full administrative access to the organization.
  2. Use teams
        • Use teams to facilitate collaboration and enhance communication in your organization.
        • Keep teams visible whenever possible and reserve secret teams for sensitive situations.
        • Use nested teams.
        • Assign permissions to teams rather than individuals.
  3. Consider using SAML single sign-on (SSO) authentication If you have mostly private repos in your organization ( Managing SAML single sign-on for your organization – GitHub Enterprise Cloud Docs ).
        • Increases security and centralizes identity and access for the web applications that your team uses; It is way to control and secure access to organization resources like repositories, issues, and pull requests.
        • Members of your organization will continue to sign into their personal accounts on GitHub.com, but will be redirected to authenticate with you Identity Provider (IdP).
  4. Enforce Two-factor Authentication for all GitHub accounts accessing to your organization.
  5. Enable GitHub security tools by default for all repositories ( GitHub security features – GitHub Docs )
        • Dependabot
        • Code scanning
        • Secret scanning
  6. Periodically review access controls and have a process in place for revoking access when someone no longer needs it.
  7. Set the default permissions granted to GITHUB_TOKEN to restricted ( Disabling or limiting GitHub Actions for your organization – GitHub Docs )

 

Best practices for GitHub Enterprises (Best practices for enterprises – GitHub Enterprise Cloud Docs)

  1. Use policies (About enterprise policies)
        • Use policies to enforce business rules and regulatory compliance.
  2. Minimize the number of organizations.
        • A smaller number of organizations encourages innersource practices and allows discussions to involve a wider audience.
        • You can manage repository access and security requirements at a more granular level within each organization by using teams.
  3. Avoid extensive collaboration in user-owned repositories.
        • Organization-owned repositories have more sophisticated security and administrative features, and they remain accessible even as enterprise membership changes.
  4. Use human-readable usernames.
        • If you control the usernames for enterprise members, avoid machine-generated IDs that are difficult for humans to read.
  5. Enforce Two-factor Authentication for all GitHub accounts accessing your GitHub Enterprise.