Project setup

While the specific setup for each 18F project varies widely, there are certain elements that should be present in all source code repositories. This document aims to detail those elements and suggest corresponding tools and resources.

Source code management

TTS projects use GitHub for source code management, with their repositories under a government-owned organization.

• GitHub Standard

Repository checklist

Below is an aspirational list of configuration and files for a source code repository. Not all of these elements will apply to every project (e.g. visual regression tests don't make sense for an API).

1. Community profile

   • LICENSE.md Standard

   • CONTRIBUTING.md Standard

   • README.md Default

2. .gitignore (though also consider a global config)

3. Programming language version specifications (e.g., .nvmrc, runtime.txt, Gemfile)

4. Dependency version descriptions (e.g., Gemfile, Pipfile, package.json) — don't forget to pin them

5. Build scripts

6. Unit test setup for each programming language

7. Linter setup (e.g., flake8, rubocop, eslint Suggestion )

8. Docker

   • Dockerfiles
   • Compose files
   • .dockerignore

9. cloud.gov/Cloud Foundry

   • Manifests, one per deployment environment (e.g., 18F/fec-cms, 18F/culper)
   • .cfignore (can be a symlink to .gitignore to get started)

10. Deploy scripts

11. Continuous Integration/Continuous Deployment

12. Code coverage metrics

13. Static analysis for code quality

14. Static security analysis

15. Accessibility scanning (e.g., Pa11y Default )

16. Integration test setup (e.g., Selenium Suggestion )

17. Visual regression setup (e.g., Backstop Suggestion )

18. Infrastructure as Code (e.g., Terraform Default )

Branch protection Requirement

Set up branch protection rules for each repository. It's a good practice to prevent mistakes like an accidental force-push to main.

We recommend at the very least enabling:

• Require pull request reviews before merging
• Restrict who can push to your main branch

Please refer to GitHub's branch protection documentation to help determine what other configuration settings are best for your project.

By default, protected branch rules do not apply to people with admin permissions to a repository, allowing admins to merge PRs without an external review when necessary.

Project management tool

Every project, no matter the size, should use a project management tool to keep track of ongoing tasks and to do items. The project management tool should be linked to somewhere in the project's GitHub repository so that others can find it easily.

Choose a tool that will work for you and your partner. Remember, they will be the ones using it once the engagement is over!

• GitHub Issues Default

• Trello Suggestion

• Jira Suggestion

Continuous Integration/Continuous Deployment

Developers don't always remember to run the test suite. That's why we have Continuous Integration services to run the tests automatically after each commit. CI also helps ensure there's nothing specific to the developer's machine that makes the tests pass.

A Continuous Deployment service allows a development team to receive rapid feedback on new features or bug fixes. CD also helps ensure deployment and infrastructure issues are identified earlier in a release process, and are scoped to a smaller number of changes.

Pick a CI/CD service with a GitHub integration so that the build status can be seen for each pull request.

• CircleCI Default

• GitHub Actions Suggestion

Code coverage metrics

Aim for more than 90% of your source code to be covered by tests; worry if coverage drops below 80%. For repositories with multiple programming languages/components (e.g., front and back ends), ensure that coverage reports are aggregated and reported on the entire project, in addition to reports on individual components.

• Code Climate Quality Suggestion

Static analysis for code quality

A good code review process is essential to writing good code. But certain code problems are difficult for humans to spot. Duplication, for example: if new code is an exact duplicate of code from an existing file in a project, that might not be caught in a code review. Static analysis tools catch duplication, security concerns, and more. Also see Static Security Analysis.

• CodeQL on GitHub (for security analysis) Default

• Code Climate Quality (for maintainability metrics) Suggestion

Dependency management

Applications require specific versions of programming languages, libraries, databases, services, and configuration to execute. A dependency management solution helps abstract that complexity and makes it easier for cross-functional teams to create consistent, reproducible, local development environments.

• Docker Suggestion
  See our Docker for Development recommendations.

Deployment infrastructure

Developers needing to deploy their code beyond their local environment should use either:

• a cloud.gov sandbox Standard

• an 18F-managed AWS sandbox account Standard

• or Federalist (for static web sites) Standard

Caution The use of tools such as localtunnel and ngrok, which make your locally running services visible to the internet, are not allowed because they present a large security concern. Consult 18F only, #infrastructure on Slack for any questions.

Infrastructure as Code

When developers are responsible for setting up or configuring infrastructure, it is best to record the steps or configuration as reproducible code.

A shell script is better than nothing and highly encouraged if infrastructure is simple. (Example).

Many cloud providers like Azure or AWS provide APIs for controlling their resources. Terraform Default is a wrapper over these APIs. You can write source-controlled configuration files (or even let Terraform generate them from existing deployments) and then use Terraform to create, modify, or delete resources. (Example). This is particularly handy when you need multiple environments (dev, staging, prod, etc) that differ only in small details.

Be aware that you might encounter difficulty in managing user roles and permissions with Terraform and cloud.gov. See this issue for context.

Caution As of 2023, Terraform is no longer open source. A fork, OpenTofu, exists, which is stewarded by the Linux Foundation. You are welcome to use OpenTofu if it works for you and your partner; it may eventually become the default at 18F.

Finally, although in many cases it is good to use containerized images, if it is necessary to do system configuration tasks on a physical server or a virtual machine, Ansible or Chef are tools to write down these tasks as playbooks or recipes and re-run them whenever needed.