# suiteAppDeployPrInstance

This step builds and deploys a frontend suite app as a PRI (PR instance) in the QA environment.

## Parameters

| Name                 | Description                                        | Type      | Default         | Required |
| -------------------- | -------------------------------------------------- | --------- | --------------- | -------- |
| appName              | The name of the application. eg. frontend-settings | `String`  | n/a             | yes      |
| envVars              | Map of environment variables                       | `Map`     | null            | no       |
| scriptNames          | List of scripts to run as the build step | `List<String>` | When omitted, defaults to `["frontend build --public-path <CDN_URL>/<appName>/prs/<pullRequestId>/"]`, prepended with `frontend i18n:download` if `POEDITOR_PROJECT_ID` is set in `envVars`. When provided, scripts are used as-is with no side effects. | no |
| pullRequestId        | Id of pull request                                 | `String`  | `env.CHANGE_ID` | no       |
| detectPackageManager | Auto-detect package manager from package.json      | `Boolean` | false           | no       |

## Usage

The step is requires a `appName` property which is usually the same as the name of the github repository. It determines where the bundles are deployed to on the CDN and the url where the application is served from. `https://[appName]-[pullRequestId].pullrequests.qaorch.com`

The `pullRequestId` is automatically picked up when the pipeline runs against a PR branch.

**Note. To access the PR-Instance url, you need to be connected to the VPN.**

### Providing environment variables

Since our suite applications use Auth0 for authentication, you would want to add the `AUTH0_CLIENT_ID` env variable.

```groovy
suiteAppDeployPrInstance (
    appName: '-- app name --',
    envVars: [
        AUTH0_CLIENT_ID: '-- qa client id --',
        // any other environment variables you want to include e.g SENTRY_DSN
    ]
)
```

### Using a custom build script

By default, the step runs `frontend build --public-path <cdnUrl>/<appName>/prs/<pullRequestId>/`. You can override this by passing a `scriptNames` list. When `scriptNames` is provided, scripts are used as-is — the `frontend i18n:download` step is not prepended even if `POEDITOR_PROJECT_ID` is set.

The `PUBLIC_PATH` environment variable is injected automatically and can be read via `process.env.PUBLIC_PATH`. It can be overridden by passing it in `envVars`.

```groovy
suiteAppDeployPrInstance(
    appName: '-- app name --',
    envVars: [
        AUTH0_CLIENT_ID: '-- qa client id --',
    ],
    scriptNames: ['build:pri'],
)
```

### Specifying the pull request id

Use the `pullRequestId` parameter if you want to override the value of `env.CHANGE_ID` or if you are running this in a non PR branch.

```groovy
suiteAppDeployPrInstance (
    appName: '-- app name --',
    pullRequestId: '1234',
    envVars: [
        AUTH0_CLIENT_ID: '-- qa client id --',
        // any other environment variables you want to include e.g SENTRY_DSN
    ]
)
```

### Deploy on demand

The recommended way to deploy PR-instances is to trigger it by a PR comment.
This reduces load on jenkins and resources spent.

The example below will trigger the PR-Instance deployment when a user adds a comment with the text: "deploy pri". Note that the tests stage will not run, so it does not potentially block the deployment.

```groovy
pipeline {
    ...

    triggers {
        issueCommentTrigger('.*retest this please.*|.*deploy pri.*')
    }

    stages {
        ...
        stage('Unit Tests and Style Checks') {
            when {
                not {
                    environment name: 'GITHUB_COMMENT', value: 'deploy pri'
                }
            }
            steps {
                yarnRun(scriptNames: ['test'])
            }
        }
        stage('Deploy to PR Instance') {
            when {
                environment name: 'GITHUB_COMMENT', value: 'deploy pri'
            }
            steps {
                suiteAppDeployPrInstance (
                    appName: '-- app name --',
                    envVars: [
                        AUTH0_CLIENT_ID: '-- qa client id --'
                    ]
                )
            }
        }
        ...
    }
}
```

### Using auto-detected package manager

By default, this step uses `yarn`. If your project uses `npm` or `pnpm`, you can enable auto-detection by setting `detectPackageManager: true`.
The step will read the `packageManager` field from your `package.json` and use the appropriate package manager.

```groovy
suiteAppDeployPrInstance (
    appName: '-- app name --',
    detectPackageManager: true,
    envVars: [
        AUTH0_CLIENT_ID: '-- qa client id --'
    ]
)
```

To set the `packageManager` field in your `package.json`:

```json
{
  "name": "my-app",
  "packageManager": "npm@10.0.0"
}
```

If the `packageManager` field is missing or contains an unsupported package manager, the step will default to `yarn` for backward compatibility.
See [packageManagerRun](./packageManagerRun.md) for more details on package manager auto-detection.