Skip to content

Latest commit

 

History

History
233 lines (180 loc) · 14.9 KB

DEPLOY.md

File metadata and controls

233 lines (180 loc) · 14.9 KB
Raw

Deployment

These deployment procedures mainly concern the Cypress binary and cypress npm module.

Independent @cypress/ packages that live inside the npm directory are automatically published to npm (with semantic-release) upon being merged into master. You can read more about this in CONTRIBUTING.md

Anyone can build the binary and npm package, but you can only deploy the Cypress application and publish the npm module cypress if you are a member of the cypress npm organization.

ℹ️ See the publishing section for how to build, test and publish a new official version of the binary and cypress npm package.

Building Locally

Building the npm package

⚠️ Note: The steps in this section are automated in CI, and you should not need to do them yourself when publishing.

Building a new npm package is very quick.

  • Increment the version in the root package.json
  • yarn build --scope cypress

The steps above:

  • Build the cypress npm package
  • Transpile the code into ES5 to be compatible with the common Node versions
  • Put the result into the cli/build folder.

Building the binary

⚠️ Note: The steps in this section are automated in CI, and you should not need to do them yourself when publishing.

The npm package requires a corresponding binary of the same version. In production, it will try to retrieve the binary from the Cypress CDN if it is not cached locally.

You can build the Cypress binary locally by running yarn binary-build. You can use Linux to build the Cypress binary (just like it is in CI) by running yarn binary-build inside of yarn docker.

yarn binary-zip can be used to zip the built binary together.

Publishing

Prerequisites

  • Ensure you have the following permissions set up:

    • An AWS account with permission to create AWS access keys for the Cypress CDN.
    • Permissions for your npm account to publish the cypress package.
    • Permissions to update releases in ZenHub.

  • Set up the following environment variables:

    • Cypress AWS access key and secret in aws_credentials_json, which looks like this: 
      aws_credentials_json={"bucket":"cdn.cypress.io","folder":"desktop","key":"...","secret":"..."}
    • A GitHub token, a CircleCI token, and a cypress-io account-specific AppVeyor token in ci_json: 
      ci_json={"githubToken":"...","circleToken":"...","appVeyorToken":"..."}
    • You'll also need to put the GitHub token under its own variable and get a ZenHub API token for the release-automations step. 
      GITHUB_TOKEN="..."
ZENHUB_API_TOKEN="..."
    • The cypress-bot GitHub app credentials are also needed. Ask another team member who has done a deploy for those.
    • For purging the Cloudflare cache (part of the move-binaries step), you'll need CF_ZONEID and CF_TOKEN set. These can be found in 1Password. If you don't have access, ask a team member who has done a deploy. 
       CF_ZONEID="..."
 CF_TOKEN="..."
    • Tip: Use as-a to manage environment variables for different situations.

Before Publishing a New Version

In order to publish a new cypress package to the npm registry, we must build and test it across multiple platforms and test projects. This makes publishing directly into the npm registry impossible. Instead, we have CI set up to do the following on every commit to develop:

  1. Build the npm package with the new target version baked in.
  2. Build the Linux/Mac binaries on CircleCI and build Windows on AppVeyor.
  3. Upload the binaries and the new npm package to cdn.cypress.io under the "beta" folder.
  4. Launch the test projects like cypress-test-node-versions and cypress-test-example-repos using the newly-uploaded package & binary instead of installing from the npm registry. That installation looks like this: 
    export CYPRESS_INSTALL_BINARY=https://cdn.../binary/<new version>/<commit hash>/cypress.zip
npm i https://cdn.../npm/<new version>/<commit hash>/cypress.tgz

Multiple test projects are launched for each target operating system and the results are reported back to GitHub using status checks so that you can see if a change has broken real-world usage of Cypress. You can see the progress of the test projects by opening the status checks on GitHub:

Screenshot of status checks

Once the develop branch for all test projects are reliably passing with the new changes, publishing can proceed.

Steps to Publish a New Version

