Reference for extension.yaml

Your extension's specification file (extension.yaml) contains your extension's metadata, declares the resources created by the extension and the APIs and access required by the extension, and defines any user-configured parameters provided by the extension.

The tables on this page describe the fields available for an extension.yaml file.

Basic and identifying information

name: your-extension-name
version: 1.0.0         # Semantic versioning (semver)
specVersion: v1beta    # Always "v1beta"
license: Apache-2.0    # Always "Apache-2.0" (required to publish on extensions.dev)
billingRequired: true  # Always "true"

displayName: Your extension name
description: >-
  Description of the extension. (One or two
  sentences.)
icon: icon.png
tags: [tag, anothertag]

sourceUrl: https://github.com/your-org/your-repo   # GitHub repo URL
releaseNotesUrl: https://github.com/your-org/your-repo/blob/main/CHANGELOG.md

author:
  authorName: Your Company
  email: [email protected]
  url: https://example.com/
contributors:
  - authorName: Your Name
  - authorName: Another Contributor
    email: [email protected]
    url: https://github.com/their-org/
Basic fields
name
string
(required)

Identifier for the extension.

Can only contain lowercase letters, numbers, and dashes; 40 character limit.

Note: This value is used to generate the extension's instance ID (which is then used to generate the names of the extension's service account and the extension-specific resources).

version
string
(required)

Version of the extension.

Must follow semver versioning (for example, 1.2.0).
specVersion
string
(required)

Version of the Firebase Extensions specification.

Current value: v1beta
license
string
(optional)

License for the extension.

Your extension must be licensed using Apache-2.0.
billingRequired
boolean
(optional)

Whether the services used by the extension require a paid-tier Firebase billing account.

Always set to true.
displayName
string
(optional)

Friendly display name for the extension (3-5 words).

40 character limit.
description
string
(optional) 		Brief description of the task your extension performs (~1 sentence).
icon
string
(optional)

File to use as your extension's icon on extensions.dev and the Firebase console.

This file must be a square PNG between 512x512 and 1024x1024 pixels. Put the file in the same directory as extension.yaml; you cannot specify a subdirectory.

Keep the following guidelines in mind when designing an icon for your extension:

  • Select background and artwork colors that are appropriate for your brand.
  • Keep your icon colors simple, using only 2 colors. Multiple colors can make your icon visually overwhelming.
  • For the same reason, don't use gradients in your icon. Gradients are hard to discern at small sizes and make the icon visually complex.
  • Use simple, unique imagery that communicates your extension’s functionality.
  • If your company builds multiple extensions, don't use your logo as the icon. Users will have difficulty distinguishing between your extensions.
  • Make the artwork graphic and bold. Don't use delicate or elaborate art, which will not render well at smaller sizes.
  • Don't include words that explain what your extension does. Text is often illegible at smaller sizes.
tags
list of strings
(optional) 		Tags to help users discover your extension. The following tags map to categories on Extensions Hub: marketing, messaging, payments, search, shipping, social, utilities, ai
sourceUrl
string
(optional) 		Public URL where the extension directory can be accessed.
releaseNotesUrl
string
(optional) 		Public URL where the release notes for the extension can be accessed.
author
one author object
(optional)

Primary author and point of contact for the extension.

author:
  authorName: Your Company
  email: [email protected]
  url: https://example.com/
Author fields
authorName
string
(required)

Name of the author.

Can be a person, company, organization, etc.
email
string
(optional) 		Email address of the author.
url
string
(optional) 		Public URL where information about the author can be accessed.
contributors
list of author objects
(optional)

Any additional contributing authors for the extension.

contributors:
  - authorName: Your Name
  - authorName: Another Contributor
    email: [email protected]
    url: https://github.com/their-org/
Author fields
authorName
string
(required)

Name of the author.

Can be a person, company, organization, etc.
email
string
(optional) 		Email address of the author.
url
string
(optional) 		Public URL where information about the author can be accessed.

