.github/workflows/README.md
# Github Actions <> Zeit integrations
> Automated actions configured through GitHub Actions
>
> This documentation explains how our GitHub actions integrate themselves with the Zeit platform
---
## Getting started
### Introducing GitHub Actions
> Stuff to read if you're not familiar with GitHub Actions
[Official documentation](https://help.github.com/en/actions/automating-your-workflow-with-github-actions)
Most useful documentation links:
- [https://help.github.com/en/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#about-yaml-syntax-for-workflows](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#about-yaml-syntax-for-workflows)
- [https://help.github.com/en/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#on](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#on)
- [https://help.github.com/en/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idneeds](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idneeds)
- [https://help.github.com/en/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idruns-on](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idruns-on)
- [https://help.github.com/en/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet)
### Requirements
> List of necessary requirements for the `Github Actions <> Zeit` to work properly.
#### Required GitHub secrets:
> Those secrets must be added on Github settings page, such as https://github.com/UnlyEd/next-right-now/settings/secrets
- `GITHUB_CI_PR_COMMENT`: Allows to post comments on GitHub Pull Request - See [https://github.com/settings/tokens](https://github.com/settings/tokens)
GitHub **["personal access token"](https://github.com/settings/tokens)** from your personal account with the following permission scopes:
- `repo` (all)
- `user`
- `read:user`
- `user:email`
- `workflow`
- `ZEIT_TOKEN`: Allows to trigger deployments - See [https://zeit.co/account/tokens](https://zeit.co/account/tokens)
Zeit personal token
---
## Overview
### Stages
> We use two different stages. Each stage is meant to use a different configuration.
_**staging**_ (see [`deploy-zeit-staging`](./deploy-zeit-staging.yml)):
Every pushed commit, (except those made on `master`) automatically starts a new Zeit deployment, using the related staging configuration file.
You can choose which client you deploy by changing the symbolic link `now.json` file.
_**production**_ (see [`deploy-zeit-production`](./deploy-zeit-production.yml)):
Commits pushed to the `master` branch will automatically deploy the `now-production.json` configuration.
> N.B: Those events are triggered by pushed commit, but also merged branches.
### GitHub Actions Jobs workflow
> The same workflow is used for both stages. The main difference is the trigger.
>
> A `production` deployment is **triggered by any change** in the `master` branch,
> while a `staging` deployment is **triggered by any change that is not on** the `master` branch.
**Jobs workflow:**
* Installing Node.js and npm dependencies, by specifying Node version
* Deploy code:
* We checkout to the last branch commit, documentation [here](https://github.com/cypress-io/github-action)
* Run 2e2 tests:
* We need to checkout again (because the code is not persistent)
* We ask to Zeit api for the last deployment data, retrieve the url and then set it as environment variable as `ZEIT_DEPLOYMENT_URL` (to be able to use it afterwards)
* We use default action provided by cypress (documentation [here](https://github.com/cypress-io/github-action)):
* _**wait-on**_: Allows us to wait before starting tests. It ping the endpoint until it's up, with a timeout of 60 seconds per default.
* _**config-file**_: We need to specify a config file because cypress is looking for cypress.json in the main folder.
The config file itself doesn't matter because we will override most settings anyway. We just need `projectId` to run the tests.
* _**config**_: Overrides some default config, like the `baseUrl` in particular (we use the `ZEIT_DEPLOYMENT_URL` instead)
* We upload artifacts on tests failure, more documentation [here](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/persisting-workflow-data-using-artifacts)
---
## Dependencies
### Actions
* _**[actions/setup-node@v1](https://github.com/actions/setup-node)**_:
Setup node.js and install dependencies
* _**[actions/checkout@v1](https://github.com/cypress-io/github-action)**_:
Checkout to last commit to retrieve code
* _**[cypress-io/github-action@v1](https://github.com/cypress-io/github-action)**_:
Run Cypress tests
* _**[actions/upload-artifact@v1](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/persisting-workflow-data-using-artifacts)**_:
Upload artifacts to Github
---
## Complex commands
* _**[jq](https://cameronnokes.com/blog/working-with-json-in-bash-using-jq/)**_:
JSON parser for bash
* _**[tr](http://linuxcommand.org/lc3_man_pages/tr1.html)**_:
Bash editor, used to remove characters
* _**[echo "::set-env name=key::value"](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/development-tools-for-github-actions)**_:
Set env variable for all others jobs