Skip to content

[No QA] Update README with new deployment documentation #3407

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
roryabraham merged 2 commits into from
Jun 7, 2021
Merged

[No QA] Update README with new deployment documentation #3407

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
76b15fb
Update README with new deployment documentation
roryabraham Jun 7, 2021
1c74d61
Add stuff for lockDeploys and finishReleaseCycle
roryabraham Jun 7, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 34 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -237,19 +237,43 @@ This application is built with the following principles.
----

# Deploying
## Continuous deployment / GitHub workflows
Every PR merged into `main` will kick off the **Create a new version** GitHub workflow defined in `.github/workflows/version.yml`.
It will look at the current version and increment it by one build version (using [`react-native-version`](https://www.npmjs.com/package/react-native-version)), create a PR with that new version, and tag the version.
## QA and deploy cycles
We utilize a CI/CD deployment system built using [GitHub Actions](https://github.com/features/actions) to ensure that new code is automatically deployed to our users as fast as possible. As part of this process, all code is first deployed to our staging environments, where it undergoes quality assurance (QA) testing before it is deployed to production. Typically, pull requests are deployed to staging immediately after they are merged.

The PR will be merged automatically by the GitHub workflow **automerge** to keep the version always up to date.
Every time a PR is deployed to staging, it is added to a [special tracking issue](https://github.com/Expensify/Expensify.cash/issues?q=is%3Aopen+is%3Aissue+label%3AStagingDeployCash) with the label `StagingDeployCash` (there will only ever be one open at a time). This tracking issue contains information about the new application version, a list of recently deployed pull requests, and any issues found on staging that are not present on production. Every weekday at 9am PST, our QA team adds the `🔐LockCashDeploys🔐` label to that tracking issue, and that signifies that they are starting their daily QA cycle. They will perform both regular regression testing and the QA steps listed for every pull request on the `StagingDeployCash` checklist.

When a new tag is pushed, it will trigger a deploy of all four clients:
1. The **web** app automatically deploys via a GitHub Action in `.github/workflows/main.yml`
2. The **MacOS desktop** app automatically deploys via a GitHub Action in `.github/workflows/desktop.yml`
3. The **Android** app automatically deploys via a GitHub Action in `.github/workflows/android.yml`
4. The **iOS** app automatically deploys via a GitHub Action in `.github/workflows/ios.yml`
Once the `StagingDeployCash` is locked, we won't run any staging deploys until it is either unlocked, or we run a production deploy. If severe issues are found on staging that are not present on production, a new issue (or the PR that caused the issue) will be labeled with `DeployBlockerCash`, and added to the `StagingDeployCash` deploy checklist. If we want to resolve a deploy blocker by reverting a pull request or deploying a hotfix directly to the staging environment, we can merge a pull request with the `CP Staging` label.

## Local production build
Once we have confirmed to the best of our ability that there are no deploy-blocking issues and that all our new features are working as expected on staging, we'll close the `StagingDeployCash`. That will automatically trigger a production deployment, open a new `StagingDeployCash` checklist, and deploy to staging any pull requests that were merged while the previous checklist was locked.

## Key GitHub workflows
These are some of the most central [GitHub Workflows](https://github.com/Expensify/Expensify.cash/tree/main/.github/workflows). There is more detailed information in the README [here](https://github.com/Expensify/Expensify.cash/blob/main/.github/workflows/README.md).

### preDeploy
The [preDeploy workflow](https://github.com/Expensify/Expensify.cash/blob/main/.github/workflows/preDeploy.yml) executes whenever a pull request is merged to `main`, and at a high level does the following:

- If the `StagingDeployCash` is locked, comment on the merged PR that it will be deployed later.
- Otherwise:
- Create a new version by triggering the [`createNewVersion` workflow](https://github.com/Expensify/Expensify.cash/blob/main/.github/workflows/createNewVersion.yml)
- Use the [`updateProtectedBranch` workflow](https://github.com/Expensify/Expensify.cash/blob/main/.github/workflows/updateProtectedBranch.yml) to update the `staging` branch.
- Also, if the pull request has the `CP Staging` label, it will execute the [`cherryPick` workflow](https://github.com/Expensify/Expensify.cash/blob/main/.github/workflows/cherryPick.yml) to deploy the pull request directly to staging, even if the `StagingDeployCash` is locked

### deploy
The [`deploy` workflow](https://github.com/Expensify/Expensify.cash/blob/main/.github/workflows/deploy.yml) is really quite simple. It runs when code is pushed to the `staging` or `production` branches, and:

- If `staging` was updated, it creates a tag matching the new version, and pushes tags.
- If `production` was updated, it creates a GitHub Release for the new version

### platformDeploy
The [`platformDeploy` workflow](https://github.com/Expensify/Expensify.cash/blob/main/.github/workflows/platformDeploy.yml) is what actually runs the deployment on all four platforms (iOS, Android, Web, macOS Desktop). It runs a staging deploy whenever a new tag is pushed to GitHub, and runs a production deploy whenever a new release is created.

### lockDeploys
The [`lockDeploys` workflow](https://github.com/Expensify/Expensify.cash/blob/main/.github/workflows/lockDeploys.yml) executes when the `StagingDeployCash` is locked, and it prepares the staging branch for a production release by creating a new `PATCH` version (i.e: `1.0.57-5` -> `1.0.58.0`).

### finishReleaseCycle
The [`finishReleaseCycle` workflow](https://github.com/Expensify/Expensify.cash/blob/main/.github/workflows/finishReleaseCycle.yml) executes when the `StagingDeployCash` is closed. It updates the `production` branch from `staging` (triggering a production deploy), deploys `main` to staging, and creates a new `StagingDeployCash` deploy checklist.

## Local production builds
Sometimes it might be beneficial to generate a local production version instead of testing on production. Follow the steps below for each client:

#### Local production build of the web app
Expand Down