Snap-in manifest

The following section is for version 2 of the manifest specification. For the previous version, see Manifest V1.

The snap-in manifest is what the developers write to define a snap-in. The manifest has the following sections:

Version

The version specifies the manifest version. The following documentation is for version 2 of the manifest. In the manifest, specify the following:

1 version: 2

Keyrings

Keyrings are secret tokens used to make calls to external systems. They can be categorized either as organization scoped or user scoped. Keyrings are specified in the manifest with the following syntax:

1 keyrings:
2   organization:
3     - name: <The name of the keyring that should be used for the snap-in.>
4       description: <A description of the functions of this keyring.>
5       display_name: <The name shown to the user.>
6       types: <List of all keyring types that can be selected by the end-user.>
7 
8     - name: <The name of the keyring that should be used for the snap-in.>
9       description: <A description of the functions of this keyring.>
10       display_name: <The name shown to the user.>
11       types: <List of all keyring types that can be selected by the end-user.>
Show more

For example:

1 keyrings:
2   organization:
3     - name: my-secret-token
4       description: The secret tokens stores the keys to the kingdom
5       types:
6         - devrev_pat
7         - snap_in_secret
8       display_name: Your secret token
Show more

Keyrings defined in the manifest can be provided in the snap-in configuration screens and are made available to the function. The keyring type is used to determine the type of the keyring and restricts selection on configuration screen to valid types.

To view the supported connection types, see Keyrings.

Developer keyrings

Developer keyrings are provided by the snap-in version developer. They're available across all installations and hidden from the installer. Only the secret string type can be used as developer keyrings.

1 developer_keyrings:
2   - name: <The name of the keyring that should be used for the snap-in.>
3     description: <A description of the functions of this keyring.>
4     display_name: <The name shown to the developer.>
5 
6   - name: <The name of the keyring that should be used for the snap-in.>
7     description: <A description of the functions of this keyring.>
8     display_name: <The name shown to the developer.>
Show more

For example:

1 developer_keyrings:
2   - name: mongodb
3     description: Store usage statistics
4     display_name: MongoDB PAT
5 
6   - name: discord
7     description: Access additional discord's API
8     display_name: Discord PAT
9 
Show more

Select the developer connection while creating snap_in_version. The DevRev CLI automatically detects such keyrings in the manifest and asks for them:

1 devrev snap_in_version create-one --manifest manifest.yaml
2 Please provide mapping for the developer keyrings:
3 Use the arrow keys to navigate: ↓ ↑ → ←
4 ? mongodb:
5   ▸ mongodb
6     discord

Developer keyrings can only be created in the UI. They're of the Snap-in Secret type.

Event sources

Event sources can be categorized as "organization" level and "user" level. Currently, only organization level event sources are supported. Event sources are specified in the manifest with the following syntax:

1 event_sources:
2       organization:
3         - name: <The name of the event-source that should be used for the snap-in.>
4           description: <A description of the functions of this event-source.>
5           display_name: <The name shown to the user.>
6           type: <An enum specifying the type of source to create.>
7           setup_instructions: <Instructions shown to the end user as an option.>
8           config:
9       <An object containing event source configuration.>
10 
11         - name: <The name of the event-source that should be used for the snap-in.>
12           description: <A description of the functions of this event-source.>
13           display_name: <The name shown to the user.>
14           type: <An enum specifying the type of source to create.>
Show more

Refer to Event sources for a checklist of supported event sources and their corresponding event types.

Refer to the webhook-event-request docs for a list of supported webhooks.

For example:

1 event_sources:
2   organization:
3     - name: devrev-webhook
4       description: Events coming from GitHub
5       display_name: DevRev webhook
6       type: devrev-webhook
7       config:
8         event_types:
9           - work_created
Show more

Inputs

Globals are implemented using per-object schemas, which is a customization term to store custom schemas in line with the object. Each global's schema maps to a FieldDescriptor.

Globals are defined as:

1 inputs:
2   organization:
3     - name: <The name of the input.>
4       description: <A description of the functions of this input.>
5       field_type: <The supported input types.>
6       id_type: <If the field type is id, so what are the supported object types whose ids this input can store?>
7       is_required: <Is this input required?>
8       default_value: <The default value for this input>
9       ui:
10         display_name: <Input field display name.>
Show more

To view supported global types, refer to the schema field descriptor.

Tags

In the manifest, pass the name and description of the tag.

For example:

1 tags:
2   - name: github.branch.name
3     description: Tag storing github branch name.

Commands

In the manifest, you need to specify the command's name, its namespace, and the surfaces where it can appear, such as comment discussions. It also specifies the UI description, usage hints, and the function to be triggered when the command is invoked.

1 commands:
2   - name: summarize
3     namespace: turing
4     description: Summarizes the conversation
5     surfaces:
6       - surface: discussions
7         object_types:
8           - conversation
9     usage_hint: "number of tokens to generate"
10     function: generate_summary
Show more

For commands, the <name, namespace> pair should be unique across the Org in which it's installed.

Functions

In the manifest, pass the name and description of the functions.

1 functions:
2   - name: create_work
3     description: Function containing logic to create a DevRev work.
4 
5   - name: post_message
6     description: Function containing logic to post a message on newly created work.

For functions, you also need to provide the actual JS/TS code behind this function. Refer to the README in the provided template.

Automations

Automation refers to linking events from the event sources to your functions.

Automations are defined as:

1 automations:
2   - name: <The name of the automation.>
3     source: <Name of the event source specified in the manifest from which the events coming in could trigger this automation.>
4     event_types:
5       - <Event from the source on which you need to run the code.>
6     function: <Specifies which function should be run from the manifest.>

For custom event sources, whatever event key you emit from your policy, the event name will be custom:<your event key>.