Last updated

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

Environment variable Description
PORTThe port that the application runs on. Default value: 8080.
MAX_CONCURRENT_JOBSThe number of jobs that can be executed in parallel. Default value: 2.
AUTO_MERGEIf set to true, merges PRs when updates are pushed to the main branch. Default value: false.
API_FOLDERThe path in the repository where Scout looks for API definitions. Default value: /.
DATA_FOLDERThe path to the folder where Scout stores temporary data. Example: /tmp/redocly/scout-data/.
REDOCLY_API_URLRedocly API base URL. Example: https://app.beta.redocly.com/api.
REDOCLY_API_KEYRedocly organization API token.
REDOCLY_ORG_IDRedocly organization ID. Example: acme-org.
REDOCLY_PROJECT_IDRedocly project ID. Example: acme-portal.
REDOCLY_DEST_FOLDER_PATHThe path where Scout pushes discovered API definitions. You can use {title}, {repoId}, {orgId} and {metadata} variables here. Use dot notation to access metadata nested properties. Default value: apis/{metadata.team}/{repoId}/{title}.
REDOCLY_JOB_CONTEXTA job execution context. You can reference same variables as in REDOCLY_DEST_FOLDER_PATH. Example: {metadata.team}.
LOG_FORMATPossible values: pretty, json. Default value: json.
LOG_LEVELPossible values: trace, debug, info, warn, error, fatal. Default value: info.

GITHUB_PROVIDERS

JSON array of GitHub app configurations. Each configuration has the following fields:

  • url - GitHub server url. Omit in case of GitHub cloud.
  • appId - GitHub application ID. https://{github-server-url}/organizations/{org}/settings/apps -> Redocly Scout -> App ID.
  • appUserId - GitHub application user that leaves Scout-related comments. https://{github-server-url}/users/{app slug name}[bot]
  • privateKey - GitHub application private key created during application configuration.
  • webhookSecret - GitHub webhook secret, created during application configuration.

You can keep your secrets as separate values. They can be referred to within the definition of other values:

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

JSON array of GitLab instance configurations. Each configuration has the following fields:

  • url - GitLab instance url. Omit if you use GitLab.com (GitLab Cloud).
  • userId - Your GitLab user id. The instructions for how to obtain it are available in the GitLab section.
  • privateToken - GitLab private token generated on the user's account.
  • webhookSecret - The secret used when creating a webhook on GitLab.

You can keep your secrets as separate values. They can be referred to within the definition of other values:

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

REDOCLY_REMOTES

JSON array of remote configurations for pushing additional files. Scout will push those files that match the rules declared here, in addition to pushing APIs. Each entry has the following fields:

  • namespaceId - ID of the namespace (organization slug) of the Git repository.
  • repositoryId - ID of the Git repository (repository slug for GitHub).
  • providerId - Git provider ID per GITHUB_PROVIDERS or GITLAB_PROVIDERS, appId for GitHub or instance URL origin (e.g. https://gitlab.com) for GitLab.
  • contentPath - Path to the content (folder or file) in the source repository to sync.
  • contentType - file or folder, folder by default.
  • mountPath - Path to mount the content in the Project repository.
GITLAB_PROVIDERS='[{
  "namespaceId": "my-org",
  "repositoryId": "config-repo",
  "providerId": "123",
  "contentPath": "./service-domains.yaml",
  "contentType": "file",
  "mountPath": ".lint/service-domains.yaml"
}]'