Installing FastStore WebOps

This guide walks you through installing and configuring FastStore WebOps so you can deploy Sales App extensions. The process is self-service: you can complete it using this documentation. If you run into issues, open a support ticket (see Support below).

Note

You do not need a FastStore storefront to use WebOps for Sales App extensions. The Sales App extension build is independent from the store build.

Tip

If you already have a FastStore project and only need to connect it to WebOps, you can skip the setup steps below and run in your project directory: npx @vtex/fsp-cli init --from-discovery. This syncs the existing configuration. For a brand-new setup, continue with the steps below.

Prerequisites

Before starting, have the following at hand:

Information	Description
VTEX account	Your VTEX account name (e.g. store-a)
GitHub organization	The GitHub org where your repository lives (or where you will create it)
Repository	An existing repository with your extension code, or you can create a new one during the onboarding

Step 1: Check for an existing WebOps installation

1. In your VTEX Admin, go to Storefront → FastStore WebOps.
2. If the WebOps page loads and shows your project/repository, WebOps is already installed and configured. You can skip to Step 4: Verification to confirm extensions build and run.
3. If you don’t see FastStore WebOps or the page indicates no project is linked, continue to Step 2.

You can also check whether the WebOps app is installed on your account via the VTEX CLI (e.g. listing installed apps) or by asking your account administrator.

Step 2: Install FastStore WebOps on your account

1. Log in to the VTEX account where you want to deploy extensions:

   vtex login ACCOUNT_NAME

   Replace ACCOUNT_NAME with your VTEX account name.

2. Install the WebOps app:

   vtex install vtex.webops@1.0.0

3. After installation, open Storefront → FastStore WebOps in VTEX Admin. You should see the WebOps dashboard; you will link the GitHub App and repository in the onboarding (Steps 3 and 4).

Step 3: Install the FastStore WebOps GitHub App

WebOps needs access to your GitHub repository to trigger builds on push. In the normal flow, you install the FastStore WebOps GitHub App during the onboarding in Step 4—the Installation ID and repository details are captured automatically. You do not need to look up Installation ID or repository ID for that.

You only need to obtain the Installation ID or repository ID manually if you cannot complete the WebOps onboarding—for example, if you already have a FastStore project or existing content in Headless CMS that must not be overwritten (the full onboarding can overwrite or remove content in Headless CMS). In that case, install the GitHub App below, obtain the IDs using the optional sections that follow, and open a support ticket so the team can link your project without running the store onboarding. See When to open a support ticket.

Installing the GitHub App

1. Open the FastStore WebOps GitHub App page on GitHub.
2. Click Configure (or Install if you haven’t installed it before).
3. Choose All repositories or Only select repositories and select the repo that contains your extension code.
4. Complete the installation (e.g. Install or Save).

Caution

Grant the app access to the correct organization and repository. Without the right permissions, WebOps will not receive push events and builds will not run.

Obtaining the WebOps Installation ID (only when you cannot do the full onboarding)

The Installation ID is a numeric ID that identifies this installation of the FastStore WebOps GitHub App. The WebOps onboarding (Step 4) captures it automatically when you install the app and select the repository. Only look it up manually if you cannot run the full onboarding (e.g. you have existing FastStore or Headless CMS content to preserve)—then provide it when you open a support ticket so the team can link your project.

Option A — From the installation URL (recommended)

1. After installing the app, go to your GitHub organization (or user) Settings.
2. In the left sidebar, open Developer settings → GitHub Apps.
3. Under Installed GitHub Apps, find FastStore WebOps and click Configure (or open the app and go to its installation settings).
4. In the browser address bar, the URL will look like: https://github.com/organizations/YOUR_ORG/settings/installations/INSTALLATION_ID or https://github.com/settings/installations/INSTALLATION_ID
5. The number at the end of the path (e.g. 12345678) is your Installation ID. Copy it for the next step.

Option B — From the “Install App” page

1. Go to FastStore WebOps GitHub App.
2. If you’re an org admin, you may see an Install or Configure link that takes you to the installation page.
3. The installation page URL often has the form: https://github.com/apps/faststore-webops/installations/new or .../installations/INSTALLATION_ID
4. When you see a URL that ends with a number (e.g. .../installations/12345678), that number is the Installation ID.

If you need to provide the Installation ID (e.g. to support), use one of the methods above to find it.

Finding the GitHub repository ID (only when you cannot do the full onboarding)

The repository ID is a numeric ID assigned by GitHub to your repository. WebOps gets it automatically during onboarding. Only look it up if you cannot run the full onboarding and are opening a support ticket—support may ask for it.

1. Open your repository on GitHub.
2. Go to Settings (repository settings, not organization).
3. At the bottom of the General section you’ll see Repository ID (numeric). Copy it.

Alternatively, you can get it via the GitHub API: GET https://api.github.com/repos/OWNER/REPO — the response includes "id": <repository_id>.

Step 4: Configure the repository in WebOps

