Skip to content
This repository was archived by the owner on Dec 4, 2023. It is now read-only.

Commit 9f5145e

Browse files
lobsterkatielobsterkatie
authored
ref(docs): Revamp and update readme (#75)
This reorganizes and updates the readme, both for clarity and to reflect changes that have been made on Netlify's side. Key changes: - Reorganize content. Specifically: Group into Installation, Configuration, and Options sections. Gather prerequisite steps in Sentry together, and put them as a first installation step. Combine env variable and `netlify.toml` options tables since they largely duplicated each other. - Add table of contents. - Add information on UI configuration. - Update descriptions of UI steps, both in Sentry and Netlify, to match current nomenclature, layout, etc. For example, in Netlify, the Plugins tab is now called Integrations, and Sentry is no longer listed under Build Plugins but instead under Monitoring. - Add note explaining the difference between this plugin and Netlify's new experimental Sentry error-monitoring plugin. - Remove "Deploy to Netlify" button, as this repo is not a site deployable to Netlify, and even if it were, only Sentry's Netlify account could do so.
1 parent 5c8a12d commit 9f5145e

File tree

1 file changed

+99
-54
lines changed

1 file changed

+99
-54
lines changed

‎README.md‎

Lines changed: 99 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -1,87 +1,132 @@
1-
# Sentry Netlify build plugin &nbsp;&nbsp;&nbsp;<a href="https://app.netlify.com/start/deploy?repository=https://github.com/getsentry/sentry-netlify-build-plugin"><img src="https://www.netlify.com/img/deploy/button.svg"></a>
1+
# Sentry Netlify Build Plugin
22

33
Automatically upload source maps and notify [Sentry](https://sentry.io/) of new releases being deployed to your site after it finishes building in Netlify.
44

55
The Sentry Netlify build plugin:
6-
* Notifies Sentry of new releases being deployed.
7-
* Uploads source maps to Sentry.
8-
* Sends Sentry the commit SHA of HEAD to enable commit features.
96

10-
Before proceeding, you'll first want to ensure that your Sentry project is set up properly to track commit metadata. The easiest way to do that is to [install a repository integration](https://docs.sentry.io/product/releases/#install-repo-integration).
7+
- Notifies Sentry of new releases being deployed.
8+
- Uploads source maps to Sentry.
9+
- Sends Sentry the commit SHA of HEAD to enable commit features.
1110

12-
By default, the linked Sentry repository will be parsed from the Netlify's `REPOSITORY_URL` environment variable. This behaviour can be overridden using the `SENTRY_REPOSITORY` environment variable.
11+
_**Note:** This build plugin is separate from `@netlify/sentry`, which is a monitoring plugin built by Netlify. For more information, see [`@sentry/netlify-build-plugin` vs. `@netlify/sentry`](#sentrynetlify-build-plugin-vs-netlifysentry) below._
1312

14-
Make sure build plugins are enabled on your site to see the plugin run.
13+
---
14+
15+
- [Installation](#installation)
16+
- [Prepare Your Sentry Organization](#prepare-your-sentry-organization)
17+
- [Install the Plugin](#install-the-plugin)
18+
- [Configure Your SDK](#configure-your-sdk)
19+
- [Configuration](#configuration)
20+
- [UI Configuration](#ui-configuration)
21+
- [Configuration Using Environment Variables](#configuration-using-environment-variables)
22+
- [Configuration in `netlify.toml`](#configuration-in-netlifytoml)
23+
- [Options](#options)
24+
- [`@sentry/netlify-build-plugin` vs. `@netlify/sentry`](#sentrynetlify-build-plugin-vs-netlifysentry)
1525

1626
## Installation
27+
28+
### Prepare Your Sentry Organization
29+
30+
Before proceeding, you'll first want to ensure that your Sentry project is set up properly to track commit metadata and allow uploading of source maps.
31+
32+
First, if you haven't already, [install a repository integration](https://docs.sentry.io/product/releases/#install-repo-integration).
33+
34+
Second, create an [internal integration in Sentry](https://docs.sentry.io/product/integrations/integration-platform/internal-integration), which will handle authentication for source map uploading.
35+
36+
1. In Sentry, navigate to: _Settings > Developer Settings > New Internal Integration_.
37+
2. Give your new integration a name (for example, "Netlify Deploy Integration") and specify the necessary permissions. In this case, we need "Admin" access for "Release" and "Read" access for "Organization". You can leave all other fields blank.
38+
3. Click "Save Changes" at the bottom of the page.
39+
4. Once the integration has been created, it should take you to the "Edit Internal Integration" page for your integration. Scroll down to the "Tokens" section and copy your token, which you'll need when configuring the plugin.
40+
41+
### Install the Plugin
42+
43+
The plugin can be installed either through the Netlify UI or by adding configuration values to `netlify.toml`. Unless you need advanced configuration, we recommend using the UI.
44+
1745
#### UI Installation
18-
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**.
1946

20-
UI installation is the recommended way to install this Build Plugin unless you need advanced configuration.
47+
To install the plugin via the Netlify UI, go to your team sites list and select the Integrations tab (or follow this direct link to the [Integrations directory](https://app.netlify.com/plugins)). Then search for "Sentry" and click **Enable** and then **Enable Release Management**.
2148

2249
#### File-based Installation
23-
Alternatively, to install with file-based installation, add the following lines to your `netlify.toml` file:
50+
51+
Alternatively, to use file-based installation, add the following lines to your `netlify.toml` file:
2452

2553
```toml
2654
[[plugins]]
2755
package = "@sentry/netlify-build-plugin"
2856

2957
[plugins.inputs]
30-
sentryOrg = ""
31-
sentryProject = ""
58+
sentryOrg = "your org slug"
59+
sentryProject = "your project slug"
3260
```
3361

34-
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.
62+
Note: The `[[plugins]]` line is required for each plugin installed via file-based installation, so you need to add it here even if you have other plugins in your `netlify.toml` file already.
63+
64+
### Configure Your SDK
65+
66+
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).
67+
68+
## Configuration
3569

36-
### Create a Sentry Internal Integration
37-
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*.
70+
The Sentry build plugin can be configured in the Netlify UI, by setting environment variables, or by adding options to `netlify.toml`.
3871

39-
Give your new integration a name (for example, “Netlify Deploy Integration”) and specify the necessary permissions. In this case, we need Admin access for “Release” and Read access for “Organization”.
72+
### UI Configuration
4073

41-
![View of internal integration permissions.](images/internal-integration-permissions.png)
74+
Basic configuration can be done in the Netlify UI. In the same Integrations tab where you [installed the plugin](#ui-installation), find the Sentry plugin again, click "View," and you should now see a configuration panel where you can set your auth token (from the internal integration [created above](#prepare-your-sentry-organization)) along with your organization and project slugs.
4275

43-
Click “Save” at the bottom of the page and grab your token, which you’ll need this in the next step.
76+
Doing this will automatically set the `SENTRY_AUTH_TOKEN`, `SENTRY_ORG`, and `SENTRY_PROJECT` environment variables in Netlify.
4477

78+
### Configuration Using Environment Variables
79+
80+
The plugin can be configured using [site environment variables](https://docs.netlify.com/configure-builds/environment-variables/) in Netlify:
4581

46-
### Set Environment Variables in Netlify
47-
Save the internal integration token and any other environment variables as [site environment variables](https://docs.netlify.com/configure-builds/environment-variables/):
4882
1. In Netlify, go to your site's settings.
49-
2. Click on "Build & deploy".
50-
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.
51-
4. Click "Save".
83+
2. Click on "Environment Variables".
84+
3. Add `SENTRY_AUTH_TOKEN`, `SENTRY_ORG`, and `SENTRY_PROJECT` with their respective values. (The auth token comes from the internal integration [created above](#prepare-your-sentry-organization).)
85+
86+
For more configuration options see the [Options](#options) section below.
5287

53-
![View of internal integration permissions.](images/netlify-environment-variables.png)
88+
### Configuration in `netlify.toml`
89+
90+
You organization and project slugs can be specified in `netlify.toml` in the `plugins.inputs` section:
91+
92+
```toml
93+
[[plugins]]
94+
package = "@sentry/netlify-build-plugin"
95+
96+
[plugins.inputs]
97+
sentryOrg = "your org slug"
98+
sentryProject = "your project slug"
99+
```
100+
101+
We recommend against setting your auth token in `netlify.toml`, to avoid committing it to your repo.
102+
103+
For more configuration options see the [Options](#options) section below.
104+
105+
## Options
106+
107+
In most cases, auth token, org slug, and project slug are all that's needed to use the plugin. For more advanced use cases, configuration can be done either by setting [site environment variables](https://docs.netlify.com/configure-builds/environment-variables/) or by adding to `netlify.toml`. Most options can be set either way.
54108

55109
For more information about the parameters below, please see the [Sentry release management docs](https://docs.sentry.io/cli/releases/).
56110

57-
### Ensure Your SDK is Configured
58-
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).
111+
| `netlify.toml` | Environment Variable | Description | Default |
112+
| --- | --- | --- | --- |
113+
| `sentryOrg` | `SENTRY_ORG` | Slug of the organization in Sentry. | - |
114+
| `sentryProject` | `SENTRY_PROJECT` | Slug of the project in Sentry | - |
115+
| `sentryAuthToken` | `SENTRY_AUTH_TOKEN` | Authentication token for Sentry. We recommend this be set as an environment variable, to avoid committing it to your repo. | - |
116+
| `sentryRelease` | `SENTRY_RELEASE` | Release ID (a.k.a version) | [COMMIT_REF](https://docs.netlify.com/configure-builds/environment-variables/#git-metadata) env variable, automatically set by Netlify |
117+
| `sentryRepository` | `SENTRY_REPOSITORY` | Name of the repository linked to your Sentry repository integration, in the form `org-name/repo-name` | Derived from [REPOSITORY_URL](https://docs.netlify.com/configure-builds/environment-variables/#git-metadata) env variable, automatically set by Netlify |
118+
| `releasePrefix` | `SENTRY_RELEASE_PREFIX` | Prefix to add to the release name | - |
119+
| - | `SENTRY_ENVIRONMENT` | Name of the environment being deployed to | Netlify [deploy context](https://docs.netlify.com/site-deploys/overview/#deploy-contexts) |
120+
| `sourceMapPath` | - | Folder to scan for source maps to upload | Netlify publish directory |
121+
| `sourceMapUrlPrefix` | - | Prefix for uploaded source map filenames (see [sentry-cli docs](https://docs.sentry.io/product/cli/releases/#sentry-cli-sourcemaps)) | `"~/"` |
122+
| `skipSetCommits` | - | If true, disable commit tracking. | `false` |
123+
| `skipSourceMaps` | - | If true, disable uploading source maps to Sentry. | `false` |
124+
| `deployPreviews` | - | If false, skip running the build plugin on preview deploys. | `true` |
125+
126+
## `@sentry/netlify-build-plugin` vs. `@netlify/sentry`
127+
128+
Both Sentry and Netlify have created plugins which integrate the two services. The Sentry plugin (the one whose docs you're reading right now) is a build plugin, which handles release management and source map uploading. The Netlify plugin, is a monitoring plugin, which adds Sentry to Netlify functions. Docs for that plugin can be found [here](https://docs.netlify.com/netlify-labs/experimental-features/sentry-integration/).
129+
130+
The two plugins can be enabled separately or together, depending on your installation method. In the Netlify UI, they are enabled together, in the Integrations tab, and there you will see settings for both. If enabled through `netlify.toml`, they must be enabled separately, with a `[[plugins]]` section added for each.
59131

60-
#### Environment Variables
61-
62-
You can use [site environment variables](https://docs.netlify.com/configure-builds/environment-variables/) to configure these values:
63-
| name | description | default |
64-
| ----------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------- |
65-
| `SENTRY_AUTH_TOKEN` | Authentication token for Sentry. | - |
66-
| `SENTRY_ORG` | The slug of the organization name in Sentry. | - |
67-
| `SENTRY_PROJECT` | The slug of the project name in Sentry. | - |
68-
| `SENTRY_RELEASE` | The release ID (a.k.a version). | [COMMIT_REF](https://docs.netlify.com/configure-builds/environment-variables/#git-metadata) |
69-
| `SENTRY_REPOSITORY` | The name of the target Sentry repository. | - |
70-
| `SENTRY_ENVIRONMENT` | The name of the environment being deployed to. | Netlify [deploy context](https://docs.netlify.com/site-deploys/overview/#deploy-contexts) |
71-
| `SENTRY_RELEASE_PREFIX` | Set this to prefix the release name with the value. | - |
72-
73-
74-
#### Plugin Inputs
75-
| name | description | default |
76-
| -------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
77-
| `sentryOrg` | The slug of the organization name in Sentry. | - |
78-
| `sentryProject` | The slug of the project name in Sentry. | - |
79-
| `sentryAuthToken` | Authentication token for Sentry. We recommend this be set as an environment variable (see below). | - |
80-
| `sentryRelease` | The release ID (a.k.a version). | [COMMIT_REF](https://docs.netlify.com/configure-builds/environment-variables/#git-metadata) |
81-
| `sentryRepository` | The name of the target Sentry repository. | Derived from [REPOSITORY_URL](https://docs.netlify.com/configure-builds/environment-variables/#git-metadata) |
82-
| `sourceMapPath` | Folder in which to scan for source maps to upload. | Netlify publish directory |
83-
| `sourceMapUrlPrefix` | Prefix for the location of source maps. | `"~/"` |
84-
| `skipSetCommits` | Set this to true if you want to disable commit tracking. | `false` |
85-
| `skipSourceMaps` | Set this to true if you want to disable sending source maps to Sentry. | `false` |
86-
| `releasePrefix` | Set this to prefix the release name with the value. | - |
87-
| `deployPreviews` | Set this to false if you want to skip running the build plugin on deploy previews. | `true` |
132+
Note that in the Netlify UI, the Sentry plugin has a `Beta` label. This applies to only to the Netlify-built plugin, not this one.

0 commit comments

Comments
 (0)