Ask or search…
K
Comment on page

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
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.

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
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.
Last modified 4mo ago