Snap-in V1 manifest

The following guide is for the version 1 of the manifest spec. For the latest version, refer to Manifest.

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

Version

The version of the manifest. The below documentation is for version 1 and should be specified in the manifest as:

1version: 1

Connections

Connections are specified in the manifest with the following syntax:

1connections:
2  - name: <connection name to use in the snap-in>
3    description: <detail about what this connection is used for>
4    display_name: <name shown to the end-user>
5    types: <list specifying what all types of connections could be selected by the end user for this connection>
6
7  - name: <connection name to use in the snap-in>
8    description: <detail about what this connection is used for>
9    display_name: <name shown to the end-user>
10    types: <list specifying what all types of connections could be selected by the end user for this connection>

Example:

1connections:
2  - name: github
3    description: GitHub token to be used to get PR details
4    types:
5      - devrev-github-pat
6      - devrev-github-oauth

Service that stores these secrets and has the business logic to refresh tokens, when applicable. Here is the list of currently supported connection types - Connections

Developer connections

Developer connections are defined during the development by the snap-in developer. They are available across all installations and invisible to the installer. Only snap-in secret string type is supported for developer connections.

1developer_connections:
2  - name: <connection name to use in the snap-in>
3    description: <detail about what this connection is used for>
4    display_name: <name shown to the developer>
5
6  - name: <connection name to use in the snap-in>
7    description: <detail about what this connection is used for>
8    display_name: <name shown to the developer>

Example:

1developer_connections:
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

The developer connection can be selected while creating the snap_in_version. DevRev CLI detects the developer connections in the manifest and prompts for them:

$devrev snap_in_version create-one --manifest manifest.yaml
>Please provide mapping for the developer connections:
>Use the arrow keys to navigate: ↓ ↑ → ←
>? mongodb:
>  ▸ mongodb
>    discord

Developer connections can only be created in the UI. They are of type “snap-in Secret”.

Event sources

Event sources are specified in the manifest with the following syntax:

1    event-sources:
2      - name: <event-source name to use in the snap-in>
3        description: <detail about this event-source>
4        display_name: <name shown to the end-user>
5        type: <enum specifying what type of the source should be created>
6        setup_instructions: <optional instructions shown to the end-user>
7        config:
8     <an object containing config specific to the event source>
9
10      - name: <event-source name to use in the snap-in>
11        description: <detail about this event-source>
12        display_name: <name shown to the end-user>
13        type: <enum specifying what type of the source should be created>

Here is the list of supported event sources.

Example:

1event-sources:
2  - name: devrev-webhook
3    description: Events coming from GitHub
4    display_name: DevRev webhook
5    type: devrev-webhook
6    config:
7      event_types:
8        - work_created

Globals

Globals are implemented today 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.

The definition of globals looks like this:

1globals:
2  - name: <name of the global>
3    description: <its description - what is it supposed to do>
4    devrev_field_type: <type of the global>
5    devrev_id_type: <if the field type is id, then what are the supported object types whose id this global can store>
6    is_required: <is this a required input?>
7    default_value: <the default value for this global>
8    ui:
9      display_name: <display name for the input field>

Tags

Define a tag by passing just the name and description of the tag.

Example:

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

Commands

In the manifest, you need to specify the name of the command, its namespace, the surfaces where it can show up (such as comment discussions), a description that can show up on the UI, usage hints, and the function to be triggered when the command is invoked.

1commands:
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

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

Functions

In the manifest, all you need to tell is the name of the function, and its description, just like tags:

1functions:
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, for that, you can refer to the README in the provided template.

Automations

Automation is where you would link events from the event sources to your function. The definition of automations looks like this:

1automations:
2  - name: <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: <name of the function specified in the manifest which should be run>

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