Introduction

By default, when viewing an event on the ARC screen, you are presented with the decompiled source code for that event. Source Attach connects your GitLab and GitHub source repositories to OverOps, allowing OverOps to display the original source code and Git Blame data in the ARC screen for an event.

There are two ways to connect Git source repositories; the first is through the settings interface, and the second is from the OverOps agent. Both of these methods require setting up a security token from the settings interface.

Add a security token

Open Settings by clicking Settings in the top right corner of the OverOps dashboard.

From the side navigation menu under Integrations, select Source Attach.

Source Attach uses token authentication to connect to the supported Git providers. Before you add a security token to OverOps, you must generate a token with "read" permissions from your Git provider.

🚧

Make sure you copy or save this token as OverOps will need it to configure Source Attach.

You can generate a token using the following instructions from our supported Git providers:

GitHub
https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token

GitLab
https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html

Bitbucket
https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html

You can add the token to OverOps in one of two ways:

From the Security tab

1. Click the Security tab.

2. Enter a descriptive name into the Name text input.

3. Copy the token that you generated from your Git provider and paste it into the Token field.

4. Click the Add button. Your token is now available to use for Source Attach.

📘

The Security Method dropdown automatically selects this newly added token in the Configuration tab.

From the Configuration tab

🚧

While there is no limit to the amount of source attach configurations you can create, it's important to note that each one you add will impact performance.

1. Click the Configuration tab.

2. Click the Security Method dropdown. Select Add new Token.

3. Enter a descriptive name into the Name text input.

4. Copy the token that you generated from your Git provider and paste it into the Token field.

5. Click the Add button.

📘

Adding your token will automatically select it in the Security Method dropdown.

Edit tokens by clicking the Pencil icon or remove them by clicking the Trash Can icon in the token search panel. Additionally, remove tokens in bulk by clicking the checkbox next to the name and clicking the Remove Selected button.

Adding your source repository

From Settings

1. Select the provider type from the Repository Provider dropdown.

2. Copy the URL for your source repository, e.g., https://github.com/takipi-field/overops-event-generator, and paste it into the Repository URL text input.

3. (Optional) Enter the parent directory for your source code if it's in a sub-module or non-standard location into the Sources Root text input.

📘

Understanding Sources Root

By default, OverOps scans for standard folder structures for java and .NET projects from the repository root.

Source Attach automatically scans the following directories for your attached applications source code packages:

Java

/src/main/java
/src
/src/java
/src/main/test

.NET

/src
/test

Example: Suppose your java class exists at /src/main/java/com/company/MyClass.java. In that case, OverOps will automatically find this class without setting the Sources Root option since the package exists in a directory for which OverOps scans.

The Sources Root option allows OverOps to find your source code if it exists in a submodule or a non-standard java or .NET path.

For example, if you have a maven-based project and your java class exists at /module/src/main/java/com/company/MyClass.java, set your Sources Root value to module.

Additionally, if your java class exists at a non-standard path, e.g. /module/source/com/company/MyClass.java, set your Sources Root value to module/source, and Source Attach will scan that specific directory.

4. Select a previously created token from the Security Method dropdown, or create a new one following the steps above.

5. Click the Connect button to verify your token. A successful connection will populate the branches and tags dropdown from the connected repository.

6. Select Branch or Tag to populate the second dropdown with the branches or tags from the connected repository. Selecting SHA will allow you to input a SHA for a specific commit in your Git repository.

7. Select a Branch, Tag, or enter a SHA and click the Add button.

The repository is now connected to OverOps, allowing you to view Git Blame data in the ARC screen.

Edit Source Attach Configurations by clicking the Pencil icon or remove them by clicking the Trash Can icon in the configurations search panel. Additionally, remove configurations in bulk by clicking the checkbox next to the name and clicking the Remove Selected button.

From OverOps Agent

Using the following article's instructions: https://doc.overops.com/docs/agent-properties, you can use these properties to attach a source repository to a specific OverOps agent.

Once these options are added, your Git source repository will be attached for all events that come from the attached agent.

Viewing Git Blame Data

Open the ARC screen by clicking on an event from the OverOps dashboard.

📘

Source Attach for Previously Viewed Events

If you've previously viewed the source for an event before adding a Source Attach Configuration, you may encounter some cached decompiled source for that event.

If decompiled source is displayed, click the Refresh All Sources button in the bottom left-hand corner of the ARC screen. Once this completes, refresh the browser window to display Git Blame data.

In the Code panel, line numbers and the associated Blame data are present with the code author's name.

Hovering over the source line number will display ellipses. Clicking the ellipses will show you commit information, including the commit comments and date.

Clicking View Commit will automatically open the commit from your source repository browser in a new tab.

Troubleshooting

These are the most common reasons why you may not see blame data:

Your token may be invalid. See above.

Your token may not have the right permissions. See above.

You have hit your rate limit with your Git provider.
Most Git providers have a rate limit on their API. Wait a minute and try loading the ARC screen again.

Additional Tips:

Make sure your collector has access to your Git provider.

I still see decompiled code. Try clicking the Refresh All Sources button in the bottom left-hand corner of the ARC screen, wait until it finishes, and refresh the page.

Still not working? Check your collector logs for errors.