Firebase and Google Cloud APIs

These fields specify the Firebase and Google APIs the extension uses. When users install the extension, they can elect to automatically enable these APIs in their project.

apis:
  - apiName: apiname.googleapis.com
    reason: Explanation of why the extension uses this API
  - apiName: anotherapiname.googleapis.com
    reason: Explanation of why the extension uses this API
API fields
apiName
string
(required)

Name of the Google API

Must correspond to the Service name field as listed on each API's overview page (example) in the Google Cloud API Library

reason
string
(required) 		Brief description of why the extension needs to use this API

IAM roles

These fields specify the Cloud IAM roles the extension requires. The service account provisioned for the extension is granted these roles.

You can only specify one of the supported roles.

roles:
  - role: product.role
    reason: Explanation of why the extension needs this level of access
  - role: anotherproduct.role
    resource: projects/${project_id}/resource_type/*
    reason: Explanation of why the extension needs this level of access
Role fields
role
string
(required)

Name of the IAM role needed for the extension to operate

Must be one of the supported roles

reason
string
(required) 		Brief description of why the extension needs the access granted by this role
resource
string
(optional)

Limit the scope of the role to this resource.

If omitted, defaults to projects/${project_id}. See Reduce the scope of roles.

External services

These fields specify the non-Firebase and non-Google services the extension uses (typically REST APIs). The Firebase Extensions platform does not provide any means of automatically enabling or performing authorization for these services.

externalServices:
  - name: Example API
    pricingUri: https://developers.example.com/pricing
  - name: Another Example API
    pricingUri: https://developers.example.com/pricing
External services fields
name
string
(required) 		Name of the external service needed for the extension to operate
pricingUri
string
(required) 		URI to pricing information for the service

User-configurable parameters

These fields define the parameters that the extension makes available for users to configure.

params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      What do you want to set PARAM_ID to?
      This is a longer description of the parameter, often phrased as a prompt
      to the user.
  - param: ANOTHER_PARAM_ID
    label: Short description of the parameter
    description: >
      What do you want to set ANOTHER_PARAM_ID to?
      This is a longer description of the parameter.
    example: example-input
    validationRegex: "^[a-zA-Z][a-zA-Z-]*[a-zA-Z]?$"
    validationErrorMessage:
      Must be a hyphen-delimited string of alphabetic characters
    default: default-value
    required: false
    immutable: true
Parameter fields
param
string
(required) 		Name of the parameter. You use this name to reference the parameter value in code.
label
string
(required) 		Short description for the parameter. Displayed to the user when they're prompted for the parameter's value.
description
string
(optional)

Detailed description for the parameter. Displayed to the user when they're prompted for the parameter's value.

Supports Markdown.
example
string
(optional) 		Example value for the parameter.
default
string
(optional) 		Default value for the parameter if the user leaves the parameter's value blank.
validationRegex
string
(optional) 		Regular expression for validation of the parameter's user-configured value. Google RE2 syntax.
validationErrorMessage
string
(optional) 		Error message to display if regex validation fails.
required
boolean
(optional) 		Defines whether the user can submit an empty string when they're prompted for the parameter's value. Defaults to true.
immutable
boolean
(optional)

Defines whether the user can change the parameter's value after installation (such as if they reconfigure the extension). Defaults to false.

Note: If you define a "location" parameter for the deployed functions of your extension, set this field to true.
type
string
(optional) 		The parameter type. Special parameter types might have additional requirements or different UI presentation. See the following sections.

Selectable and multi-selectable parameters

Selectable and multi-selectable parameters prompt users to choose from a list of predefined options.

params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      Do you want to enable the option?
    type: select
    options:
      - label: Yes
        value: true
      - label: No
        value: false
  - param: ANOTHER_PARAM_ID
    label: Short description of the parameter
    description: >-
      Which options do you want to enable?
    type: multiselect
    options:
      - value: red
      - value: green
      - value: blue
Multiple-choice parameter fields
type
string

select or multiselect

Specifies that the parameter can be one value (select) or several values (multiselect) selected from a set of predefined choices
options
list of options
(required)

The options from which the user can choose

Option fields
value
string
(required) 		One of the values the user can choose. This is the value you get when you read the parameter value in code.
label
string
(optional) 		Short description of the selectable option. If omitted, defaults to value.

Selectable resource parameters

Selectable resource parameters prompt users to select a resource (database instance, storage bucket, etc.) from their project.

params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      Which resource do you want to use?
    type: selectresource
    resourceType: product.googleapis.com/ResourceType
Resource parameter fields
type
string

selectresource

Specifies that the parameter represents a project resource
resourceType
string
(required)

The type of resource to prompt the user to select.

Valid values:

  • storage.googleapis.com/Bucket
  • firestore.googleapis.com/Database
  • firebasedatabase.googleapis.com/DatabaseInstance

However, only Cloud Storage buckets currently have a selection UI (other resource types are presented as free-form text input fields).

Secret parameters

User-provided secret values (such as API keys) are handled differently:

  • Secret values are stored using Cloud Secret Manager. Only authorized clients (such as an installed instance of an extension) can access these values.
  • When users are prompted to provide these values, their input is not displayed.
params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      What is the secret value?
    type: secret
Secret parameter fields
type
string

secret

Specifies that the parameter is a secret value

Cloud Function resources

These fields declare the Cloud Functions included in an extension. The resource declaration syntax looks a little different between 1st-gen and 2nd-gen functions, which can coexist in an extension.

1st-gen Cloud Functions

resources:
  - name: functionName
    type: firebaseextensions.v1beta.function
    description: >-
      Description of what the function does. (One or two
      sentences.)
    properties:
      runtime: runtime-version
      eventTrigger:
        eventType: google.product.event
        resource: projects/_/resource/specifier
Resource fields
name
string
(required)

User-friendly name for the exported function.

If you don't specify the entryPoint property (see below), this value must match the name of the function in your functions source code.

The final name of the deployed function will be in the following format: ext-extension-instance-id-name.
type
string
(required) 		For a 1st-gen function resource: firebaseextensions.v1beta.function
description
string
(required)

Brief description of what task the function performs for the extension.
properties
(required)

1st-gen Cloud Functions properties. The most important properties are listed below, but you can find the complete list in the Cloud Functions reference.

Properties
location
(optional)

Location to which to deploy the function. Defaults to us-central1
entryPoint
(optional) 		Name of the exported function within your functions source code that the extension should look for. Defaults to the value of name, above.
sourceDirectory
(optional)

Directory that contains your package.json at its root. The file for your functions source code must be in this directory. Defaults to functions

Note: The main field of package.json specifies the file for your functions source code (like index.js).
timeout
(optional)

The function's maximum execution time.

  • Default: 60s
  • Max value: 540s
availableMemoryMb
(optional)

Amount of memory in MB available for the function.

  • Default: 256
  • Valid values: 128, 256, 512, 1024, and 2048
runtime
(recommended)

Runtime environment for the function.
httpsTrigger
or
eventTrigger
or
scheduleTrigger
or
taskQueueTrigger
(one of these function trigger types is required) 		See Write Cloud Functions for an extension for specific information about each trigger type.

2nd-gen Cloud Functions

resources:
  - name: functionName
    type: firebaseextensions.v1beta.v2function
    description: >-
      Description of what the function does. (One or two
      sentences.)
    properties:
      buildConfig:
        runtime: nodejs16
      serviceConfig:
        availableMemory: 512M
      eventTrigger:
        eventType: google.firebase.firebasealerts.alerts.v1.published
        triggerRegion: global
        eventFilters:
          - attribute: alerttype
            value: crashlytics.newFatalIssue
Resource fields
name
string
(required)

User-friendly name for the exported function.

If you don't specify the entryPoint property (see below), this value must match the name of the function in your functions source code.

The final name of the deployed function will be in the following format: ext-extension-instance-id-name.
type
string
(required) 		For a 2nd-gen function resource: firebaseextensions.v1beta.v2function
description
string
(required)

Brief description of what task the function performs for the extension.
properties
(required)

2nd-gen Cloud Functions properties. The most important properties are listed below, but you can find the complete list in the Cloud Functions reference.

Properties
location
(optional)

Location to which to deploy the function. Defaults to us-central1
sourceDirectory
(optional)

Directory that contains your package.json at its root. The file for your functions source code must be in this directory. Defaults to functions

Note: The main field of package.json specifies the file for your functions source code (like index.js).

There are also three object-type fields with their own properties:

buildConfig properties
buildConfig.runtime
(recommended)

Runtime environment for the function.
buildConfig.entryPoint
(optional) 		Name of the exported function within your functions source code that the extension should look for. Defaults to the value of name, above.
serviceConfig properties
serviceConfig.timeoutSeconds
(optional)

The function's maximum execution time.

  • Default: 60
  • Max value: 540
serviceConfig.availableMemory
(optional) 		The amount of memory available for a function. Defaults to 256M. Supported units are k, M, G, Mi, Gi. If no unit is supplied, the value is interpreted as bytes.
eventTrigger properties
eventTrigger.eventType
(required) 		The type of event to listen for. See Write Cloud Functions for an extension for the event types available for each product.
eventTrigger.eventFilters
(optional) 		Filters that further limit the events to listen to. For example, you could only listen to events matching a specific resource pattern. See Write Cloud Functions for an extension for information on filtering each type of event.
eventTrigger.channel
(optional) 		The name of the channel associated with the trigger in projects/{project}/locations/{location}/channels/{channel} format. If you omit this property, the function will listen for events on the project's default channel.
eventTrigger.triggerRegion
(optional) 		The trigger will only receive events originating in this region. It can be the same region as the function, a different region or multi-region, or the global region. If not provided, defaults to the same region as the function.

Lifecycle events

Lifecycle events let you specify functions that will run when a user installs, updates, or configure an instance of your extension. See Handle your extension's lifecycle events.

lifecycleEvents:
  onInstall:
    function: myTaskFunction
    processingMessage: Describes the task being completed
  onUpdate:
    function: myOtherTaskFunction
    processingMessage: Describes the task being completed
  onConfigure:
    function: myOtherTaskFunction
    processingMessage: Describes the task being completed
Lifecycle event fields
onInstall
(optional)

Specifies a function that runs when a user installs the extension.

Function specification
function
string
(required)

Name of the task queue-triggered function that will handle the event.

This function must be declared in the resources section and have taskQueue defined.
processingMessage
string
(required) 		Message to display in the Firebase console while the task is in progress.
onUpdate
(optional)

Specifies a function that runs when a user updates the extension.

Function specification
function
string
(required)

Name of the task queue-triggered function that will handle the event.

This function must be declared in the resources section and have taskQueue defined.
processingMessage
string
(required) 		Message to display in the Firebase console while the task is in progress.
onConfigure
(optional)

Specifies a function that runs when a user re-configures the extension.

Function specification
function
string
(required)

Name of the task queue-triggered function that will handle the event.

This function must be declared in the resources section and have taskQueue defined.
processingMessage
string
(required) 		Message to display in the Firebase console while the task is in progress.

Custom events (Eventarc)

Custom events are events that your extension emits to allow users to insert their own logic into your extension. See the Eventarc section in Add user hooks to an extension.

events:
  - type: publisher-id.extension-name.version.event-name
    description: Description of the event
  - type: publisher-id.extension-name.version.another-event-name
    description: Description of the other event
Custom event fields
type
string
(required) 		The type identifier of the event. Construct the identifier out of 3-4 dot-delimited fields: the publisher ID, extension name, and event name fields are required; the version field is recommended. Choose a unique and descriptive event name for each event type you publish.
description
string
(required) 		Description of the event.