From 6b1c6174d0df40c90edfd7526496baabb1dd159d Mon Sep 17 00:00:00 2001 From: Tim Rogers Date: Fri, 4 Nov 2022 10:33:14 +0000 Subject: [PATCH] Add docs for the new "webhook forwarding" GitHub CLI feature (#32040) Co-authored-by: Sarah Edwards --- ...iguring-your-server-to-receive-payloads.md | 2 +- .../webhooks/creating-webhooks.md | 18 ++++++-- .../webhooks-and-events/webhooks/index.md | 1 + .../receiving-webhooks-with-the-github-cli.md | 46 +++++++++++++++++++ content/rest/guides/building-a-ci-server.md | 16 +++++-- content/rest/guides/delivering-deployments.md | 16 +++++-- data/features/cli-webhook-forwarding.yml | 6 +++ 7 files changed, 93 insertions(+), 12 deletions(-) create mode 100644 content/developers/webhooks-and-events/webhooks/receiving-webhooks-with-the-github-cli.md create mode 100644 data/features/cli-webhook-forwarding.yml diff --git a/content/developers/webhooks-and-events/webhooks/configuring-your-server-to-receive-payloads.md b/content/developers/webhooks-and-events/webhooks/configuring-your-server-to-receive-payloads.md index bc09b2ff7b..293c719dda 100644 --- a/content/developers/webhooks-and-events/webhooks/configuring-your-server-to-receive-payloads.md +++ b/content/developers/webhooks-and-events/webhooks/configuring-your-server-to-receive-payloads.md @@ -26,7 +26,7 @@ to handle incoming payloads. ## Writing the server We want our server to listen to `POST` requests, at `/payload`, -because that's where we told GitHub our webhook URL was. Because we're using ngrok to expose +because that's where we told GitHub our webhook URL was. Because we're using `ngrok` to expose our local environment, we don't need to set up a real server somewhere online, and can happily test out our code locally. diff --git a/content/developers/webhooks-and-events/webhooks/creating-webhooks.md b/content/developers/webhooks-and-events/webhooks/creating-webhooks.md index 4891b1b676..db196327e8 100644 --- a/content/developers/webhooks-and-events/webhooks/creating-webhooks.md +++ b/content/developers/webhooks-and-events/webhooks/creating-webhooks.md @@ -14,16 +14,28 @@ topics: --- Now that we understand [the basics of webhooks][webhooks-overview], let's go through the process of building out our own webhook-powered integration. In this tutorial, we'll create a repository webhook that will be responsible for listing out how popular our repository is, based on the number of issues it receives per day. -Creating a webhook is a two-step process. You'll first need to set up how you want your webhook to behave through {% data variables.product.product_name %}: what events should it listen to. After that, you'll set up your server to receive and manage the payload. +Creating a webhook is a two-step process. You'll first need to set up what events you webhook should listen to. After that, you'll set up your server to receive and manage the payload. {% data reusables.webhooks.webhooks-rest-api-links %} ## Exposing localhost to the internet -For the purposes of this tutorial, we're going to use a local server to receive messages from {% data variables.product.prodname_dotcom %}. So, first of all, we need to expose our local development environment to the internet. We'll use ngrok to do this. ngrok is available, free of charge, for all major operating systems. For more information, see [the `ngrok` download page](https://ngrok.com/download). +For the purposes of this tutorial, we're going to use a local server to receive webhook events from {% data variables.product.prodname_dotcom %}. -After installing `ngrok`, you can expose your localhost by running `./ngrok http 4567` on the command line. 4567 is the port number on which our server will listen for messages. You should see a line that looks something like this: +First of all, we need to expose our local development environment to the internet so {% data variables.product.prodname_dotcom %} can deliver events. We'll use [`ngrok`](https://ngrok.com) to do this. + +{% ifversion cli-webhook-forwarding %} +{% note %} + +**Note:** Alternatively, you can use webhook forwarding to set up your local environment to receive webhooks. For more information, see "[Receiving webhooks with the GitHub CLI](/developers/webhooks-and-events/webhooks/receiving-webhooks-with-the-github-cli)." + +{% endnote %} +{% endif %} + +`ngrok` is available, free of charge, for all major operating systems. For more information, see [the `ngrok` download page](https://ngrok.com/download). + +After installing `ngrok`, you can expose your localhost by running `./ngrok http 4567` on the command line. `4567` is the port number on which our server will listen for messages. You should see a line that looks something like this: ```shell $ Forwarding http://7e9ea9dc.ngrok.io -> 127.0.0.1:4567 diff --git a/content/developers/webhooks-and-events/webhooks/index.md b/content/developers/webhooks-and-events/webhooks/index.md index 1bdcd3275a..bd2ffe71dd 100644 --- a/content/developers/webhooks-and-events/webhooks/index.md +++ b/content/developers/webhooks-and-events/webhooks/index.md @@ -14,6 +14,7 @@ children: - /configuring-your-server-to-receive-payloads - /testing-webhooks - /securing-your-webhooks + - /receiving-webhooks-with-the-github-cli - /webhook-events-and-payloads --- diff --git a/content/developers/webhooks-and-events/webhooks/receiving-webhooks-with-the-github-cli.md b/content/developers/webhooks-and-events/webhooks/receiving-webhooks-with-the-github-cli.md new file mode 100644 index 0000000000..882d8941c7 --- /dev/null +++ b/content/developers/webhooks-and-events/webhooks/receiving-webhooks-with-the-github-cli.md @@ -0,0 +1,46 @@ +--- +title: Receiving webhooks with the GitHub CLI +intro: 'You can use the {% data variables.product.prodname_cli %} to test webhooks in your development environment without the complexity of port forwarding or third-party tools.' +versions: + feature: 'cli-webhook-forwarding' +topics: + - Webhooks +shortTitle: Receiving webhooks with the GitHub CLI +--- +## About receiving webhooks with {% data variables.product.prodname_cli %} + +{% note %} + +**Note**: Receiving webhooks with the {% data variables.product.prodname_cli %} is currently in limited public beta and subject to change. To sign up for the beta, reply to our GitHub Community [discussion](https://github.com/orgs/community/discussions/38261). You may not be added immediately. You will receive an email notification once you have been added to the beta. + +{% endnote %} + +When you make changes to your integration code, running the code in a local environment lets you test and iterate quickly without deploying the code. You can use {% data variables.product.prodname_cli %} to forward webhooks to your local environment. + +{% note %} + +**Note:** Webhook forwarding in the {% data variables.product.prodname_cli %} only works with repository and organization webhooks. If you want to test sponsorship, GitHub App, enterprise, or Marketplace webhooks locally, you'll need to do this manually. For more information, see "[Creating webhooks](/developers/webhooks-and-events/webhooks/creating-webhooks)." + +{% endnote %} + +## Recieving webhooks with {% data variables.product.prodname_cli %} + +{% data reusables.cli.cli-learn-more %} + +1. To install the {% data variables.product.prodname_cli %} extension to enable webhook forwarding, use the `extension install` subcommand. + + ```sh + gh extension install cli/gh-webhook + ``` + + +1. Start your application locally, and take a note of the URL where it's expecting to receive webhooks. This guide assumes that your application is listening for webhook events at `http://localhost:3000/webhook`. + +1. To set up webhooks to be delivered to your application, run the `webhook forward` subcommand. Replace `REPOSITORY` with the name of your repository. For example, `monalisa/octocat`. Replace `EVENTS` with a comma-separated list of the events that you want to receive. For example, `issues,pull_request`. Replace `URL` with the local URL where your application expects to receive webhooks. For example, `"http://localhost:3000/webhook"`. To listen for organization webhooks instead of repository webhooks, replace the `--repo` flag with the `--org` flag. For example `--org="octo-org"`. + + + ```sh + gh webhook forward --repo=REPOSITORY --events=EVENTS --url=URL + ``` + + Leave the command running in the background. It will receive all of the specified events for the specified repository and forward them to your webhook handler running at the specified URL. diff --git a/content/rest/guides/building-a-ci-server.md b/content/rest/guides/building-a-ci-server.md index afe94b461f..2bb9ae3ff5 100644 --- a/content/rest/guides/building-a-ci-server.md +++ b/content/rest/guides/building-a-ci-server.md @@ -29,9 +29,17 @@ Our CI system and host server will be figments of our imagination. They could be Travis, Jenkins, or something else entirely. The crux of this guide will be setting up and configuring the server managing the communication. -If you haven't already, be sure to [download ngrok][ngrok], and learn how +If you haven't already, [download `ngrok`][ngrok], and learn how to [use it][using ngrok]. We find it to be a very useful tool for exposing local -connections. +applications to the internet. + +{% ifversion cli-webhook-forwarding %} +{% note %} + +**Note:** Alternatively, you can use webhook forwarding to set up your local environment to receive webhooks. For more information, see "[Receiving webhooks with the GitHub CLI](/developers/webhooks-and-events/webhooks/receiving-webhooks-with-the-github-cli)." + +{% endnote %} +{% endif %} Note: you can download the complete source code for this project [from the platform-samples repo][platform samples]. @@ -54,14 +62,14 @@ end (If you're unfamiliar with how Sinatra works, we recommend [reading the Sinatra guide][Sinatra].) Start this server up. By default, Sinatra starts on port `4567`, so you'll want -to configure ngrok to start listening for that, too. +to configure `ngrok` to start listening for that, too. In order for this server to work, we'll need to set a repository up with a webhook. The webhook should be configured to fire whenever a Pull Request is created, or merged. Go ahead and create a repository you're comfortable playing around in. Might we suggest [@octocat's Spoon/Knife repository](https://github.com/octocat/Spoon-Knife)? After that, you'll create a new webhook in your repository, feeding it the URL -that ngrok gave you, and choosing `application/x-www-form-urlencoded` as the +that `ngrok` gave you, and choosing `application/x-www-form-urlencoded` as the content type: ![A new ngrok URL](/assets/images/webhook_sample_url.png) diff --git a/content/rest/guides/delivering-deployments.md b/content/rest/guides/delivering-deployments.md index 44be60c989..48dab8b880 100644 --- a/content/rest/guides/delivering-deployments.md +++ b/content/rest/guides/delivering-deployments.md @@ -32,9 +32,17 @@ Our CI system and host server will be figments of our imagination. They could be Heroku, Amazon, or something else entirely. The crux of this guide will be setting up and configuring the server managing the communication. -If you haven't already, be sure to [download ngrok][ngrok], and learn how +If you haven't already, be sure to [download `ngrok`][ngrok], and learn how to [use it][using ngrok]. We find it to be a very useful tool for exposing local -connections. +applications to the internet. + +{% ifversion cli-webhook-forwarding %} +{% note %} + +**Note:** Alternatively, you can use webhook forwarding to set up your local environment to receive webhooks. For more information, see "[Receiving webhooks with the GitHub CLI](/developers/webhooks-and-events/webhooks/receiving-webhooks-with-the-github-cli)." + +{% endnote %} +{% endif %} Note: you can download the complete source code for this project [from the platform-samples repo][platform samples]. @@ -57,14 +65,14 @@ end (If you're unfamiliar with how Sinatra works, we recommend [reading the Sinatra guide][Sinatra].) Start this server up. By default, Sinatra starts on port `4567`, so you'll want -to configure ngrok to start listening for that, too. +to configure `ngrok` to start listening for that, too. In order for this server to work, we'll need to set a repository up with a webhook. The webhook should be configured to fire whenever a pull request is created, or merged. Go ahead and create a repository you're comfortable playing around in. Might we suggest [@octocat's Spoon/Knife repository](https://github.com/octocat/Spoon-Knife)? After that, you'll create a new webhook in your repository, feeding it the URL -that ngrok gave you, and choosing `application/x-www-form-urlencoded` as the +that `ngrok` gave you, and choosing `application/x-www-form-urlencoded` as the content type: ![A new ngrok URL](/assets/images/webhook_sample_url.png) diff --git a/data/features/cli-webhook-forwarding.yml b/data/features/cli-webhook-forwarding.yml new file mode 100644 index 0000000000..d09d1b1bfd --- /dev/null +++ b/data/features/cli-webhook-forwarding.yml @@ -0,0 +1,6 @@ +# Issue #8501 +# Webhook forwarding with GitHub CLI + +versions: + fpt: '*' + ghec: '*'