Code monitoring

Keep on top of events in your codebase. Watch your code with code monitors and trigger actions to run automatically in response to events.

Code monitors allow you to keep track of and get notified about changes in your code. Some use cases for code monitors include getting notifications for potential secrets, anti-patterns, or common typos committed to your codebase.

Here are some starting points for your first code monitor:

Watch for consumers of deprecated endpoints

SHELL
f:\.tsx?$ patterntype:regexp fetch\(['"`]/deprecated-endpoint

If youre deprecating an API or an endpoint, you may find it useful to set up a code monitor watching for new consumers. As an example, the above query will surface fetch() calls to /deprecated-endpoint within TypeScript files. Replace /deprecated-endpoint with the actual path of the endpoint being deprecated.

Get notified when a file changes

SHELL
patterntype:regexp repo:^github\.com/sourcegraph/sourcegraph$ file:SourcegraphWebApp\.tsx$ type:diff

You may want to get notified when a given file is changed, regardless of the diff contents of the change: the above query will return all changes to the SourcegraphWebApp.tsx file on the github.com/sourcegraph/sourcegraph repo.

Get notified when a specific function call is added

SHELL
repo:^github\.com/sourcegraph/sourcegraph$ type:diff select:commit.diff.added Sprintf

You may want to monitor new additions of a specific function call, for example a deprecated function or a function that introduces a security concern. This query will notify you whenever a new addition of Sprintf is added to the sourcegraph/sourcegraph repository. This query selects all diff additions marked as "+". If a call of Sprintf is both added and removed from a file, this query will still notify due to the addition.

Code monitors are made up of two main elements: Triggers and Actions.

Triggers

A trigger is an event which causes execution of an action. Currently, code monitoring supports one kind of trigger: "When new search results are detected" for a particular search query. When creating a code monitor, users will be asked to specify a query as part of the trigger.

Sourcegraph will run the search query over every new commit for the searched repositories, and when new results for the query are detected, a trigger event is emitted. In response to the trigger event, any actions attached to the code monitor will be executed.

A query used in a "When new search results are detected" trigger must be a type:commit or type:diff search. This allows Sourcegraph to detect new search results periodically.

Actions

An action is executed in response to a trigger event. Currently, code monitoring supports three different actions:

Sending a notification email to the owner of the code monitor

Prerequisite: Ensure email notifications are configured in site configuration.

1. Click the Code monitoring menu item at the top right of your page.
2. Click the Create new code monitor button at the top right of the page.
3. Fill out the Name input with: "TODOs".
4. Under the Trigger section, click When there are new search results.
5. In the Search query input, enter the following search query: TODO type:diff patternType:keyword. (Note that type: and patternType: are required as part of the search query for code monitoring.)
6. You can click Preview results to see all previous additions or removals of TODO to your codebase.
7. Back in the code monitor form, click Continue.
8. Click Send email notifications under the Actions section. You can use "Send test email" to verify you can properly receive notifications and to lean more about the format.
9. Click Done.
10. Click Create code monitor.

You should now see the TODO code monitor on the page, and you will receive email notifications whenever the trigger fires.

Sending a Slack message to a channel

You can set up code monitors to send notifications about new matching search results to Slack channels.

Usage

1. In Sourcegraph, click on the "Code Monitoring" nav item at the top of the page.
2. Create a new code monitor or edit an existing monitor by clicking on the "Edit" button next to it.
3. Under actions, select Send Slack message to channel.
4. Paste your webhook URL into the "Webhook URL" field. (See "Creating a Slack incoming webhook URL" below for detailed instructions.)
5. Click on the "Continue" button, and then the "Save" button.

Creating a Slack incoming webhook URL

1. You must have permission to create apps in your organization's Slack workspace.
2. Go to https://api.slack.com/apps and sign in to your Slack account if necessary.
3. Click on the "Create an app" button.
4. Create your app "From scratch".
5. Give your app a name and select the workplace you want notifications sent to.
6. Once your app is created, click on the "Incoming Webhooks" in the sidebar, under "Features".
7. Click the toggle button to activate incoming webhooks.
8. Scroll to the bottom of the page and click on "Add New Webhook to Workspace".
9. Select the channel you want notifications sent to, then click on the "Allow" button.
10. Your webhook URL is now created! Click the copy button to copy it to your clipboard.

Sending a webhook event to an endpoint of your choosing

Webhook notifications provide a way to execute custom responses to a code monitor notification. They are implemented as a POST request to a URL of your choice. The body of the request is defined by Sourcegraph, and contains all the information available about the cause of the notification.

Prerequisites

• You must have a service running that can accept the POST request triggered by the webhook notification

Creating a webhook receiver

A webhook receiver is a service that can accept an HTTP POST request with the contents of the webhook notification. The receiver must be reachable from the Sourcegraph cluster using the URL that is configured below.

The HTTP POST request sent to the receiver will have a JSON-encoded body with the following fields:

• monitorDescription: The description of the monitor as configured in the UI
• monitorURL: A link to the monitor configuration page
• query: The query that generated results
• results: The list of results that triggered this notification. Contains the following sub-fields
  • repository: The name of the repository the commit belongs to
  • commit: The commit hash for the matched commit.
  • diff: The matching diff in unified diff format. Only set if the result is a diff match.
  • matchedDiffRanges: The character ranges of diff that matched query. Only set if the result is a diff match.
  • message: The matching commit message. Only set if the result is a commit match.
  • matchedMessageRanges: The character ranges of message that matched query. Only set if the result is a commit match.

Current flow

To put it all together, a code monitor has a flow similar to the following:

A user creates a code monitor, which consists of:

• a name for the monitor
• a trigger, which consists of a search query to run periodically,
• and an action, which is sending an email, sending a Slack message, or sending a webhook event

Sourcegraph runs the query periodically over new commits. When new results are detected, a notification will be sent with the configured action. It will either contain a link to the search that provided new results, or if the "Include results" setting is enabled, it will include the result contents.

Best practices

There are some best practices we recommend when creating code monitors.

Privacy and visibility

Do not include confidential information in monitor names

Every code monitor has a name that will be shown wherever the monitor is referenced. In notification actions this name is likely to be the only information about the event, so its important for identifying what was triggered, but also has to be safe to expose in plain text emails.

Do not include results when the notification destination is untrusted

Each code monitor action has the ability to include the result contents when sending a notification. This is often convenient because it lets you immediately see which results triggered the notification. However, because the result contents include the code that matched the search query, they may contain sensitive information. Care should be taken to only send result contents if the destination is secure.

For example, if sending the results to a Slack channel, every user that can view that channel will also be able to view the notification messages. The channel should be properly restricted to users who should be able to view that code.

Scale

Code monitors have been designed to be performant even for large Sourcegraph instances. There are no hard limits on the number of monitors or the volume of code monitored. However, depending on a number of factors such as the number of code monitors, the number of repos monitored, the frequency of commits, and the resources allocated to your instance, it's still possible to hit soft limits. If this happens, your code monitor will continue to work reliably, but it may execute more infrequently.

Architecture

Learn about how Code Monitoring fits into Sourcegraph in the architecture overview.