← Cloudflare Workers / workers / ci-cd / builds

Deploy Hooks

По умолчанию Workers Builds запускает сборку при отправке коммита в подключённый репозиторий Git. Deploy Hooks дают ещё один способ запустить сборку. Каждый хук представляет собой уникальный URL, который запускает ручную сборку для одной ветки при получении HTTP POST запроса. Используйте Deploy Hooks, чтобы связать Workers Builds со следующими сценариями:

• Автоматическая пересборка при изменении контента в headless CMS
• Собирайте по расписанию с помощью внешней службы cron
• Запуск развёртываний из пользовательских конвейеров CI/CD на основе определённых условий

Прежде чем создавать Deploy Hook, убедитесь, что ваш Worker подключён к репозиторию Git.

1. Перейдите в Workers & Pages и выберите свой Worker.

   Перейдите в Workers & Pages ↗

2. Перейдите в Настройки > Builds > Deploy Hooks.

3. Введите имя и выберите ветка для сборки.

4. Выберите Создание и скопируйте сгенерированный URL.

Отправьте запрос HTTP POST на свой Deploy Hook URL, чтобы запустить сборку:

curl -X POST "https://api.cloudflare.com/client/v4/workers/builds/deploy_hooks/<DEPLOY_HOOK_ID>"

Нет Authorization заголовок не требуется. Уникальный идентификатор, встроенный в URL, служит учетными данными для аутентификации.

Пример ответа:

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "build_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "branch": "main",
    "worker": "my-worker"
  }
}

build_uuid в ответе можно использовать, чтобы отслеживание статуса сборки и получение логов.

После срабатывания Deploy Hook вы можете проверить это в панели управления:

• В Deploy Hooks список, hook отображает время последнего срабатывания.
• В истории сборок Worker Инициировано столбец указывает сборки, запущенные через Deploy Hook, по имени хука и deploy hook метка.

Если вам нужно проверять эти сборки программно, используйте Получить список сборок для Worker в справочнике Builds API. Сборки, запущенные хуком, записываются с build_trigger_source: "deploy_hook".

Большинство headless CMS платформ поддерживают вебхуки, которые вызывают ваш Deploy Hook URL при изменении контента. Общая настройка одинакова для всех платформ:

1. Найдите настройки вебхуков или интеграций в вашей CMS.
2. Создайте новый вебхук и вставьте URL вашего Deploy Hook в качестве целевого URL.
3. Выберите события, которые должны запускать webhook (например, publish, unpublish или update).

Инструкции для вашей платформы см. в документации CMS. Среди популярных платформ с поддержкой вебхуков: Contentful, Sanity, Strapi, Storyblok, DatoCMS и Prismic.

Если один и тот же Deploy Hook срабатывает повторно до того, как предыдущая сборка полностью запустится, Workers Builds не создаёт дублирующую сборку, а возвращает уже выполняющуюся сборку.

Если внешняя система отправляет один и тот же Deploy Hook дважды подряд с небольшим интервалом:

1. Первый запрос создаёт сборку.
2. Если второй запрос поступает, пока эта сборка ещё queued или initializing, повторная сборка не создаётся.
3. Вместо этого в ответе возвращается уже существующий build_uuid и задаёт already_exists к true.

Пример ответа при возврате уже существующей ожидающей сборки:

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "build_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "queued",
    "created_on": "2026-01-21T18:50:00Z",
    "already_exists": true
  }
}

После того как более ранняя сборка пройдет initializing, последующий POST запрос создает новую сборку в обычном режиме. Благодаря этому Deploy Hooks можно безопасно использовать с системами, которые повторяют webhook-запросы или генерируют серии событий обновления контента.

Worker, который получает /deploy команду из Slack, которая запускает сборку:

export default {
	async fetch(request, env) {
		const body = await request.formData();
		const command = body.get("command");
		const token = body.get("token");

		if (token !== env.SLACK_VERIFICATION_TOKEN) {
			return new Response("Unauthorized", { status: 401 });
		}

		if (command === "/deploy") {
			const res = await fetch(env.DEPLOY_HOOK_URL, { method: "POST" });
			const { result } = await res.json();
			return new Response(`Build started: ${result.build_uuid}`);
		}

		return new Response("Unknown command", { status: 400 });
	},
};

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const body = await request.formData();
    const command = body.get("command");
    const token = body.get("token");

    if (token !== env.SLACK_VERIFICATION_TOKEN) {
      return new Response("Unauthorized", { status: 401 });
    }

    if (command === "/deploy") {
      const res = await fetch(env.DEPLOY_HOOK_URL, { method: "POST" });
      const { result } = await res.json<{ result: { build_uuid: string } }>();
      return new Response(`Build started: ${result.build_uuid}`);
    }

    return new Response("Unknown command", { status: 400 });
  },
};

Worker с Cron Trigger который пересобирается каждый час:

export default {
	async scheduled(event, env) {
		await fetch(env.DEPLOY_HOOK_URL, { method: "POST" });
	},
};

export default {
  async scheduled(event: ScheduledEvent, env: Env): Promise<void> {
    await fetch(env.DEPLOY_HOOK_URL, { method: "POST" });
  },
};

• Храните URL-адреса Deploy Hook в переменных окружения или в менеджере секретов, но никогда в исходном коде или в общедоступных файлах конфигурации.
• Ограничьте доступ к URL только теми системами, которым он нужен.
• Если URL-адрес скомпрометирован или вы подозреваете несанкционированное использование, немедленно удалите Deploy Hook и создайте новый. Старый URL-адрес перестаёт работать сразу после удаления.

Если ваша внешняя система поддерживает пользовательские заголовки, вы можете вызывать эндпоинт для ручного запуска сборки с токеном API в Authorization заголовок. Это дает вам аутентификацию на основе токена и возможность выбирать ветку для каждого запроса. Пошаговое руководство смотрите в Запустить сборку вручную.

Deploy Hooks ограничены 10 сборками в минуту на Worker и 100 сборками в минуту на аккаунт. Полный список ограничений Workers Builds см. Лимиты и цены.