In the following instructions, "X.Y.Z" is used to denote the version of Cypress being published.

  1. develop should contain all of the changes made in master. However, this occasionally may not be the case. Ensure that master does not have any additional commits that are not on develop and all auto-generated pull requests designed to merge master into develop have been successfully merged.

  2. If there is a new cypress-example-kitchensink version, update the corresponding dependency in packages/example to that new version.

  3. Use the move-binaries script to move the binaries for <commit sha> from beta to the desktop folder for <new target version>. This also purges the cloudflare cache for this version.

    yarn move-binaries --sha <commit sha> --version <new target version>

  4. Publish the new npm package under the dev tag, using your personal npm account.

    • To find the link to the package file cypress.tgz:
      1. In GitHub, go to the latest commit (the one whose sha you used in the last step). commit-link
      2. Scroll down past the changes to the comments. The first comment should be a cypress-bot comment that includes a line beginning npm install .... Grab the https://cdn.../npm/X.Y.Z/<long sha>/cypress.tgz link. cdn-tgz-link
    • Publish to the npm registry straight from the URL: 
      npm publish https://cdn.../npm/X.Y.Z/<long sha>/cypress.tgz --tag dev

  5. Double-check that the new version has been published under the dev tag using npm info cypress or available-versions. latest should still point to the previous version. Example output:

    dist-tags:
dev: 3.4.0     latest: 3.3.2

  6. Test cypress@X.Y.Z to make sure everything is working.

    • Install the new version: npm install -g cypress@X.Y.Z
    • Run a quick, manual smoke test:
      • cypress open
      • Go into a project, run a quick test, make sure things look right
    • Optionally, do more thorough tests:
      • Trigger test projects from the command line (if you have the appropriate permissions)
      node scripts/test-other-projects.js --npm cypress@X.Y.Z --binary X.Y.Z
      • Test the new version of Cypress against the Cypress dashboard repo.

  7. Confirm that every issue labeled stage: pending release has a ZenHub release set. Tip: there is a command in release-automations's issues-in-release tool to list and check such issues. Without a ZenHub release issues will not be included in the right changelog.

  8. Deploy the release-specific documentation and changelog in cypress-documentation.

    • If there is not already a release-specific PR open, create one. You can use release-automations's issues-in-release tool to generate a starting point for the changelog, based off of ZenHub: 
      cd packages/issues-in-release
yarn do:changelog --release <release label>
    • Ensure the changelog is up-to-date and has the correct date.
    • Merge any release-specific documentation changes into the main release PR.
    • You can view the doc's branch deploy preview by clicking 'Details' on the PR's netlify-cypress-docs/deploy-preview GitHub status check.
    • Merge this PR into master to deploy it to production.

  9. Make the new npm version the "latest" version by updating the dist-tag latest to point to the new version:

    npm dist-tag add cypress@X.Y.Z

  10. Run binary-release to update the download server's manifest. This will also ensure the binary for the version is downloadable for each system.

    yarn binary-release --version X.Y.Z

  11. If needed, push out any updated changes to the links manifest to on.cypress.io.

  12. If needed, deploy the updated cypress-example-kitchensink to example.cypress.io by following these instructions under "Deployment".

  13. Update the releases in ZenHub:

    • Close the current release in ZenHub.
    • Create a new patch release (and a new minor release, if this is a minor release) in ZenHub, and schedule them both to be completed 2 weeks from the current date.
    • Move all issues that are still open from the current release to the appropriate future release.

  14. Bump version in package.json, commit it to develop, tag it with the version, and push the tag up:

    git commit -am "release X.Y.Z [skip ci]"
git log --pretty=oneline
# copy sha of the previous commit
git tag -a vX.Y.Z <sha>
git push origin vX.Y.Z

  15. Merge develop into master and push both branches up. Note: pushing to master will automatically publish any independent npm packages that have not yet been published.

    git push origin develop
git checkout master
git merge develop
git push origin master

  16. Inside of cypress-io/release-automations:

    • Publish GitHub release to cypress-io/cypress/releases using package set-releases: 
      cd packages/set-releases && npm run release-log -- --version X.Y.Z
    • Add a comment to each GH issue that has been resolved with the new published version using package issues-in-release: 
      cd packages/issues-in-release && npm run do:comment -- --release X.Y.Z
    • Confirm there are no issues with the label stage: pending release left

  17. Publish a new docker image in cypress-docker-images under included for the new cypress version. Note: we use the base image with the Node version matching the bundled Node version.

  18. Update example projects to the new version. For most projects, you can go to the Renovate dependency issue and check the box next to Update dependency cypress to X.Y.Z. It will automatically create a PR. Once it passes, you can merge it. Try updating at least the following projects:

  19. Check if any test or example repositories have a branch for testing the features or fixes from the newly published version x.y.z. The branch should also be named x.y.z. Check all cypress-test-* and cypress-example-* repositories, and if there is a branch named x.y.z, merge it into master.

    Test Repos

    Example Repos

Take a break, you deserve it! 😎