> For the complete documentation index, see [llms.txt](https://prodocs.webhash.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://prodocs.webhash.com/auto-deploy.md).

# Auto-deploy on Push

Once your site is live on WebHash Pro, you don't have to redeploy it by hand every time you change something. **Auto-deploy on push** watches a repository for you: every time you push new code to your chosen branch, WebHash Pro automatically builds the latest version and publishes it to IPFS.

This page explains what auto-deploy does, how to turn it on, what happens on each push, and how to turn it off again.

{% hint style="info" %}
Auto-deploy is set **per repository, per branch**. Turning it on for one repository does not affect your others, and each repository watches exactly one branch (for example `main`).
{% endhint %}

***

## What auto-deploy does

When auto-deploy is enabled for a repository:

1. You push a commit to GitHub on the branch you configured (for example, `main`).
2. GitHub instantly notifies WebHash Pro about that push.
3. WebHash Pro automatically starts a new deployment - it builds your project and publishes the result to IPFS, exactly as if you had clicked **Deploy** yourself.
4. You get a brand-new **CID** (the content identifier for this version of your site) and a fresh gateway URL.
5. If you have any ENS domains pointed at an older version of this repository, WebHash Pro emails you so you can update them to the new CID.

In short: **push your code, and your live IPFS build updates on its own.** No buttons to click, no terminal commands to run.

{% hint style="info" %}
Auto-deploy uses the same build settings (project type, build command, output directory) and the same [environment variables](/environment-variables.md) you set up when you first deployed the repository. To change those, update them on the repository before your next push.
{% endhint %}

***

## Before you start

To use auto-deploy, you need:

* **A connected repository with at least one deployment.** Auto-deploy lives on a repository's own page, which you reach after you've deployed that repository at least once. If you haven't deployed it yet, follow the [Quick Start](/getting-started.md) first.
* **Admin access to the repository on GitHub.** Enabling auto-deploy creates a webhook on your GitHub repository, and only people with admin rights on a repo can add webhooks. If you don't have admin access, WebHash Pro will tell you and the toggle won't turn on.

{% hint style="warning" %}
**You need admin access on the GitHub repository.** If you only have read or write access (but not admin), GitHub won't let WebHash Pro create the webhook, and you'll see the message *"You need admin access to this repository to enable auto-deploy."* Ask a repository owner or organization admin to enable it, or to grant you admin access.
{% endhint %}

***

## How to enable auto-deploy

1. Sign in to your dashboard at <https://pro.webhash.com>.
2. In the left-hand navigation, click **Deployments**.
3. Find the repository you want to watch and open it. This takes you to the repository's page, which lists all of its deployments.
4. At the top of that page you'll see a card titled **Auto-deploy on push**, with a description such as *"Automatically deploy this repository whenever you push to the `main` branch."*
5. Click the **toggle switch** on the right side of that card to turn it on.

![Auto-deploy on push card, toggle off](/files/Qygf0fQQyHKx6d9FEGgi)

When you flip the switch on, WebHash Pro does the following for you behind the scenes:

* It checks that you have admin access to the repository on GitHub.
* It creates a **GitHub webhook** on the repository that listens for `push` events and points at WebHash Pro.
* It securely stores the connection so future pushes can trigger a build.

When this finishes you'll see a confirmation: **"Auto-deploy enabled."** The toggle stays on.

![Auto-deploy on push enabled](/files/JJQ05A6bASGVfQzVA5Jf)

{% hint style="success" %}
That's it - you don't need to touch your GitHub settings or copy any secret yourself. WebHash Pro creates and manages the webhook for you. The next push to your branch will trigger a deployment automatically.
{% endhint %}

### Which branch does it watch?

Auto-deploy watches the branch shown in the card's description (for most projects this is `main`). The branch is taken from how the repository was set up when you first deployed it. Pushes to **other** branches are ignored and won't trigger a deployment - only the configured branch does.

***

## What happens on each push

After auto-deploy is enabled, here's the full sequence every time you push to the watched branch:

1. **You push.** You commit and push to the configured branch on GitHub as normal.
2. **GitHub notifies WebHash Pro.** GitHub sends the push event to WebHash Pro over the webhook that was created for you.
3. **A new deployment starts.** WebHash Pro begins building your project using your saved build settings and environment variables, then publishes the result to IPFS. You'll see the new deployment appear on the repository's page with a status that moves from building to **Success**.
4. **You get a new CID.** Each successful build produces a new content identifier (CID) and gateway URL - a fresh, permanent address for this exact version of your site.
5. **You may be emailed to update your ENS domain.** If any of your ENS domains are connected to an *older* deployment of this repository, WebHash Pro sends you an email titled **"New build live - update your ENS domains."** It includes the new CID, a preview link, and a button to update your domain. (More on this below.)

{% hint style="info" %}
**Duplicate pushes are handled safely.** If GitHub sends the same push more than once, WebHash Pro recognizes it and won't run the build twice. Branch deletions and tag pushes are ignored.
{% endhint %}

{% hint style="warning" %}
**If you've run out of storage, the automatic build is skipped.** Auto-deploy respects your storage allowance just like a manual deploy. If a push would exceed your available storage, WebHash Pro quietly skips that build rather than failing loudly - so it's worth keeping an eye on your usage. See [Storage & Billing](/storage-and-billing.md) to check your usage or buy more.
{% endhint %}

***

## Updating your ENS domain after a deploy

WebHash Pro is **self-custodial** when it comes to ENS: it never changes your domain's records for you. That's a deliberate safety feature - only you, signing with your own wallet, can change where your domain points.

So when auto-deploy publishes a new build, any ENS domain you previously connected to this repository still points at the *old* version. To show your visitors the new build, you update the domain's contenthash to the new CID yourself.

To make this easy, WebHash Pro emails you after each successful auto-deploy (when you have a domain pointed at an older build of that repository). The email includes:

* The **new CID** and a preview link so you can confirm the build looks right.
* The list of ENS domain(s) that still point to the previous version.
* A button - **Update ENS contenthash** - that takes you to your **Domains** page.

To update a domain:

1. Open the email and click **Update ENS contenthash**, or go to <https://pro.webhash.com/dashboard/domains>.
2. Select the domain you want to re-point and choose the new deployment.
3. Approve the update by **signing the transaction in your wallet**. WebHash Pro never signs on your behalf.

For the full walkthrough, see the **ENS Domains** guide.

{% hint style="info" %}
Don't have an ENS domain connected? Then there's nothing extra to do after a push - your new build is live on its IPFS gateway URL immediately, and you won't receive the update email.
{% endhint %}

***

## How to disable auto-deploy

You can turn auto-deploy off at any time:

1. Go to **Deployments** and open the repository you want to change.
2. In the **Auto-deploy on push** card, click the toggle switch to turn it **off**.

WebHash Pro will remove the GitHub webhook it created, and you'll see the confirmation **"Auto-deploy disabled."** From then on, pushes to your branch will no longer trigger automatic deployments. You can always deploy manually, and you can re-enable auto-deploy later with a single toggle.

![Auto-deploy on push disabled](/files/U1oyyKj1LegUn7D9iyLN)

{% hint style="info" %}
Turning auto-deploy off does **not** delete any of your existing deployments or unpublish your site - it only stops new pushes from triggering builds. Your latest CID and any connected ENS domains keep working exactly as before.
{% endhint %}

***

## Troubleshooting

**The toggle won't turn on / "You need admin access."** You must have admin rights on the GitHub repository to add the webhook. Ask a repository or organization admin to enable auto-deploy, or to grant you admin access.

**"A webhook already exists for this repository."** GitHub already has a matching webhook on the repository. Remove the existing webhook in your repository's GitHub settings (Settings → Webhooks), then try the toggle again.

**A push didn't trigger a deployment.** Check that you pushed to the **configured branch** shown in the card (other branches are ignored), and that you still have storage available - builds are skipped when your storage allowance is full. If you recently disconnected GitHub, you may need to reconnect it so WebHash Pro can build your repository.

{% hint style="warning" %}
**Auto-deploy needs a public WebHash Pro URL to work.** On the live site at <https://pro.webhash.com> this is always the case. If you're ever using a local or preview build of WebHash Pro that GitHub can't reach over the internet, you may see a note that *"Auto-deploy only works once this app is deployed to a public URL."* - in that situation pushes won't trigger a deployment until a public URL is in use.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://prodocs.webhash.com/auto-deploy.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.