Configurations

Learn about the different configuration options your app or integration can use
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
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 first install the integration, 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.
Integrations - Previous
Overview
Next - Integrations
Reference
Last modified 20d ago