Deploy Hooks

Deploy hooks enable you to trigger an on-demand deploy of your Render service with a single HTTP request. Use deploy hooks with:

• CI/CD environments like GitHub Actions (see an example)
• Image-backed services (to trigger a deploy when a new image is available)
• Headless CMS systems like Contentful (to trigger a deploy when content changes)

Triggering a deploy

Each service has a secret deploy hook URL, available from its Settings tab in the Render Dashboard:

To trigger a deploy, send a basic GET or POST request to your service’s deploy hook URL—no special headers required.

curl https://api.render.com/deploy/srv-xyz…

Deploying from an image registry

Image-backed services on Render pull and deploy a prebuilt Docker image from an external registry. These services do not automatically redeploy if a new image is pushed to the registry. You can use a deploy hook to trigger a deploy whenever an updated image is available.

To deploy a specific tag or digest, append the imgURL query parameter to your deploy hook URL:

# Append a string with this format to your deploy hook URL.
# This example deploys the image `nginx:1.26` from Docker Hub.
# Note the URL-encoding.
&imgURL=docker.io%2Flibrary%2Fnginx%401.26

If you don’t provide this parameter, Render uses whichever tag or digest you’ve specified in the service’s settings.

Using with GitHub Actions

You might want to trigger a service deploy from your CI/CD environment whenever certain conditions are met (such as when all of your tests pass). Let’s set this up using deploy hooks and GitHub Actions.

1. Create a repository secret

Deploy hook URLs are secret values, so we need to make sure to store ours as a secret in our GitHub repo:

1. Go to your GitHub repo’s Settings page.

2. Click Secrets and variables > Actions.

3. Click New repository secret. Create a secret with the name RENDER_DEPLOY_HOOK_URL and provide your deploy hook URL as the value:

   

2. Add a GitHub workflow

Now that we’ve added our deploy hook URL, let’s create a GitHub workflow that uses it:

1. Create a .github/workflows directory in your repo if it doesn’t already exist. GitHub Actions automatically detects and runs any workflows defined in this folder.
2. Add a YAML file to this directory to represent your new workflow. The example below uses the file path .github/workflows/ci.yml.
3. Define logic in your workflow to trigger a deploy after any prerequisite steps succeed. See the example.
4. Commit all of your changes.

Example workflow

This example workflow defines a job named ci that includes two steps (Test and Deploy). The workflow runs whenever any pull request is opened against main, or when commits are pushed to main.

1. The Test step runs the repo’s defined unit tests.
2. The Deploy step executes a curl request to our deploy hook URL only if the current branch is main and the Test step succeeded.

# .github/workflows/ci.yml

on:
  pull_request:
  push:
    branches: [main]

jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Test
        run: |
          npm install
          npm run test

      - name: Deploy
        # Only run this step if the branch is main
        if: github.ref == 'refs/heads/main'
        env:
          deploy_url: ${{ secrets.RENDER_DEPLOY_HOOK_URL }}
        run: |
          curl "$deploy_url"