Skip to content

Deployment

Jump to bottom
Dan Guy edited this page Sep 26, 2025 · 49 revisions

Repositories

Special Note: If the fecfile-validate repo was updated, the commit of the update needs to be updated in the requirements.txt file in the fecfile-web-api repo and the packages.json file in the fecfile-web-app repo, otherwise the CircleCI cache will not roll out the change.

Automatic deployment of branches

CircleCI will automatically deploy to environments based on changes to branches.

Environment Branch
DEV develop
STAGE release/sprint-xx
TEST release/test
PROD main

Create a feature branch

Using git-flow extensions: git flow feature start feature_branch

Without the git-flow extensions:

git checkout develop
git pull
git checkout -b feature/feature_branch develop
  • Developer creates a GitHub PR when ready to merge to develop branch
  • Reviewer reviews and merges feature branch into develop via GitHub
  • [auto] develop is deployed to DEV

Create a release branch

See Repositories for full list

  • Make sure all PRs for the given sprint are merged

  • Using git-flow extensions:

git checkout develop
git pull 
git flow release start sprint-#
git push --set-upstream origin release/sprint-#
  • Without the git-flow extensions:
git checkout develop
git pull
git checkout -b release/sprint-# develop
git push --set-upstream origin release/sprint-#
  • Developer creates two PRs per repository in GitHub to merge release/sprint-# branch into main and release/sprint-# into release/test branches to track if commits pass deployment checks. The actual merge will happen when deploying a release to TEST/PROD.
  • (optional) Tag reviewers on pull request(s)
  • Pushing the release branch triggers deploying to STAGE. Make sure deploys and end-to-end-tests pass (may need to re-run E2E).
  • Test logging in to STAGE environment (stage.fecfile.fec.gov)
  • Let the team know (and email QA team) that the release branch has been deployed to STAGE, ask developers to review their work there

Create and deploy a hotfix

  • Using git-flow extensions:
git flow hotfix start my-fix
# Work happens here
git flow hotfix finish my-fix
  • Without the git-flow extensions:
git checkout -b hotfix/my-fix main
# Work happens here
git push --set-upstream origin hotfix/my-fix
  • Developer creates a hotfix branch, commits changes, and makes a PR to the main and develop branches:
  • Reviewer merges hotfix/my-fix branch into develop
  • [auto] develop is deployed to DEV. Make sure the build passes before deploying to main.
  • Trigger rebuild of main without hotfix to ensure stable build.
  • If deploy to DEV is successful, reviewer merges hotfix/my-fix branch into main.

Deploying a release to TEST and PROD

See Repositories for full list.

First deploy to TEST:

  • Make sure reviewers have approved release/sprint-# -> release/test PRs in all repos (API/web app/proxy/validate)
  • Merge the release/sprint-# -> release/test fecfile-web-api PR and check CircleCI for passing tests and successful deploy before continuing
  • Merge the release/sprint-# -> release/test fecfile-web-app PR and check CircleCI for passing tests and successful deploy before continuing
  • Merge the release/sprint-# -> release/test fecfile-api-proxy PR and check CircleCI for passing tests and successful deploy before continuing
  • Merge the release/sprint-# -> release/test fecfile-validate PR and check CircleCI for passing tests
  • If commits were made to release/sprint-#:
    • Developer creates a PR in GitHub to merge release/sprint-# branch into the develop branch
    • Reviewer approves PR and merges into develop

Then deploy to PROD:

  • Make sure reviewers have approved release/sprint-# -> main PRs in all repos (API/web app/proxy/validate)
  • Merge the release/sprint-# -> main fecfile-web-api PR and check CircleCI for passing tests and successful deploy before continuing
  • Merge the release/sprint-# -> main fecfile-web-app PR and check CircleCI for passing tests and successful deploy before continuing
  • Merge the release/sprint-# -> main fecfile-api-proxy PR and check CircleCI for passing tests and successful deploy before continuing
  • Merge the release/sprint-# -> main fecfile-validate PR and check CircleCI for passing tests
  • Delete release/sprint-# branches prior to the current release/sprint-# branch, if they exist
  • Publish a new release using tag sprint-#, be sure to Auto-generate release notes
    • On Github, click on "Code" tab, then the "tags" link, then the "Releases" toggle
    • Click the button "Draft a new release"
    • Enter the new sprint tag "sprint-XX"
    • Set Target option to "main"
    • Set Release title to "sprint-XX"
    • Click the button "Generate release notes"
    • Click the "Publish release" button

Manually deploying out of band

(e.g. deploying test branches to DEV)

Communicate with the entire team that you will be utilizing the environment for a test release. Ensure that no one else is using that environment for a more critical purpose.

Be careful not to deploy changes ahead of their release - when targeting develop, branch off develop. When targeting release, branch off latest release branch. Make sure to get a fresh pull of whichever branch you fork.

In order to deploy a non-standard branch to an enviroment you must alter the deployment logic within your branch. Where to find and alter that deployment logic varies between apps:

  • fecfile-web-api and fecfile-web-app
    • update tasks.py DEPLOY_RULES to change intended environment to use the desired branch
    • update .circleci/config.yml deploy-job filters > branches > only to include the desired branch
  • fecfile-api-proxy
    • bin/cf_deploy.sh change branch logic
Clone this wiki locally