plugin-github

GitHub integration plugin

The @preevy/plugin-github plugin adds GitHub integration to Preevy.

This plugin is bundled with Preevy and enabled by default. To disable it, see below.

GitHub PR comment for your environment

Automatic PR comment at up and down

Comment generation is done as part of the up and down core commands.

Preevy will post the comment if a GitHub PR and a GitHub token are detected in the context (e.g, when running in a GitHub Action or other supported CI provider) or specified explicitly. See the Configuration section for details.

Manual PR 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.

GitHub Docker build cache

Specify --github-add-build-cache at the up command to add GitHub cache to your build directives.

This will add the following directives to all services with a build section:

  cache_to: type=gha,scope=<project>/<service>,mode=max
  cache_from: type=gha,scope=<project>/<service>

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/<number>)	--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
• GitLab Actions
• Circle CI
• Travis CI
• Azure Pipelines

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:

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:

Command	Flag	Description
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

PR 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 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: an array of { service: string; port: number; url: string; project: string }

Here is an example of a configuration file containing a customized template:

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.