Merge pull request #13 from getsentry/feat/sentry-release-var

Adds sentryRelease and releasePrefix parameters. Modify README.md

Author: jonesphillip

README.md

@@ -12,15 +12,24 @@ Before proceeding, you'll first want to ensure that your Sentry project is set u
 Make sure build plugins are enabled on your site to see the plugin run.
 
 ## Installation
+#### UI Installation
+To install plugins via the Netlify UI, go to your team sites list and select the Plugins tab (or follow this direct link to the [plugins directory](https://app.netlify.com/plugins)). Then find "Sentry Build Plugin" and click **Install**.
 
-To install, add the following lines to your `netlify.toml` file:
+UI installation is the recommended way to install this Build Plugin unless you need advanced configuration.
+
+#### File-based Installation
+Alternatively, to install with file-based installation, add the following lines to your `netlify.toml` file:
 
 ```toml
 [[plugins]]
   package = "@sentry/netlify-build-plugin"
+
+  [plugins.inputs]
+    sentryOrg = ""
+    sentryProject = ""
 ```
 
-Note: The `[[plugins]]` line is required for each plugin, even if you have other plugins in your `netlify.toml` file already.
+Note: The `[[plugins]]` line is required for each plugin installed via file-based installation, even if you have other plugins in your `netlify.toml` file already.
 
 ### Create a Sentry Internal Integration
 For Netlify to communicate securely with Sentry, you'll need to create a new internal integration. In Sentry, navigate to: *Settings > Developer Settings > New Internal Integration*.
@@ -33,25 +42,30 @@ Click “Save” at the bottom of the page and grab your token, which you’ll n
 
 
 ### Set Environment Variables in Netlify
-Save the internal integration token as a [site environment variable](https://docs.netlify.com/configure-builds/environment-variables/):
+Save the internal integration token and any other environment variables as [site environment variables](https://docs.netlify.com/configure-builds/environment-variables/):
 1. In Netlify, go to your site's settings.
 2. Click on "Build & deploy".
-3. Add a new environment variable and enter `SENTRY_AUTH_TOKEN` as the name and your internal integration token as the value.
+3. Click “Edit variables” and add `SENTRY_AUTH_TOKEN`, `SENTRY_ORG`, and `SENTRY_PROJECT` with their respective values. For more configuration options see the [environment variables](#environment-variables) section below.
+4. Click "Save".
 
 ![View of internal integration permissions.](images/netlify-environment-variables.png)
 
-### Configuration
-Configure the plugin with your Sentry settings:
-```toml
-[[plugins]]
-  package = "@sentry/netlify-build-plugin"
+For more information about the parameters below, please see the [Sentry release management docs](https://docs.sentry.io/cli/releases/).
 
-  [plugins.inputs]
-    sentryOrg = ""
-    sentryProject = ""
-```
+### Ensure Your SDK is Configured
+To link errors with releases, you must include a release ID (a.k.a version) where you configure your client SDK. For more information, read our documentation on [configuring your SDK for releases](https://docs.sentry.io/workflow/releases/?platform=node#configure-sdk).
 
-For more information about the parameters below, please see the [Sentry release management docs](https://docs.sentry.io/cli/releases/).
+#### Environment Variables
+
+You can use [site environment variables](https://docs.netlify.com/configure-builds/environment-variables/) to configure these values:
+| name | description | default |
+|------|-------------|---------|
+| `SENTRY_AUTH_TOKEN` | Authentication token for Sentry. | - |
+| `SENTRY_ORG` | The slug of the organization name in Sentry. | - |
+| `SENTRY_PROJECT` | The slug of the project name in Sentry. | - |
+| `SENTRY_RELEASE` | The release ID (a.k.a version). | [COMMIT_REF](https://docs.netlify.com/configure-builds/environment-variables/#git-metadata) |
+| `SENTRY_ENVIRONMENT` | The name of the environment being deployed to. | Netlify [deploy context](https://docs.netlify.com/site-deploys/overview/#deploy-contexts) |
+| `SENTRY_RELEASE_PREFIX` | Set this to prefix the release name with the value. | - |
 
 
 #### Plugin Inputs
@@ -60,17 +74,9 @@ For more information about the parameters below, please see the [Sentry release
 | `sentryOrg` | The slug of the organization name in Sentry. | - |
 | `sentryProject` | The slug of the project name in Sentry. | - |
 | `sentryAuthToken` | Authentication token for Sentry. We recommend this be set as an environment variable (see below). | - |
+| `sentryRelease` | The release ID (a.k.a version). | [COMMIT_REF](https://docs.netlify.com/configure-builds/environment-variables/#git-metadata) |
 | `sourceMapPath` | Folder in which to scan for source maps to upload. | Netlify publish directory |
 | `sourceMapUrlPrefix` | Prefix for the location of source maps. | `"~/"` |
 | `skipSetCommits` | Set this to true if you want to disable commit tracking. | `false` |
 | `skipSourceMaps` | Set this to true if you want to disable sending source maps to Sentry. | `false` |
-
-#### Environment Variables
-
-You can also use [site environment variables](https://docs.netlify.com/configure-builds/environment-variables/) to configure these values:
-| name | description | default |
-|------|-------------|---------|
-| `SENTRY_AUTH_TOKEN` | Authentication token for Sentry. | - |
-| `SENTRY_ORG` | The slug of the organization name in Sentry. | - |
-| `SENTRY_PROJECT` | The slug of the project name in Sentry. | - |
-| `SENTRY_ENVIRONMENT` | The name of the environment being deployed to. | Netlify [deploy context](https://docs.netlify.com/site-deploys/overview/#deploy-contexts) |
+| `releasePrefix` | Set this to prefix the release name with the value. | - |

images/netlify-environment-variables.png

@@ -28,6 +28,8 @@ module.exports = {
     const sentryOrg = process.env.SENTRY_ORG || inputs.sentryOrg
     const sentryProject = process.env.SENTRY_PROJECT || inputs.sentryProject
     const sentryAuthToken = process.env.SENTRY_AUTH_TOKEN || inputs.sentryAuthToken
+    const sentryRelease = process.env.SENTRY_RELEASE || inputs.sentryRelease || process.env.COMMIT_REF
+    const releasePrefix = process.env.SENTRY_RELEASE_PREFIX || inputs.releasePrefix || ''
     const sentryEnvironment = process.env.SENTRY_ENVIRONMENT || process.env.CONTEXT
     const sourceMapPath = inputs.sourceMapPath || PUBLISH_DIR
     const sourceMapUrlPrefix = inputs.sourceMapUrlPrefix || DEFAULT_SOURCE_MAP_URL_PREFIX
@@ -45,10 +47,13 @@ module.exports = {
 
       await createSentryConfig({ sentryOrg, sentryProject, sentryAuthToken })
 
+      /* Apply release prefix */
+      const release = `${releasePrefix}${sentryRelease}`
+
       /* Notify Sentry of release being deployed on Netlify */
-      await sentryRelease({
+      await createSentryRelease({
         pluginApi,
-        sentryAuthToken,
+        release,
         sentryEnvironment,
         sourceMapPath,
         sourceMapUrlPrefix,
@@ -65,10 +70,9 @@ module.exports = {
   }
 }
 
-async function sentryRelease({ pluginApi, sentryAuthToken, sentryEnvironment, sourceMapPath, sourceMapUrlPrefix, skipSetCommits, skipSourceMaps }) {
+async function createSentryRelease({ pluginApi, release, sentryEnvironment, sourceMapPath, sourceMapUrlPrefix, skipSetCommits, skipSourceMaps }) {
   // default config file is read from ~/.sentryclirc
   const { constants, inputs, utils } = pluginApi
-  const release = process.env.COMMIT_REF
   const cli = new SentryCli()
 
   console.log('Creating new release with version: ', release)

index.js

@@ -6,6 +6,8 @@ inputs:
     description: The slug of the project name in Sentry
   - name: sentryAuthToken
     description: Authentication token for Sentry
+  - name: sentryRelease
+    description: The release ID (a.k.a version)
   - name: sourceMapPath
     description: Folder in which to scan for source maps to upload
   - name: sourceMapUrlPrefix
@@ -16,3 +18,5 @@ inputs:
   - name: skipSourceMaps
     description: Set this to true if you want to disable sending source maps to Sentry
     default: False
+  - name: releasePrefix
+    description: Set this to prefix the release name with the value.