Partner Deployment Guide

Overview

Are you a developer that wants to deploy your app to the Decent Portal? Good! You're in the right place. This guide should have what you need.

Our deployment system was specifically designed for secure, private, local-first web apps following Decent sensibilities. Your app will be available via a fast, global CDN network, mirrored across six continents. (Sorry, Antartica users - it might be slow for you!)

Table of Contents

Configuration Steps

Prerequisites

Before you start, you’ll need:

  • A public GitHub repository with a Decent-compatible project (created using create-decent-app)
  • An app name, shared with Decent Apps for provisioning
  • A Decent API key

You’ll get your API key and app name after coordinating with someone at Decent Apps. If you're unsure who to contact, email launch@decentapps.net. We will provision your account such that your API key will permit deployment operations for your app.

Keep your Decent API key secure. Never commit the Decent API key to a public repository.

Configuring Your App

  1. Open a terminal and navigate to your project root (it should contain a package.json file).
  2. Run npm run build and verify it completes without errors and outputs to ./dist (default behavior for create-decent-app-generated projects).
  3. Run npm install decent-portal@latest to install the latest Decent Portal library.
  4. Run npm run setup-portal-workflows to generate GitHub workflow files in .github/workflows/.

After step 4, GitHub will try to deploy your app on each push. These attempts will fail safely until you finish repository configuration.

Configuring Your GitHub Repository

  1. In the GitHub portal, open your repository and go to Settings (repository-level).
  2. Under Secrets and Variables > Actions, add a new secret:
    • Name: DECENT_API_KEY
    • Value: your Decent API key
  3. Under Secrets and Variables > Variables, add:
    • Name: APP_NAME
    • Value: the exact app name used during provisioning

Reminder: Keep your API key private. Never commit it, even temporarily.

Using Deployment Workflows

Once configured, you can use three workflows:

  • Deploy - deploys your app to a staging URL
  • Promote - makes the staged version live at the production URL
  • Rollback - reverts production to the previous version

A typical flow is: deploy to staging, test, then promote to production. If an issue arises after promotion, you can roll back to the last known good version.

Staging and production URLs follow these patterns:

  • Production: https://decentapps.net/your-app-name
  • Staging: https://decentapps.net/_your-app-name

Deploy

By default, every git push to your configured repository deploys your app to a staging URL on the Decent Portal. Deployments take a few seconds to a few minutes, depending on your file count. You can track progress in GitHub under the Actions tab for your app's repository.

Example deploy workflow
Viewing deployment progress from the GitHub portal.

Deploying creates a new versioned set of files based on the latest commit on the "Main" branch of your app's repository. The production and staging URLs will always point to one immutable version.

You can also deploy manually via Actions > Deploy to Staging > Run workflow. For a manual deployment, files from the latest commit hash on the "Main" branch will be used.

Example of manual deployment
Manually deploying an app from the GitHub portal

The staging URL is public—anyone can guess it by adding an underscore before your app name. To avoid this, you can disable automatic deployments by editing .github/workflows/deploy.yml: remove the push trigger and leave only workflow_dispatch:.

editing deploy.yml for manual-only triggers
Delete these three lines in .github/workflows/deploy.yml if you only want manual deploys.

Promote

Once your staging deployment is tested, you can promote it to the production URL—i.e., go live.

Promotion is manually triggered: in GitHub, go to Actions > Promote Staging to Production > Run workflow. The process typically completes in under 10 seconds.

Viewing promotion progress from the GitHub portal.

Promotion is atomic—the production URL switches entirely to the staged version. Users with open sessions may need to refresh their browsers to see the update.

Rollback

Each promotion saves the previous production version, allowing you to roll back if needed. This is helpful if a problem is discovered after going live.

Rollbacks are manually triggered: in GitHub, go to Actions > Rollback Production > Run workflow. It typically completes in under 10 seconds.

Viewing rollback progress from the GitHub portal.

You can only roll back once per promotion. A second rollback attempt (without a new promotion) will fail. Once a new version is promoted, rollback becomes available again.

Preview versus Discoverable

Your app’s staging and production URLs are public, but apps start in a “preview” state—not listed from the Decent Portal homepage.

You're free to share your URLs however you like, including on social media. When you're ready, Decent Apps can review and mark your app as discoverable.

Troubleshooting

