How to Add a "Deploy to DigitalOcean" Button to Your Repository

App Platform is a Platform-as-a-Service (PaaS) offering that allows developers to publish code directly to DigitalOcean servers without worrying about the underlying infrastructure.


The Deploy to DigitalOcean Button allows users to launch an application onto App Platform. It can be embedded in the README file for GitHub and GitLab repositories, allowing users who are browsing your repository to deploy your code in one click, with a button that looks like this:

Deploy to DO

Overview

  1. Add a deploy.template.yaml file in the .do folder in the root directory of your repository.
  2. Add the Deploy to DigitalOcean button in the root README file in the repo.

Add the YAML File

The .do/deploy.template.yaml file contains all of the configuration details required to launch your application on App Platform. The YAML file’s structure is identical to a regular app spec except that the spec information must be nested under a spec: key. If you do not include a spec: key, the button will not function correctly.

Here’s a sample deploy.template.yaml file for a Golang service with no database:

spec:
 name: sample-golang
 services:
 - name: web
   git:
     branch: main
     repo_clone_url: https://github.com/digitalocean/sample-golang.git

Here’s an example of a minimal deploy.template.yaml file for a Python-based service with a dev database:

spec:
  name: sample-python
  services:
    - name: sample-python
      git:
        branch: main
        repo_clone_url: https://github.com/digitalocean/sample-python.git
    databases:
    - name: example-db

Here’s an example of a minimal deploy.template.yaml for a static site:

spec:
 name: sample-html
 static_sites:
 - git:
     branch: main
     repo_clone_url: https://github.com/digitalocean/sample-html.git
   name: sample-html

You can also specify a gitlab.com URL in the repo_clone_url parameter of the YAML file.

Configure Environment Variables

If your app requires an environment variable, you must list the variable in the deploy.template.yaml file with a placeholder value. App Platform will prompt you to enter values for these environment variables during app creation time.

For example, in the deploy.template.yaml file below:

  • DB_FOO_1 is a secret with a default value, DB-password-testvalue. App Platform lets you edit this environment variable at app creation time. This could be a database environment variable you need to set for the app to deploy.
  • EMAIL will be available in plain text during runtime. App Platform will prompt you to provide a value for this environment variable at app creation time.
  • MESSAGE will be available in plain text during run and build time with a default value of This is a greeting message. App Platform will let you edit this environment variable at app creation time.
  • DATABASE_URL is a bindable variable that points to the database connection string for example-db.
spec:
  name: sample-golang
  services:
  - name: web
    git:
      branch: main
      repo_clone_url: https://github.com/digitalocean/sample-golang.git
    envs:
    - key: DB_FOO_1
      value: "DB-password-testvalue"
      type: SECRET
    - key: EMAIL
      scope: RUN_TIME
    - key: MESSAGE
      value: "This is a greeting message"
    - key: DATABASE_URL
      scope: RUN_TIME
      value: ${example-db.DATABASE_URL}
  databases:
  - name: example-db

Add the Button

To add the button to a repo’s README file, add the following Markdown to your repo’s README file:

[![Deploy to DO](https://www.deploytodo.com/do-btn-blue.svg)](https://cloud.digitalocean.com/apps/new?repo=https://github.com/{REPO-OWNER}/{REPO-NAME}/tree/{BRANCH-NAME})

To add the button to a website or blog, embed the following HTML on your website:

<a href="https://cloud.digitalocean.com/apps/new?repo=https://github.com/{repo-owner}/{repo-name}/tree/{branch-name}">
 <img src="https://www.deploytodo.com/do-btn-blue.svg" alt="Deploy to DO">
</a>

Update the URL with your repo’s path information. For a GitLab repository, use https://gitlab.com instead of https://github.com.

Update URL Path

You must then replace the following variables in this code with the following values for the button to work:

  • REPO-OWNER: The base of your GitHub or GitLab URL. This is usually your user name or organization name.
  • REPO-NAME: The name given for this specific repo. This is the next path in the GitHub or GitLab URL.
  • BRANCH-NAME: Common defaults are main and master but this could be any branch in your repo.

The following code embeds this image in the README or website, making it viewable by users browsing your repository on GitHub.com, GitLab.com or your website. Your code edits make the image clickable so that users can deploy your app:

Deploy to DO

Customization

If you’d prefer a different color or style of button, you can swap out the image URL https://www.deploytodo.com/do-btn-blue.svg, with one of the following styles:

Blue Ghost

https://www.deploytodo.com/do-btn-blue-ghost.svg

Deploy to DO

White Ghost

https://www.deploytodo.com/do-btn-white-ghost.svg

Deploy to DO

White

https://www.deploytodo.com/do-btn-white.svg

(Shown here on a black background)

Deploy to DO

Verify the Button Works

Once you’ve added the button to your repo or website, click the Deploy to DigitalOcean button. If set up correctly, the button sends you to DigitalOcean’s Control Panel and prompts you to log in. Log in to the control panel.

Note
Your GitHub repo must contain some form of an app. If the repo is empty, App Platform returns the error App detection failed - Missing app spec file when you click the deploy button.

Once logged in, the control panel prompts you to enter any environmental variables your app may require. To update environmental variable values, click Edit and then enter values for any necessary environmental variables.

Once you have entered any necessary environmental variables, click Deploy. Your app should deploy within a few minutes.

If your app does not deploy, or the button does not correctly link to DigitalOcean’s Control Panel, or the control panel doesn’t display your environmental variables, check your configuration using the set up steps above.

Get DigitalOcean Credits For Use of “Deploy to DigitalOcean” Button

If you refer someone to DigitalOcean via the Deploy to DigitalOcean button using a valid referral code, they’ll receive credits on their account as soon as they add a valid payment method. Additionally, you’ll receive credit with DigitalOcean for the referral. The amounts that are paid out are listed in the official page for the DigitalOcean Referral Program.

To enable this benefit for you and your users:

  1. Get your unique referral code by visiting the Referrals tab on your Settings page and note the 12 character code (for example, a1b2c3d4e5f6) at the end of your referral link (for example, https://m.do.co/c/a1b2c3d4e5f6).

  2. Add your referral code to the end of the URL as an additional query string beginning with refcode=.

For example, if your referral code is a1b2c3d4e5f6 and your URL is:

https://cloud.digitalocean.com/apps/new?repo=https://github.com/digitalocean/sample-nextjs/tree/main

After adding your referral code, the URL will look like this:

https://cloud.digitalocean.com/apps/new?repo=https://github.com/digitalocean/sample-nextjs/tree/main&refcode=a1b2c3d4e5f6
Note
The git URL in deploy.template.yaml must be the same as that is specified in this spec.

Limits

Only the following combination of resources are currently supported:

  • 1 Service
  • 1 Service + Dev Database
  • 1 Static site
  • 1 Static site + Dev Database