UnlyEd/next-right-now-admin

# 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