feat: add netlify push for git-based deploys via Netlify-hosted git

serhalp · serhalp · commit 43aeca50adb6 · 2026-02-16T10:58:21.000-05:00
Introduce a new deploy workflow using Netlify-hosted git repositories:

- `netlify init --git`: configures a site to use Netlify's git provider, sets up the `netlify`
  remote, and wires up a credential helper in `./.git/config` for seamless git operations
- `netlify push`: stages, commits, and pushes to the Netlify remote (which will trigger a
  build/deploy)
- `netlify git-credentials` (hidden): git credential helper that provides the Netlify auth token for
  push authentication

Adds `@clack/prompts` for pretty CLI UX. We've been meaning to do this for years and I'd rather not
keep spreading our current patterns. The dependency weight is very small.
diff --git a/docs/commands/init.md b/docs/commands/init.md
@@ -20,6 +20,7 @@ netlify init
 
 - `filter` (*string*) - For monorepos, specify the name of the application to run the command in
 - `force` (*boolean*) - Reinitialize CI hooks if the linked project is already configured to use CI
+- `git` (*boolean*) - Use Netlify-hosted git for deploys (no external provider needed)
 - `git-remote-name` (*string*) - Name of Git remote to use. e.g. "origin"
 - `manual` (*boolean*) - Manually configure a git remote for CI
 - `debug` (*boolean*) - Print debugging information
diff --git a/docs/commands/push.md b/docs/commands/push.md
@@ -0,0 +1,34 @@
+---
+title: Netlify CLI push command
+sidebar:
+  label: push
+description: Push code to Netlify via git, triggering a build
+---
+
+# `push`
+
+<!-- AUTO-GENERATED-CONTENT:START (GENERATE_COMMANDS_DOCS) -->
+Push code to Netlify via git, triggering a build
+
+**Usage**
+
+```bash
+netlify push
+```
+
+**Flags**
+
+- `filter` (*string*) - For monorepos, specify the name of the application to run the command in
+- `message` (*string*) - Commit message
+- `debug` (*boolean*) - Print debugging information
+- `auth` (*string*) - Netlify auth token - can be used to run this command without logging in
+
+**Examples**
+
+```bash
+netlify push
+netlify push -m "Add contact form"
+```
+
+
+<!-- AUTO-GENERATED-CONTENT:END -->
diff --git a/docs/index.md b/docs/index.md
@@ -145,6 +145,10 @@ Open settings for the project linked to the current folder
 | [`open:site`](/commands/open#opensite) | Opens current project url in browser  |
 
 
+### [push](/commands/push)
+
+Push code to Netlify via git, triggering a build
+
 ### [recipes](/commands/recipes)
 
 Create and modify files in a project using pre-defined recipes
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -57,6 +57,7 @@
     "typecheck:watch": "tsc --watch"
   },
   "dependencies": {
+    "@clack/prompts": "^1.0.0",
     "@fastify/static": "9.0.0",
     "@netlify/ai": "0.3.4",
     "@netlify/api": "14.0.13",
diff --git a/src/commands/git-credentials/git-credentials.ts b/src/commands/git-credentials/git-credentials.ts
@@ -0,0 +1,36 @@
+import process from 'process'
+
+import type BaseCommand from '../base-command.js'
+
+const readStdin = (): Promise<string> =>
+  new Promise((resolve) => {
+    let data = ''
+    process.stdin.setEncoding('utf8')
+    process.stdin.on('data', (chunk: string) => {
+      data += chunk
+    })
+    process.stdin.on('end', () => {
+      resolve(data)
+    })
+    // If stdin isn't being piped, resolve after a short timeout
+    if (process.stdin.isTTY) {
+      resolve(data)
+    }
+  })
+
+export const gitCredentials = async (command: BaseCommand) => {
+  const input = await readStdin()
+
+  // Only respond to "get" requests from the git credential protocol
+  if (!input.includes('protocol=') && !input.startsWith('get')) {
+    return
+  }
+
+  const token = command.netlify.api.accessToken
+  if (!token) {
+    throw new Error('No access token found. Please run `netlify login` first.')
+  }
+
+  // Output in git credential helper format
+  process.stdout.write(`username=x-access-token\npassword=${token}\n`)
+}
diff --git a/src/commands/git-credentials/index.ts b/src/commands/git-credentials/index.ts
@@ -0,0 +1,10 @@
+import BaseCommand from '../base-command.js'
+
+export const createGitCredentialsCommand = (program: BaseCommand) =>
+  program
+    .command('git-credentials', { hidden: true })
+    .description('Git credential helper for Netlify-hosted repos')
+    .action(async (_options, command: BaseCommand) => {
+      const { gitCredentials } = await import('./git-credentials.js')
+      await gitCredentials(command)
+    })
diff --git a/src/commands/init/index.ts b/src/commands/init/index.ts
@@ -10,6 +10,7 @@ export const createInitCommand = (program: BaseCommand) =>
       'Configure continuous deployment for a new or existing project. To create a new project without continuous deployment, use `netlify sites:create`',
     )
     .option('-m, --manual', 'Manually configure a git remote for CI')