Today, the repository is linked to WebOps through the WebOps onboarding in the dashboard. There is no separate form to manually enter organization, repository name, or IDs — the onboarding installs the FastStore WebOps GitHub App (after you authenticate with GitHub), lets you create a new repository or select an existing one, and stores the organization, repository, and Installation ID automatically.

Tip

After onboarding, run npx @vtex/fsp-cli init --from-discovery in your repository to sync the discovered configuration. The only caveat: the full store onboarding in the WebOps UI can overwrite or remove existing content in Headless CMS (hCMS). If you already have important content in hCMS for a storefront, be aware of that before running it. If that’s not a concern (e.g. new project, or Sales App only with no FastStore project in hCMS), just do the onboarding normally and then run the CLI command above.

1. In VTEX Admin, go to Storefront → FastStore WebOps.
2. In the WebOps dashboard, start the onboarding flow (e.g. from the main screen or the option to connect/set up a project).
3. When prompted, authenticate with GitHub and install the FastStore WebOps GitHub App for your organization (or account).
4. Create a new repository or select an existing one when the onboarding asks you to choose the repo. WebOps will store the organization, repository, and Installation ID automatically — you do not need to look up or enter repository ID or Installation ID.
5. Complete the onboarding steps. After that, the repository is configured and WebOps can run builds on push.

You do not need to use the sections Obtaining the WebOps Installation ID and Finding the GitHub repository ID unless you cannot complete the onboarding (e.g. you have existing Headless CMS content to preserve)—in that case, get those IDs and open a support ticket.

Step 5: How Sales App extension builds work

After the repository and Installation ID are configured:

• Pushing to the configured branch (typically main) triggers a production build.
• WebOps detects the Sales App module in the repo and builds it when it has changes.
• When the build finishes, WebOps deploys the extensions to VTEX. No separate manual build step is required.

For more detail, see Deploying Sales App extensions.

Step 6: Verification

Caution

Extension points require a feature flag. An internal step is needed to enable the enable-extension-points feature flag for your account. If you don’t see the extension point after deploying, this configuration may be missing—request that the team enable the feature flag for your account (e.g. via a support ticket to the PS FastStore group; see When to open a support ticket).

1. Make a small change in your Sales App extension code and push to the production branch.
2. In Storefront → FastStore WebOps → Deploys, confirm that a new deployment appears and completes successfully.
3. Open your Sales App in the browser and confirm that the extension behaves as expected (e.g. custom UI or logic is visible and working).

If the build fails, check Handling build failures or run the build locally:

yarn fsp build <account-name> sales-app

---

Rollback

Rollback here means reverting the Sales App to a state without the extension deployment—i.e. removing the effect of the extension from the app.

Option 1: Revert via Git (recommended)

1. In your repository, revert the commits that added or changed the extension (e.g. git revert or restore a previous version of the extension code).
2. Push the revert to the production branch (e.g. main).
3. WebOps will run a new build and deploy. After it succeeds and caches propagate (typically within a few minutes), the app will run without the reverted extension changes.

This keeps WebOps installed and only removes the latest extension changes.

Option 2: Remove the WebOps installation (full rollback)

Use this if you need to fully remove WebOps from the account (e.g. stop all extension builds and deployments).

1. In VTEX Admin, go to Storefront → FastStore WebOps and remove or unlink the repository/project if the UI allows it (see your WebOps dashboard options).
2. Uninstall the WebOps app from the account. This is usually done from the VTEX App Store or via CLI (e.g. uninstall the vtex.webops app). Confirm the exact step in the current VTEX/WebOps documentation.
3. Optionally, uninstall the FastStore WebOps GitHub App from your GitHub organization or account so it no longer has access to your repositories.
4. Verify that the Sales App works as expected without extensions—e.g. open the app and confirm that the default experience loads and that no custom extension code is running.

Caution

Removing WebOps means no more automatic builds or deployments for extensions from that repository. To deploy extensions again, you will need to reinstall and reconfigure WebOps following this guide.

---

When to open a support ticket

Installation and initial setup are self-service and do not require a ticket. Open a ticket only when:

• You cannot run the full WebOps onboarding because you already have a FastStore project or existing Headless CMS content that must not be overwritten—in that case, install the GitHub App, obtain the Installation ID (and repository ID if asked), and request that the team link your project manually.
• You followed this guide and a step fails (e.g. WebOps doesn’t install, or the Installation ID is not accepted).
• Builds fail and you cannot resolve them using the Handling build failures instructions and local build commands.
• You need to roll back and something doesn’t work as described.

Open the ticket via your usual support channel (e.g. Zendesk) and direct it to the PS FastStore group. Include:

• Account (VTEX account name)
• Domain (e.g. the Sales App URL affected)
• Expected behavior vs actual behavior
• Evidence: screenshots, error messages, or a .har file if relevant
• How to reproduce the issue

For more on the WebOps dashboard and features, see the FastStore WebOps documentation on the VTEX Developer Portal.