Install Scout

Before you begin

Generate Redocly API key

Webhook setup

Scout needs access to your Git source contol. You need to provide the Scout webhook URL to your Git source control and pass credentials to the Scout via configuration.

Note: Webhook setup requires URL of the Scout instance from the next step. You can configure a temporary URL first and then update it later.

GitLab

To run Scout in GitLab, create a new user on behalf of which Scout makes operations on connected repositories and leaves comments in merge requests.

1. Create a new user with a Maintainer role by following these instructions.
2. Add newly created user as a member of projects or groups you want to sync with your main Redocly project.
3. Sign in into newly created user account and create personal access token (scopes: api) - save it for the configuration step.
4. Go to https://{gitlab-server-url}/api/v4/users?username={username} where {username} is the user that Scout performs actions on behalf of. Copy the value of the user id for the configuration step.
5. Configure a GitLab webhook for every project or group (at least GitLab Premium is required) to sync:
   • URL: https://{scout-url}/webhooks/gitlab
   • Secret token is optional but if you provide one then save it for the configuration step.
   • Triggers: Push events and Merge request events

GitHub

To run Scout in GitHub you need to create a GitHub application and provide it with access to your repositories. It allows Scout to create comments and set statuses in your PRs.

1. Create a new application https://{github-server-url}/organizations/{org}/settings/apps
2. Fill required fields
   • Github App name: Redocly Scout
   • Homepage URL: https://redocly.com
   • Webhook URL: https://{scout-url}/webhooks/github
   • Secret: any value, you need to provide same value to Scout config WEBHOOK_SECRET field
   • Repository permissions:
     • Contents: read-only
     • Pull requests: read and write
     • Commit statuses: read and write
   • User permissions:
     • Email addresses: read-only
   • Subscribe to events: PullRequest, Push
3. Scroll down to Private keys and generate a new private key
4. Go to Optional features -> Activate optional features for Redocly Scout -> User-to-server token expiration -> toggle Opt-in

Running Scout in your infra

You could run a Scout instance with Docker:

docker run redocly/scout

Scout is a source available tool and you could run it from source which could be found in this repository.

Configuration

GITHUB_PROVIDERS='[{
  "appId": "123",
  "appUserId": "456",
  "privateKey": "${MY_PRIVATE_KEY}",
  "webhookSecret": "${MY_WH_SECRET}"
}]'
MY_PRIVATE_KEY='-----BEGIN RSA PRIVATE KEY-----
MIIEp...6G2Hg==
-----END RSA PRIVATE KEY-----'
MY_WH_SECRET='my-secret'

GITLAB_PROVIDERS='[{
  "userId": "123",
  "privateToken": "d7dsf7s5d76576sdf5sd5f76",
  "webhookSecret": "${MY_WH_SECRET}"
}]'
MY_WH_SECRET='my-secret'

GITLAB_PROVIDERS='[{
  "namespaceId": "my-org",
  "repositoryId": "config-repo",
  "providerId": "123",
  "contentPath": "./service-domains.yaml",
  "contentType": "file",
  "mountPath": ".lint/service-domains.yaml"
}]'