+    .option('--git', 'Use Netlify-hosted git for deploys (no external provider needed)')
     .option('--git-remote-name <name>', 'Name of Git remote to use. e.g. "origin"')
     .addHelpText('after', () => {
       const docsUrl = 'https://docs.netlify.com/cli/get-started/'
diff --git a/src/commands/init/init.ts b/src/commands/init/init.ts
@@ -6,6 +6,7 @@ import { chalk, exit, log, netlifyCommand } from '../../utils/command-helpers.js
 import getRepoData from '../../utils/get-repo-data.js'
 import { ensureNetlifyIgnore } from '../../utils/gitignore.js'
 import { configureRepo } from '../../utils/init/config.js'
+import { configNetlifyGit } from '../../utils/init/config-netlify-git.js'
 import { track } from '../../utils/telemetry/index.js'
 import type BaseCommand from '../base-command.js'
 import { link } from '../link/link.js'
@@ -241,6 +242,14 @@ export const init = async (
   // Add .netlify to .gitignore file
   await ensureNetlifyIgnore(repositoryRoot)
 
+  // Handle --git flag: use Netlify-hosted git
+  if (options.git) {
+    const siteInfo = isEmpty(existingSiteInfo) ? await createOrLinkSiteToRepo(command) : existingSiteInfo
+    persistState({ state, siteInfo })
+    await configNetlifyGit({ command, siteId: siteInfo.id })
+    return siteInfo
+  }
+
   const repoUrl = getRepoUrl(existingSiteInfo)
   if (repoUrl && !options.force) {
     logExistingAndExit({ siteInfo: existingSiteInfo })
diff --git a/src/commands/main.ts b/src/commands/main.ts
@@ -35,12 +35,14 @@ import { createDevCommand } from './dev/index.js'
 import { createDevExecCommand } from './dev-exec/index.js'
 import { createEnvCommand } from './env/index.js'
 import { createFunctionsCommand } from './functions/index.js'
+import { createGitCredentialsCommand } from './git-credentials/index.js'
 import { createInitCommand } from './init/index.js'
 import { createLinkCommand } from './link/index.js'
 import { createLoginCommand } from './login/index.js'
 import { createLogoutCommand } from './logout/index.js'
 import { createLogsCommand } from './logs/index.js'
 import { createOpenCommand } from './open/index.js'
+import { createPushCommand } from './push/index.js'
 import { createRecipesCommand } from './recipes/index.js'
 import { createServeCommand } from './serve/index.js'
 import { createSitesCommand } from './sites/index.js'
@@ -225,13 +227,15 @@ export const createMainCommand = (): BaseCommand => {
   createDevCommand(program)
   createEnvCommand(program)
   createFunctionsCommand(program)
+  createGitCredentialsCommand(program)
   createRecipesCommand(program)
   createInitCommand(program)
   createCloneCommand(program)
   createLinkCommand(program)
   createLoginCommand(program)
   createLogoutCommand(program)
   createOpenCommand(program)
+  createPushCommand(program)
   createServeCommand(program)
   createSitesCommand(program)
   createStatusCommand(program)
diff --git a/src/commands/push/index.ts b/src/commands/push/index.ts
@@ -0,0 +1,14 @@
+import type { OptionValues } from 'commander'
+
+import BaseCommand from '../base-command.js'
+
+export const createPushCommand = (program: BaseCommand) =>
+  program
+    .command('push')
+    .description('Push code to Netlify via git, triggering a build')
+    .option('-m, --message <message>', 'Commit message')
+    .addExamples(['netlify push', 'netlify push -m "Add contact form"'])
+    .action(async (options: OptionValues, command: BaseCommand) => {
+      const { push } = await import('./push.js')
+      await push(options, command)
+    })
diff --git a/src/commands/push/push.ts b/src/commands/push/push.ts
@@ -0,0 +1,100 @@
+import type { OptionValues } from 'commander'
+import * as p from '@clack/prompts'
+
+import { logAndThrowError } from '../../utils/command-helpers.js'
+import execa from '../../utils/execa.js'
+import type BaseCommand from '../base-command.js'
+
+export const push = async (options: OptionValues, command: BaseCommand) => {
+  p.intro('Push to Netlify')
+
+  await command.authenticate()
+
+  // 1. Verify netlify remote exists
+  const { stdout: remotes } = await execa('git', ['remote'])
+  if (!remotes.includes('netlify')) {
+    p.cancel('No netlify remote found.')
+    return logAndThrowError('No netlify remote found. Run `netlify init --git` first.')
+  }
+
+  const s = p.spinner()
+
+  // 2. Check if this is a fresh repo with no commits yet
+  let isInitialCommit = false
+  try {
+    await execa('git', ['rev-parse', 'HEAD'])
+  } catch {
+    isInitialCommit = true
+  }
+
+  // 3. Check for working tree changes (unstaged + staged)
+  const { stdout: status } = await execa('git', ['status', '--porcelain'])
+  const hasChanges = status.trim().length > 0
+
+  if (hasChanges) {
+    // Stage everything
+    s.start('Staging changes')
+    await execa('git', ['add', '.'])
+    s.stop('Changes staged')
+
+    // Commit
+    const message: string =
+      typeof options.message === 'string'
+        ? options.message
+        : isInitialCommit
+        ? 'Initial deploy via Netlify CLI'
+        : `Deploy at ${new Date().toISOString()}`
+
+    const commitResult = await execa('git', ['commit', '-m', message], { reject: false })
+    if (commitResult.exitCode !== 0 && !commitResult.stderr.includes('nothing to commit')) {
+      p.cancel('Commit failed')
+      return logAndThrowError(`Commit failed: ${commitResult.stderr}`)
+    }
+    p.log.success(`Committed: ${message}`)
+  } else if (!isInitialCommit) {
+    // No local changes — check if there are unpushed commits.
+    const { stdout: currentBranchName } = await execa('git', ['rev-parse', '--abbrev-ref', 'HEAD'])
+    const branch = currentBranchName.trim()
+    // First check if the remote tracking branch exists at all (it won't before the first push).
+    const { exitCode: remoteRefExists } = await execa('git', ['rev-parse', '--verify', `netlify/${branch}`], {
+      reject: false,
+    })
+    if (remoteRefExists === 0) {
+      // Use rev-list --count for a reliable machine-readable check
+      const { stdout: countStr } = await execa('git', ['rev-list', '--count', `netlify/${branch}..HEAD`], {
+        reject: false,
+      })
+      if (countStr.trim() === '0') {
+        p.log.step('Everything up to date — nothing to push')
+        p.outro('Already deployed!')
+        return
+      }
+      p.log.step(`Pushing ${countStr.trim()} unpushed commit(s)`)
+    } else {
+      p.log.step('Pushing to Netlify for the first time')
+    }
+  }
+
+  // 4. Push the current branch
+  const { stdout: currentBranch } = await execa('git', ['rev-parse', '--abbrev-ref', 'HEAD'])
+  s.start(`Pushing ${currentBranch.trim()} to Netlify`)
+  const pushResult = await execa('git', ['push', '--porcelain', '-u', 'netlify', currentBranch.trim()], {
+    reject: false,
+  })
+  if (pushResult.exitCode !== 0) {
+    s.stop('Push failed')
+    p.cancel(pushResult.stderr || 'Push failed')
+    return logAndThrowError(`Push failed: ${pushResult.stderr}`)
+  }
+
+  // --porcelain output format: <flag>\t<from>:<to>\t<summary>
+  // flag '=' means up-to-date (nothing pushed), ' ' or other means data was transferred
+  const porcelainOutput = pushResult.stdout.trim()
+  if (porcelainOutput.includes('=\t') || porcelainOutput.includes('[up to date]')) {
+    s.stop('Nothing to push')
+    p.outro('Already deployed!')
+  } else {
+    s.stop('Pushed to Netlify')
+    p.outro('Build triggered! Your deploy will start shortly.')
+  }
+}
diff --git a/src/utils/init/config-netlify-git.ts b/src/utils/init/config-netlify-git.ts
diff --git a/tests/integration/commands/help/__snapshots__/help.test.ts.snap b/tests/integration/commands/help/__snapshots__/help.test.ts.snap

Original file line number	Diff line number	Diff line change
`@@ -10,6 +10,7 @@ export const createInitCommand = (program: BaseCommand) =>`
`10`	`10`	'Configure continuous deployment for a new or existing project. To create a new project without continuous deployment, use `netlify sites:create`',
`11`	`11`	`)`
`12`	`12`	`.option('-m, --manual', 'Manually configure a git remote for CI')`
	`13`	`+ .option('--git', 'Use Netlify-hosted git for deploys (no external provider needed)')`
`13`	`14`	`.option('--git-remote-name <name>', 'Name of Git remote to use. e.g. "origin"')`
`14`	`15`	`.addHelpText('after', () => {`
`15`	`16`	`const docsUrl = 'https://docs.netlify.com/cli/get-started/'`