How to Deploy Salesforce SFDX Metadata from a GitHub Repository

5 min read · Salesforce · SFDX · GitHub Repositories

If your Salesforce metadata lives in a GitHub repository — Apex classes, Lightning Web Components, custom objects, flows — getting it into an org means running a deployment. The fastest way is straight from your browser with reapd. If you want to understand how the process works under the hood using the Salesforce CLI, that's covered below.

The Fast Way: Deploy Directly from Your Browser

reapd handles the entire deployment process without installing anything. Connect your GitHub account, connect your Salesforce org via OAuth, pick a repo and branch, and hit Deploy. Logs stream in real time — no terminal, no local CLI, no setup.

Deploy from GitHub without the CLI

Connect your GitHub and Salesforce org in seconds. Pick a repo, pick a branch, and watch your deployment stream live.

Start deploying free →

How It Works: The CLI Approach

Under the hood, deploying Salesforce SFDX metadata from a GitHub repository involves three steps: cloning the repo, authenticating to your org, and running the deploy command. Here's how that looks using the Salesforce CLI directly.

What Is a Salesforce SFDX Deployment?

Salesforce DX (SFDX) is the source-driven development model introduced by Salesforce. Metadata is stored in source format in a project directory, typically under force-app/main/default/, versioned in Git. Deploying means pushing that metadata from your repository into a Salesforce org — syncing what's in your code with what's in the org.

The deployment tool is the Salesforce CLI, available as the sf command (formerly sfdx). The core deploy command is sf project deploy start.

Prerequisites

To deploy manually using the CLI, you need the following installed on your machine:

Node.js (v18 or later) — required by the Salesforce CLI
Salesforce CLI — install with npm install -g @salesforce/cli
Git — to clone the repository

Step 1: Clone the Repository

Start by cloning the GitHub repository to your local machine:

git clone https://github.com/your-org/your-sfdx-project.git
cd your-sfdx-project

Confirm the project has a valid SFDX structure — you should see a sfdx-project.json file and a force-app/ directory at the root.

Step 2: Authenticate to Your Salesforce Org

Before deploying, the CLI needs credentials for your target org. The most common approach is the web-based login flow:

# For a sandbox
sf org login web --instance-url https://test.salesforce.com --alias my-sandbox

# For production
sf org login web --alias my-production

This opens a browser window where you log in with your Salesforce credentials. Once authenticated, the CLI stores an access token locally.

The default token lifetime is short. For automation or repeated deploys, consider using a connected app with a JWT-based auth flow instead of the web login.

Step 3: Run the Deployment

With the repo cloned and your org authenticated, run the deploy:

sf project deploy start \
  --source-dir force-app \
  --target-org my-sandbox \
  --test-level RunLocalTests \
  --wait 10

Key flags to know:

--source-dir — the path to your metadata source (usually force-app)
--target-org — the alias of the org you're deploying to
--test-level — controls which Apex tests run (see below)
--wait — how many minutes to wait for the deployment to complete before timing out

Test Levels Explained

Salesforce requires Apex test coverage for production deployments. The --test-level flag controls this:

NoTestRun — skips tests entirely. Only valid for sandbox deployments.
RunSpecifiedTests — runs only the test classes you name.
RunLocalTests — runs all tests defined in your org, excluding managed package tests. Required for production when no test classes are specified.
RunAllTestsInOrg — runs every test in the org, including managed packages. Slowest option.

Reading the Deployment Output

A successful deploy prints a summary listing each deployed component, test results, and overall pass/fail status. A failure shows which components or tests failed, along with error messages you can act on immediately.

Deployments to production with many components or tests can take 10–30 minutes. The --wait flag determines how long the CLI blocks before returning — if it times out, the deployment continues in the background and you can check status with sf project deploy report.