configurations.md

description
Learn about the different configuration options your app or integration can use

Configurations

gitbook-manifest.yaml

Integrations can define a schema for the configuration. You will be prompted upon setup via the CLI for some required options. See the keys below for more information.

*required

Name*

The name of your integration. Must be unique across all GitBook integrations.

Example:

name: slack

Title*

The title of your integration.

Example:

title: Slack

Description*

A short description for your integration.

Example:

description: Notify a channel or individual in Slack with real-time events from GitBook.

Organization*

The id or subdomain of the organization that owns this integration.

Example:

organization: gitbook

Visibility*

The visibility for your integration. Defaults to private. When set to private, only members of the organization that owns the integration are able to see or install the integration into a space.

Set the visibility to unlisted in order to share your integration install link with anyone.

Setting the visibility to public is only available by GitBook staff, and setting it to public will allow your integration to be listed on our marketplace.

See the Publishing section to learn more.

Example:

visibility: private

Scopes*

The scopes your integration has permissions for.

Example:

scopes:
  - space:content:read
  - space:content:write
  - space:metadata:read
  - space:metadata:write
  - space:views:read

{% hint style="danger" %} You may see the scope space:script:inject throughout GitBook owned integrations—This scope is only available for internal GitBook use.

Building integrations that inject JavaScript into a space or page are not possible to build at this time. {% endhint %}

Script

The main script to execute for your integration. Should contain the call to createIntegration().

Example:

script: ./src/index.ts

Blocks

Component block(s) referenced by name to render in the ( ⌘ + / ) menu. See createComponent() to learn more.

Example:

blocks:
  - id: example-block
    title: Exmple Block
    description: An example block for a GitBook Integration

Categories

A list of categories your integration falls into.

Example:

categories:
    - collaboration

Summary

A summary for your integration displayed on the installation page. Supports Markdown.

Example:

summary: |
    # Overview
    The GitBook Slack integration brings the power of GitBook to your Slack workspace. Your teams have instant access to your GitBook knowledge base, without leaving Slack.
    # Configure
    You can install the integration on a single space by clicking the integrations button in sub-navigation panel. If you prefer to install the Slack integration on multiple on all spaces you can enable this through organization settings. To configure the integration you will have to authorize the connection between Slack and GitBook. You can also select the default channel to post messages to.

Icon

A locally referenced icon for your integration. Asset must be located alongside the code for your integration

Example:

icon: ./assets/icon.png

Preview Images

A list of locally referenced assets to display on the installation page for your integration.

Example:

previewImages:
    - ./assets/slack-preview.png

External Links

A list of URLs to display on the installation page for your integration. Each link requires a label and a url.

Example:

externalLinks:
    - label: Documentation
      url: https://www.gitbook.com/integrations/slack
    - label: Slack Homepage
      url: https://slack.com/

Configurations

The configurations key allows you to specify specific steps and configurations for your integration through it's environment.

You're able to set up default configurations under the configurations.account key, and space-specific configurations through the configurations.space key.

Both of these configurations accept properties, which are named keys used to describe the different steps your user will go through as they install your integration. You can also name these properties in a required key to enforce certain configurations.

You can create as many properties as you would like, and can be of the following:

string

String configurations can be used to collect user input. You can use optional keys enum or completion_url to provide a list of items from a dropdown list instead than an input.

enum allows you to specify a list of items, while completion_url allows you to fetch options from an endpoint. See the Slack configuration to learn more.

string_property:
    type: string
    title: String Property
    description: A short description
    default: A default Value
    
    # Optional key to provide a list of options
    enum:
      - item 1
      - item 2
      - item 3
      - item 4
    
    # Optional key to fetch a list of entries from an endpoint.
    completion_url: /completion-endpoint

number

number_property:
    type: number
    title: Number Property
    description: A short description
    default: 1

boolean

boolean_property:
    type: boolean
    title: Boolean Property
    description: A short description
    default: true

button

Button configurations can be used if you need to set up an OAuth connection with a provider in order to use your integration. See createOAuthHandler() for more information.

button_property:
    type: button
    title: Button Property
    description: A short description
    button_text: Authorize
    callback_url: /callback-url

Example Configuration:

configurations:
    account:
        properties:
            oauth_credentials:
                type: button
                title: Connection
                description: Authorization between Slack and GitBook.
                button_text: Authorize
                callback_url: /oauth
            default_channel:
                type: string
                title: Default Channel
                description: Select a channel to post messages to, when none is configured for a specific space.
                completion_url: /channels
        required:
            - oauth_credentials
            - default_channel
    space:
        properties:
            channel:
                type: string
                title: Channel
                description: Select a channel to post messages related to this space.
                completion_url: /channels
            notify_content_update:
                type: boolean
                title: Notify Content Update
                description: Post a notification message every time the content of the space is updated.
                default: true
            notify_visibility_update:
                type: boolean
                title: Notify Visibility Update
                description: Post a notification message every time the visibility of the space is updated.
                default: true

Secrets

A list of secrets or environment variables that your integration might need in order to function. By default, environment variables are not loaded into GitBook's Manifest file.

We recommend using a package like dotenv-cli to include environment variables in your integrations configuration through an .env file when using the cli.

See the Linear integration for an example.

Example:

secrets:
    CLIENT_ID: ${{ env.CLIENT_ID }}

Installation & Configuration flow

During the installation flow, an event installation_setup is triggered as soon as the integration is installed for the first time. You can identify the configuration as being incomplete by checking environment.installation.status != 'active'.

This event (installation_setup) is triggered every time the user edits one property of the configuration. The status will become active once the configuration pass the validation with the schema.