diff --git a/site/docs/integrations/demo.png b/site/docs/integrations/demo.png new file mode 100644 index 00000000..74a476b4 Binary files /dev/null and b/site/docs/integrations/demo.png differ diff --git a/site/docs/integrations/github-plugin.md b/site/docs/integrations/github-plugin.md new file mode 100644 index 00000000..a404cda4 --- /dev/null +++ b/site/docs/integrations/github-plugin.md @@ -0,0 +1,161 @@ +--- +title: Preevy PR Plugin +--- + +# Preevy PR Plugin + +The `@preevy/plugin-github` plugin adds GitHub integration to [Preevy](https://github.com/livecycle/preevy). + +This plugin is bundled with Preevy and enabled by default. To disable it, see [below](#disabling-the-plugin). + +## GitHub PR comment for your environment + +![Demo comment](./demo.png) + +### Automatic comment at `up` and `down` + +Comment generation is done as part of the `up` and `down` core commands. + +If a GitHub context is detected (e.g, when running in a GitHub actions job), it will post the comment automatically. + +### Manual comment using the `github` commands + +This plugin adds the following commands: + +`github pr comment`: Creates a GitHub PR comment for an existing Preevy environment. If the comment exists, it is updated with the current set of URLs. + +`github pr uncomment`: Updates the GitHub PR comment to state that the Preevy environment has been deleted. + +Run `preevy github pr comment --help` for details. + +## Configuration + +At runtime, the plugin will attempt to detect the configuration it needs from environment variables and the git context. Options can be overridden using CLI flags and the Docker Compose file. + +| | Environment variable | Flag | Config section | Other sources | +|---|------|------|-----|----| +| GitHub token | `GITHUB_TOKEN` | `--github-token` | `token` | +| Repo (owner/reponame) | `GITHUB_REPOSITORY` | `--github-repo` | `repo` | git context (if `detect` is not `false`) | +| PR number | `GITHUB_REF` (format: `refs/pull/`) | `--github-pull-request` | `pullRequest` | | +| Comment template | | `--github-pr-comment-template-file` | `commentTemplate` | | + +### Configuration from the CI provider context + +The plugin can automatically detect its configuration when running in a CI provider supported by `@preevy/core`: + +* [GitHub Actions](../core/src/ci-providers/github-actions.ts) +* [GitLab Actions](../core/src/ci-providers/gitlab.ts) +* [Circle CI](../core/src/ci-providers/circle.ts) +* [Travis CI](../core/src/ci-providers/travis.ts) +* [Azure Pipelines](../core/src/ci-providers/azure-pipelines.ts) + +To disable auto-detection, specify `detect: false` at the plugin configuration in the Docker Compose file. + +### Configuration from the Docker Compose file + +Add the plugin to the `plugins` section of the `x-preevy` element in your Docker Compose file: + +```yaml +services: + ... +x-preevy: + plugins: + - module: '@preevy/plugin-github' + # detect: false + # disabled: true + # commentTemplate: see below + # pullRequest: PR number + # token: GitHub token + # repo: GitHub repo (owner/reponame) +``` + +### Configuration from CLI flags + +The following flags can be specified at the Preevy CLI: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandFlagDescription
up, down--github-token=<token>GitHub token
--github-repo=<owner>/<repo>GitHub repository
--github-pull-request=<number>GitHub PR number
--github-comment-template-file=<path>Path to a nunjucks comment template
--github-pr-comment-enabled=<auto|no|always>Whether to enable posting/updating a comment on the GitHub PR
github pr comment, github pr uncomment--token=<token>GitHub token
--repo=<owner>/<repo>GitHub repository
--pull-request=<number>GitHub PR number
--comment-template-file=<path>Path to a nunjucks comment template
+ +### Comment template + +The generated PR comment can be customized by specifying a template in your Docker Compose file, or in a separate file (see above). The template is rendered by [`nunjucks`](https://mozilla.github.io/nunjucks/templating.html) and receives a context containing a `urls` property which is one of the following: + +* `undefined`: The environment is being deleted, or the `uncomment` command has been invoked. +* Otherwise, the result of the [preevy `urls` command](../cli/README.md#preevy-urls-service-port): an array of `{ service: string; port: number; url: string; project: string }` + +Here is an example of a configuration file containing a customized template: + +```yaml +x-preevy: + plugins: + - module: '@preevy/plugin-github' + commentTemplate: | + {% if urls %}[Preevy](https://preevy.dev) has created a preview environment for this PR. + + Here is how to access it: + + | Service | Port | URL | + |---------|------|-----| + {% for url in urls %}| {{ url.service }} | {{ url.port }} | {{ url.url }} | + {% endfor %} + {% else %}The [Preevy](https://preevy.dev) preview environment for this PR has been deleted. + {% endif %} +``` + +## Disabling the plugin + +### Disabling the plugin completely (will remove all the GitHub integration) + +Any of the following will disable the plugin: + +- Specify `disabled: true` at the plugin configuration in the Docker Compose file +- Set the `PREEVY_DISABLE_PLUGINS` environment variable to `@preevy/plugin-github`. If multiple plugins need to be disabled, specify a comma-separated list of modules. +- Add the flag `--disable-plugin=@preevy/plugin-github` + +### Disabling the GitHub PR comment + +Automatic commenting on the GitHub PR can be disabled by, setting the environment variable `PREEVY_GITHUB_PR_COMMENT_ENABLED=0` or specifying the flag `--github-pr-comment-enabled=no` at the `up` and `down` commands. +