App Integration for Codecov Self-Hosted

Introduction

The App Integration allows Codecov to:

1. Provide login with functionality to end users.
2. Post comments and status on Pull Requests in
3. Sync Codecov state to via webhooks
4. Provide fine grained controls for determining which repositories Codecov can access.

📘

This Approach works for both and Enterprise

Regardless of which version you're using this approach can work for either. However you will need to be mindful of adapting the code snippets to your particular scenario (i.e., , or _enterprise in the codecov.yml)

Creating a App Integration

🚧

Enable webhooks

Webhooks need to be enabled for the App to work. This is the method the app uses to connect and communicate with Codecov.

To create a App Integration for Codecov, first navigate to your organization in the UI.

Then from the Sidebar Click Developer Settings > Apps:

Choose "New App":

🚧

Create the App for your Organization

When creating the app, ensure that you're creating it for your organization, not your personal account. The URL on the app creation page should read: https://.com/settings/apps/new

And fill out the relevant fields for app creation:

It's important to set the proper callback URL. They should point to your Codecov Self-Hosted install as follows:

• <your-codecov-self-hosted-url>/login/ghe

For the webhook URL:

• <your-codecov-self-hosted-url>/webhooks/_enterprise

You should provide a secret.

:
  
    webhook_secret: "<some-secret>"

Once provided, you will want to ensure that you properly provide the secret in the Codecov Self-Hosted codecov.yml.

Permissions

The following screenshot shows all permissions needed by the app integration, as well as the relevant events. For visibility permissions with a greater setting than "No Access" have been emphasized in green.

Repository Permissions

Organization Permissions

User Permissions

Email address read is required. All others can be set to "No Access"

Events

📘

Using .com?

If you're not using Enterprise, make sure that you only publish this app for your organization.

Use the App for Login

Once the App is created, a Client ID will be generated automatically by . Additionally you will need to generate a new Client Secret for the App in the user interface. Once this is done, you can use the client id and secret as part of the configuration in the codecov.yml as follows:

:
  client_id: "<client-id>"
  client_secret: "<client-secret>"

Once these values are supplied and the Codecov instance restarted, login via should be functional.

Generate and Add a PEM file to Codecov.

🚧

Adding a PEM file to Codecov is highly encouraged!

The PEM file allows Codecov to post pull request comments and update statuses on . Not adding a PEM file may cause Codecov to malfunction.

After creating the App, will prompt you to create a .pem file from the ui. This will result in a .pem file you can download. Once downloaded you will need to place this file in the same directory as your codecov.yml and docker-compose.yml and update your docker-compose.yml as follows:

web:
  #... other configuration
  volumes:
  	- ./file.pem:/config/file.pem 
worker:
  #... other configuration
  volumes:
  	- ./file.pem:/config/file.pem

You will need to add the integration and webhook_secret sections to the (or _enterprise) section of your codecov.yml as follows:

: 
# ...
  webhook_secret: "ff523b3162ef64604f03c94459"

# values from the  App integration
  integration:
    id: 63040 # App ID value shown on 
your integration's page in 
    pem: /config/file.pem # path to the pem file you 
created in the `web` and `worker` containers.

Install App Integration to your organizations

Depending on your settings, you may have to install the Codecov App on any organizations that you wish to use it with. This can be done from the app settings screen.

After installing the app you can verify installation on the organization's installed apps page.

Troubleshooting

• If you don't receive comments on Pull Requests for Repositories with the App Integration installed, visit the repo settings page for that particular repository on your Codecov Enterprise install:

For .com:
<your-codecov-self-hosted-url>/gh/<org-name>/><repo-name>/settings

For Enterprise:
<your-codecov-self-hosted-url>/ghe/<org-name>/><repo-name>/settings

Once there, check the " Webhook" section and press the "Create Web Hook" button if a webhook is not already set.