We've collected some common troubleshooting situations below. They are all oriented towards actions you can take to resolve problems. But that doesn't mean problems are always your fault or our platform can't be improved. We fully expect to find some bugs or things that could work better. If the troubleshooting help here isn't enough, let's talk further on the Decent App Discord server!

Problems Common to Multiple Workflows

When running a workflow, you see "Local action version does not match latest action version" or similar message.

If you aren't aware of any other problem, this warning is usually safe to ignore. But to address the warning, you can edit your workflow files in .github/workflows to specify the latest version which was also output in the warning message.

Note that due to GitHub caching, the major version syntax (e.g., "DecentAppsNet/deploy@v1") in the workflow will sometimes reference an older action than the latest. You can force GitHub to use the latest version of an action by editing the workflow to reference a full semantic version (e.g. "DecentAppsNet/deploy@v1.0.12").

When running a workflow, you see an "api-key is required" or "app-name is required" message.

 
You need to configure your app's repository to specify required inputs. See the previous "Configuring Your GitHub Repository" section.

When running a workflow, you see "Status code: 401", "Unauthorized", or similar message.

You've configured your app's repository to specify required inputs, but they aren't matching what has been provisioned for your account. Double-check that the repository secrets/variables are set correctly, and contact Decent Apps if that doesn't resolve the issue.

Deploy Workflow Problems

When running the deploy workflow, you see "Local dist directory missing" or a similar message.

 
The deploy action expects to find files intended for deployment within a dist subdirectory from your project root. If you are using a create-decent-app -generated project, the deploy workflow file (.github/workflows/deploy.yml) will build your source code to the dist directory with a call to npm run build.
 
You can create or modify the workflow to work differently, as long as the files you intend to deploy are found within dist before the DecentAppsNet/deploy action begins execution within the GitHub CI environment.
 
It's not necessary or advisable for the dist directory to be directly committed to your repository. In most cases, you will want the deploy workflow of your project to copy or build files to dist within the Github CI environment instead.

After successfully completing a deployment, you can't see the new version of your app.

 
The deploy workflow updates your staging URL, not the production URL. So if your app is named "cool-app", you should check at "https://decentapps.net/_cool-app" rather than "https://decentapps.net/cool-app".
 
Verify within the Github actions tab that the deploy workflow completed successfully. The last line of the log will indicate a versioned URL in a message like "Successfully deployed 295 files to https://decentapps.net/_cool-app/acd3ab36/". Sometimes using that versioned URL for testing instead of the shortened form will get around browser caching issues.
 
You can clear the cache in your browser as well.

Promotion Workflow Problems

After successfully completing a promotion, you can't see the new version of your app.

 
Verify within the Github actions tab that the promotion workflow completed successfully.
 
The deploy workflow updates your production URL to match the same set of files hosted from your staging URL. Check that your staging URL is serving the newer version of your app you had hoped to see at the production URL. If it is not, then run a new deploy, verify the staging URL is serving the expected version, and then run promote again. In this way, you can narrow the problem to a problem in deployment or promotion.

When running the promotion workflow, you see a "no stage version found" or similar message.

 
You need to run the deploy workflow before a staging version is available to promote.
 
If you ran the deploy workflow much earlier, it's possible that the staging version was deleted to recover storage. In this case, just run the deploy and promote workflows again.

Rollback Workflow Problems

When running the rollback workflow, you see a "no rollback version available" or similar message.

 
If you see this message and you're trying to resolve a production problem for your users, consider the rollback version as unavailable. You'll need to "fix forward", (deploy and promote a new version that addresses the production problem) rather than troubleshooting the unavailable rollback.
 
The explanation that follows won't be helpful in resolving a production problem, but rather explains the reasons for the message: If a promotion hasn't been made yet, no rollback will be available. If you've rolled back once already, you can't roll back a second time to reach an earlier version. One rollback is available for each promotion.

Under the Hood

Curious how it all works? Great. If not, feel free to skip this section—it's just background info for those who like to dig in.

The deployment system has three main parts:

  • GitHub workflows - defined in your repository, fully tinkerable
  • GitHub actions - open-source logic triggered by workflows. You can fork and modify them, though it’s rarely necessary.
  • Decent Partner Service - a closed-source backend that authorizes deployments, scoped to apps tied to your API key. It's closed to mitigate certain security risks.

These components don’t modify your source code. The only file added is a version.txt in your built output—used to track which version is live.

The workflows and actions run within GitHub’s CI environment, isolated from your local setup. The following sequence diagram illustrates how these pieces fit together:

Sequence diagram for deployments