Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 37 ยท Deployments and Git Integration

Git Integration and Automatic Deploys

Understand how Vercel and Netlify connect to GitHub, GitLab and Bitbucket, what a push triggers, which permissions are needed, and how to pause or limit automatic builds.

The feature that made these platforms popular is simple: you push to Git and your site updates. No upload, no button. This lesson explains what happens behind that push, how the connection is secured and how to control it.

Once you understand the trigger, the rest of the chapter (branches, previews, rollbacks, monorepos) is variations on the same pipeline.

What happens when you push

The deploy pipeline

Push Git host sends a webhook event.
Clone A build machine fetches the commit.
Install Dependencies are installed.
Build Your build command runs.

Same steps on both platforms.

1 / 2
  1. You push a commit (or open or update a pull request). Your Git host (GitHub, GitLab, Bitbucket) sends a webhook: an HTTP request describing the event.
  2. The platform receives it, finds the connected project and decides whether the event should trigger a build (branch rules, ignore rules).
  3. A fresh, isolated build container clones the repository at that exact commit, installs dependencies, runs the build, and uploads the results.
  4. The platform reports status checks back to your Git host, so a pull request shows "Deploy preview ready" with a link.

Connecting a Git provider

You grant access through an app installed on your Git account:

  • GitHub: the Vercel or Netlify GitHub App is installed on your account or organization. During installation you choose All repositories or Only select repositories. Prefer the second: grant the minimum.
  • GitLab and Bitbucket: both platforms support them through OAuth-style connections. Self-hosted Git servers have more limited support, so check the current documentation.

If you cannot see a repository in the import list, the cause is almost always that the app was not granted that repository. Open the app's settings on GitHub and add it.

Connecting a private repository from an organization may require an organization owner to approve the app. Ask your admin instead of working around it with shared personal tokens.

Trigger rules: what builds and what does not

By default every push to any branch builds, and every pull request gets a preview. You can narrow that:

  • Production branch. The one branch whose pushes become production. Usually main.
  • Branch deploys / preview branches. Choose whether other branches build at all, only some, or none.
  • Ignored builds. A script or command that exits with a code deciding whether to skip, useful for monorepos (covered in Monorepos).
  • Skip tokens in commit messages. Both platforms understand markers such as [skip ci] or [ci skip] in a commit message; Netlify also supports [skip netlify]. Vercel supports [skip ci] and [vercel skip]. Verify the current list in each platform's docs, since the supported markers can change.
  • Stop or pause builds. Netlify has Stop auto publishing (builds still run but are not published) and Stop builds. Vercel lets you disable Git-triggered deployments per branch with configuration.

On Vercel you can restrict deployment branches in vercel.json:

JSON
{
  "git": {
    "deploymentEnabled": {
      "main": true,
      "dev": true,
      "experimental": false
    }
  }
}

Commit status and pull request comments

When a deploy finishes, the platform posts a status check and (usually) a comment on the pull request containing the preview URL. A failed build marks the check red, which can block merging if you set the check as required in your branch protection rules. That turns the preview build into an automatic gate: broken builds cannot be merged.

Deploying without Git integration

Sometimes you want the CI system you already use (GitHub Actions, GitLab CI) to control timing. Then you disable the automatic Git builds and have the CI job call the CLI with a token:

YAML
# .github/workflows/deploy.yml (read-only example)
name: deploy
on:
  push:
    branches: [main]
jobs:
  ship:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npm test
      - run: npx netlify-cli deploy --build --prod
        env:
          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}

This runs your tests first and deploys only if they pass. The trade-off is that you give up the built-in preview comments unless you recreate them.

A webhook handler you can run

This stand-in receives GitHub-style push payloads and decides what the platform would do. The payload fields (ref, head_commit.message) are real GitHub fields; the rules are a simplified model.

Node.js Push event decision (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Status check gate (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What tells the platform that you pushed a commit?

    Git hosts notify the platform through webhooks, and the platform then clones the commit.
  2. 2. When installing the GitHub app, what is the safest repository access choice?

    Grant the least access needed.
  3. 3. How can a failed preview build stop a bad merge?

    A required status check blocks merging until it passes.
  4. 4. When would you disable Git-triggered builds and use a CI job plus the CLI?

    CI-driven deploys let you run tests first and control the exact timing.

Summary

  • A push triggers a webhook, a clean build in an isolated container, an upload and a status report.
  • Grant the Git app only the repositories it needs.
  • Control triggers with the production branch, branch settings, ignore rules and skip markers in commit messages.
  • Required status checks turn the preview build into a merge gate.
  • CI-driven deploys with the CLI and tokens are an alternative when you need full control.

Next: Production and Branch Deploys