How to Build Your Own Google Workspace Add-On

As a Google user, I never paid much attention to Add-ons until I started using Keep and Tasks on a regular basis. These apps can be quickly accessed in a taskbar on the far right side of the screen in Gmail and most other Google apps. I've really enjoyed having my notes and tasks instantly available since I always have a tab open to Gmail.

Then I got to wondering—what's this big "+" for, and what else can I have at my fingertips? That's when I discovered the Workspace Marketplace with its impressive selection of productivity tools.

But as someone who likes to tinker and build, I wondered what it would take to build my own little app. Building apps for Apple and Android has become so accessible with AI coding tools like Cursor and Lovable—surely a Workspace app wouldn't be too hard.

To my delight, it's actually very easy to build your own apps, especially when using an AI to guide you through the unfamiliar JavaScript library used for building and configuring objects in your app. What's particularly nice about these Workspace Add-on apps is that they can be deployed for personal use (and across your organization) instantly without having to go through a verification and review process.

Enough backstory—let's look at the steps to build your own Add-on using Google Apps Script.

Want to see an example? Search for "Clear Slate Ticket Creator" in the Workspace Marketplace. It's an email ticket creator to track support cases—built entirely with Apps Script.

What You'll Build

By the end of this guide, you'll have:

• A working Google Workspace Add-on
• A custom sidebar app that appears in Gmail, Drive, or other Google apps
• Internal distribution to your organization (no public review required)

Prerequisites

Before starting, make sure you have:

• A Google account (personal or Workspace)
• Basic familiarity with JavaScript (AI assistants can help here)
• Access to Google Cloud Console for your organization

Step 1: Create the Apps Script Project

The easiest way to build a Workspace Add-on is via Google Apps Script (GAS), which uses a Card-based framework—no HTML or CSS required.

1. Go to script.google.com and click New Project
2. Click on Project Settings (gear icon) on the left sidebar
3. Check the box: Show 'appsscript.json' manifest file in editor
4. Return to the Editor (code icon)

You will now see appsscript.json in your file list. This is the configuration file that tells Google what your Add-on does.

Step 2: Configure the Manifest

The manifest file (appsscript.json) is the "blueprint" of your Add-on. It tells Google where your app should appear and what permissions it needs.

Add Scopes: Explicitly list every OAuth scope your script uses in the oauthScopes array. Find the scopes you need by clicking Project Settings > Scopes after you’ve written some code, or by checking the "View > Show manifest" option.

Replace the default code with this starter configuration:

{
  "timeZone": "America/New_York",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "My Internal Tool",
      "logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/extension_black_24dp.png",
      "homepageTrigger": {
        "runFunction": "onHomepage",
        "enabled": true
      }
    },
    "gmail": {},
    "drive": {}
  },
  "oauthScopes": [
    "https://www.googleapis.com/auth/workspace.addons.display"
  ]
}

Key Configuration Options

• name: The display name of your Add-on
• logoUrl: URL to your Add-on's icon (24x24 pixels recommended)
• homepageTrigger: The function that runs when users open your Add-on
• gmail/drive: Include these objects to enable your Add-on in those apps
• oauthScopes: The permissions your Add-on needs

Tip: Find the scopes you need by clicking Project Settings > Scopes after you've written some code. Explicitly list every OAuth scope your script uses in the oauthScopes array.

Step 3: Add the Script Logic

Now write the JavaScript that builds your visual interface. Click on the Code.gs file in the editor and paste the following:

/**
 * This function runs when you click the Add-on icon in the sidebar.
 */
function onHomepage(e) {
  // Create a section with your message
  var section = CardService.newCardSection()
    .addWidget(CardService.newTextParagraph()
      .setText("Your cool app logic here!"));

  // Build the card and return it to the UI
  var card = CardService.newCardBuilder()
    .setHeader(CardService.newCardHeader()
      .setTitle("Welcome")
      .setSubtitle("Ready to build?"))
    .addSection(section)
    .build();

  return card;
}

The CardService API provides widgets like text paragraphs, buttons, text inputs, selection inputs, and more. You can build surprisingly rich interfaces without touching HTML or CSS.

Step 4: Link to a Google Cloud Project

By default, Apps Script uses a "hidden" project. For internal distribution, you must link it to a Standard Google Cloud Project.

1. Go to the Google Cloud Console
2. Create a New Project
3. Go to APIs & Services > OAuth Consent Screen
4. Set User Type to Internal (this ensures only people in your organization can use it)
5. Copy your Project Number (found on the Dashboard)
6. In Apps Script, go to Project Settings > Change Project and paste your Project Number

Step 5: Enable the Marketplace SDK

To make the Add-on "installable" for your team, you must enable the Marketplace interface.

1. In your Google Cloud Console, search for Google Workspace Marketplace SDK and click Enable
2. Under App Configuration:
   • Set App Visibility to Private (My Organization)
   • Select the apps you want to extend (Gmail, Sheets, etc.)
   • Provide the Deployment ID from Apps Script (found under Deploy > Test Deployments)
3. Under Store Listing, fill in the basic details (name, description, icons)

Note: Since it's private, you don't need a professional promo video or high-end assets.

Step 6: Test and Deploy

Before a full rollout, test the Add-on using a Test Deployment.

1. In Apps Script, click Deploy > Test deployments
2. Click Install
3. Open the host app (e.g., Gmail) and look for your Add-on icon in the right-side panel

Once satisfied, click Deploy > New deployment to create a stable version.

Step 7: Internal Distribution

To give the rest of your organization access, you have two options:

Option A: Self-Install

Users in your organization can find the Add-on in the "Internal Apps" section of the Google Workspace Marketplace.

Option B: Admin Force-Install

A Google Workspace Admin can go to Admin Console > Apps > Google Workspace Marketplace apps and "Admin Install" the app for specific departments or the entire company.

Tips for Building with AI

Since Apps Script uses a specific Card-based framework, AI coding assistants are incredibly helpful for:

• Generating widget layouts and card structures
• Understanding the CardService API methods
• Debugging scope and permission issues
• Building form inputs and handling submissions

Simply describe what you want your Add-on to do, and let the AI generate the boilerplate code. Then iterate from there.

What's Next?

Now that you know how to build a basic Add-on, consider exploring:

• Context-aware triggers: Show different content based on the selected email or file
• Form inputs: Collect user input with text fields, dropdowns, and date pickers
• External API calls: Connect your Add-on to external services using UrlFetchApp
• Card navigation: Build multi-step wizards with card stacks

The Google Apps Script documentation has extensive examples and reference material to help you build more sophisticated tools.