Introducción
En este tutorial se muestra cómo escribir código para crear una GitHub App que realice una solicitud de API en respuesta a un evento de webhook. En concreto, cuando se abre una solicitud de cambios en un repositorio al que se concedió acceso a la aplicación, esta recibirá un evento de webhook de solicitud de cambios. Después, la aplicación usará la API de GitHub para agregar un comentario a la solicitud de cambios.
En este tutorial, vas a usar el equipo o codespace como servidor mientras desarrollas la aplicación. Una vez que la aplicación esté lista para su uso en producción, debes implementarla en un servidor dedicado.
En este tutorial se usa JavaScript, pero puedes usar cualquier lenguaje de programación que se pueda ejecutar en el servidor.
Acerca de webhooks
Al registrar una instancia de GitHub App, puedes especificar una dirección URL de webhook y suscribirte a eventos de webhook. Cuando la actividad en GitHub desencadena un evento al que la aplicación está suscrita, GitHub envía un evento de webhook a la URL del webhook de la aplicación.
Por ejemplo, puedes suscribir tu instancia de GitHub App al evento de webhook de solicitud de incorporación de cambios. Cuando se abre una solicitud de cambios en un repositorio al que la aplicación tiene acceso, GitHub enviará un evento de webhook de solicitud de cambios a la URL del webhook de la aplicación. Si varias acciones pueden desencadenar el evento, la carga del evento incluirá un campo action
para indicar qué tipo de acción desencadenó el evento. En este ejemplo, el valor de action
sería opened
puesto que el evento se desencadenó porque se abrió una solicitud de cambios.
Si la aplicación se ejecuta en un servidor que escucha estos eventos de webhook, la aplicación puede realizar una acción cuando recibe un evento de webhook. Por ejemplo, la aplicación puede usar la API de GitHub para publicar un comentario en la solicitud de cambios cuando recibe un evento de webhook de una solicitud de este tipo.
Para obtener más información, vea «Uso de webhooks con aplicaciones de GitHub». Para más información sobre los posibles eventos y acciones de webhook, consulta "Eventos y cargas de webhook".
Requisitos previos
Este tutorial requiere que el equipo o el codespace ejecuten Node.js versión 20 o posterior y npm versión 6.12.0 o posterior. Para más información, consulta Node.js.
En este tutorial se supone que tiene conocimientos básicos de la sintaxis de JavaScript y ES6.
Configurar
Las secciones siguientes le guiarán a través de la configuración de los siguientes componentes:
- un repositorio para almacenar el código de la aplicación
- una manera de recibir webhooks localmente
- un registro de GitHub App que esté suscrito a eventos de webhook de "solicitud de incorporación de cambios", tenga permisos para agregar comentarios a este tipo de solicitudes y use una dirección URL de webhook que puedas recibir localmente.
Creación de un repositorio para almacenar el código de la aplicación
- Crea un repositorio para almacenar el código de la aplicación. Para obtener más información, vea «Crear un repositorio nuevo».
- Clona el repositorio del paso anterior. Para obtener más información, vea «Clonar un repositorio». Puedes usar un clon local o GitHub Codespaces.
- En un terminal, ve al directorio donde se almacena el clon.
- Si el directorio aún no incluye un archivo
.gitignore
, agrega un archivo.gitignore
. Agregará contenido a este archivo más adelante. Para más información sobre los archivos.gitignore
, consulta "Ignorar archivos".
Agregará más código a este repositorio en pasos posteriores.
Obtención de una dirección URL del proxy de webhook
Para desarrollar la aplicación localmente, puedes usar una dirección URL del proxy de webhook para reenviar webhooks de GitHub al equipo o codespace. En este tutorial se usa Smee.io para proporcionar una dirección URL del proxy de webhook y reenviar webhooks.
- Abra el explorador y vaya a https://smee.io/.
- Haz clic en Iniciar un nuevo canal.
- Copia la dirección URL completa en "Dirección URL del proxy de webhook". La usarás en un paso posterior.
Registro de una instancia de GitHub App
En este tutorial, debes tener un registro de GitHub App que:
- Tenga webhooks activos
- Use una dirección URL de webhook que puedas recibir localmente.
- Tenga el permiso de repositorio "Solicitud de cambios"
- Esté suscrita al evento de webhook "Solicitud de cambios"
Los pasos siguientes te guiarán por el registro de una instancia de GitHub App con estas opciones. Para más información sobre la configuración de GitHub Apps, consulta "Registro de una instancia de GitHub App".
- En la esquina superior derecha de cualquier página en GitHub Enterprise Server, haga clic en su fotografía de perfil.
- Navega a la configuración de tu cuenta.
- Para una aplicación propiedad de una cuenta personal, haga clic en Configuración.
- Para una aplicación propiedad de una organización:
- Haga clic en Sus organizaciones.
- A la derecha de la organización, haga clic en Configuración.
- En la barra lateral izquierda, haz clic en Configuración del desarrollador.
- En la barra lateral de la izquierda, haga clic en GitHub Apps .
- Haga clic en New GitHub App (Nueva aplicación GitHub).
- En "Nombre de la aplicación de GitHub", escribe un nombre para la aplicación. Por ejemplo,
USERNAME-webhook-test-app
dondeUSERNAME
es el nombre de usuario de GitHub. - En "URL de la página principal", escribe la dirección URL de la aplicación. Por ejemplo, puedes usar la dirección URL del repositorio que creaste para almacenar el código de la aplicación.
- Omite las secciones "Identificación y autorización de usuarios" y "Pasos posteriores a la instalación" de este tutorial. Para más información acerca de esta configuración, consulta "Registro de una instancia de GitHub App".
- Asegúrate de que Activo esté seleccionado en "Webhooks".
- En "Dirección URL de webhook", escribe la dirección URL del proxy de webhook anterior. Para más información, consulta "Obtención de una dirección URL del proxy de webhook".
- En "Secreto de webhook", escribe una cadena aleatoria. Usarás esta cadena más adelante.
- En "Permisos de repositorio", junto a "Solicitudes de cambios", selecciona Leer y escribir.
- En "Suscripción a los eventos", selecciona Solicitud de cambios.
- En "¿Dónde se puede instalar esta aplicación de GitHub?", selecciona Solo en esta cuenta. Puedes cambiar esto más adelante si quieres publicar la aplicación.
- Haga clic en Create GitHub App (Crear aplicación de GitHub).
Escritura del código de la aplicación
Las secciones siguientes te indicarán cómo escribir código para que la aplicación responda a eventos de webhook.
Instalar dependencias
En este tutorial se usa el módulo octokit
de GitHub para controlar los eventos de webhook y realizar solicitudes de API. Para más información sobre Octokit.js, consulta "Scripting con la API de REST y JavaScript" y el archivo LÉAME de Octokit.js.
En este tutorial se usa el módulo dotenv
para leer información sobre la aplicación desde un archivo .env
. Para más información, consulta dotenv.
En este tutorial se usa Smee.io para reenviar webhooks de GitHub al servidor local. Para más información, consulta smee-client.
- En un terminal, ve al directorio donde se almacena el clon.
- Ejecuta
npm init --yes
para crear un archivopackage.json
con los valores predeterminados de npm. - Ejecute
npm install octokit
. - Ejecute
npm install dotenv
. - Ejecute
npm install smee-client --save-dev
. Puesto que solo usarás Smee.io para reenviar webhooks mientras desarrollas la aplicación, esta es una dependencia de desarrollo. - Agregue
node_modules
al archivo.gitignore
.
Almacenamiento de la información de identificación y las credenciales de la aplicación
En este tutorial se muestra cómo almacenar las credenciales y la información de identificación de la aplicación como variables de entorno en un archivo .env
. Cuando implementes la aplicación, puede que quieras cambiar la forma en que se almacenan las credenciales. Para más información, consulta "Implementación de la aplicación".
Asegúrate de que estás en una máquina segura antes de realizar estos pasos, ya que vas a almacenar las credenciales localmente.
-
En el terminal, ve al directorio donde se almacena el clon.
-
Cree un archivo llamado
.env
en el nivel superior de este directorio. -
Agregue
.env
al archivo.gitignore
. Esto evitará que confirmes accidentalmente las credenciales de la aplicación. -
Agrega el siguiente contenido al archivo
.env
: ReemplazaYOUR_HOSTNAME
por el nombre de tu instancia de GitHub Enterprise Server. Actualizarás los demás valores en un paso posterior.Text APP_ID="YOUR_APP_ID" WEBHOOK_SECRET="YOUR_WEBHOOK_SECRET" PRIVATE_KEY_PATH="YOUR_PRIVATE_KEY_PATH" ENTERPRISE_HOSTNAME="YOUR_HOSTNAME"
APP_ID="YOUR_APP_ID" WEBHOOK_SECRET="YOUR_WEBHOOK_SECRET" PRIVATE_KEY_PATH="YOUR_PRIVATE_KEY_PATH" ENTERPRISE_HOSTNAME="YOUR_HOSTNAME"
-
Ve a la página "Configuración" de la aplicación:
-
En la esquina superior derecha de cualquier página en GitHub Enterprise Server, haga clic en su fotografía de perfil.
-
Navega a la configuración de tu cuenta.
- Para una aplicación propiedad de una cuenta personal, haga clic en Configuración.
- Para una aplicación propiedad de una organización:
- Haga clic en Sus organizaciones.
- A la derecha de la organización, haga clic en Configuración.
-
En la barra lateral izquierda, haz clic en Configuración del desarrollador.
-
En la barra lateral de la izquierda, haga clic en GitHub Apps .
-
Junto al nombre de la aplicación, haz clic en Editar.
-
-
En la página de configuración de la aplicación, junto a "Id. de la aplicación", busca el identificador de la aplicación.
-
En el archivo
.env
, reemplazaYOUR_APP_ID
por el identificador de la aplicación. -
En la página de configuración de la aplicación, en "Claves privadas", haz clic en Generar una clave privada. Verás una llave privada en formato PEM que se descarga en tu ordenador. Para obtener más información, vea «Administración de claves privadas para aplicaciones de GitHub».
-
Si usas un codespace, mueve el archivo PEM descargado al codespace para que este pueda acceder al archivo.
-
En el archivo
.env
, reemplazaYOUR_PRIVATE_KEY_PATH
por la ruta de acceso completa a la clave privada, incluida la extensión.pem
. -
En el archivo
.env
, reemplazaYOUR_WEBHOOK_SECRET
por el secreto de webhook de la aplicación. Si has olvidado el secreto de webhook, en "Secreto de webhook (opcional)", haz clic en Cambiar secreto. Especifica un nuevo secreto y, a continuación, haz clic en Guardar cambios.
Adición de código para responder a eventos de webhook
En el nivel superior del directorio donde está almacenado tu clon, crea un archivo JavaScript para guardar el código de tu aplicación. En este tutorial se llamará al archivo app.js
.
Agregue el siguiente código a app.js
. El código incluye anotaciones que explican cada parte.
// These are the dependencies for this file. // // You installed the `dotenv` and `octokit` modules earlier. The `@octokit/webhooks` is a dependency of the `octokit` module, so you don't need to install it separately. The `fs` and `http` dependencies are built-in Node.js modules. import dotenv from "dotenv"; import {App, Octokit} from "octokit"; import {createNodeMiddleware} from "@octokit/webhooks"; import fs from "fs"; import http from "http"; // This reads your `.env` file and adds the variables from that file to the `process.env` object in Node.js. dotenv.config(); // This assigns the values of your environment variables to local variables. const appId = process.env.APP_ID; const webhookSecret = process.env.WEBHOOK_SECRET; const privateKeyPath = process.env.PRIVATE_KEY_PATH; const enterpriseHostname = process.env.ENTERPRISE_HOSTNAME; // This reads the contents of your private key file. const privateKey = fs.readFileSync(privateKeyPath, "utf8"); // This creates a new instance of the Octokit App class. const app = new App({ appId: appId, privateKey: privateKey, webhooks: { secret: webhookSecret }, Octokit: Octokit.defaults({ baseUrl: `https://${enterpriseHostname}/api/v3`, }), }); // This defines the message that your app will post to pull requests. const messageForNewPRs = "Thanks for opening a new PR! Please follow our contributing guidelines to make your PR easier to review."; // This adds an event handler that your code will call later. When this event handler is called, it will log the event to the console. Then, it will use GitHub's REST API to add a comment to the pull request that triggered the event. async function handlePullRequestOpened({octokit, payload}) { console.log(`Received a pull request event for #${payload.pull_request.number}`); try { await octokit.request("POST /repos/{owner}/{repo}/issues/{issue_number}/comments", { owner: payload.repository.owner.login, repo: payload.repository.name, issue_number: payload.pull_request.number, body: messageForNewPRs, headers: { "x-github-api-version": "2022-11-28", }, }); } catch (error) { if (error.response) { console.error(`Error! Status: ${error.response.status}. Message: ${error.response.data.message}`) } console.error(error) } }; // This sets up a webhook event listener. When your app receives a webhook event from GitHub with a `X-GitHub-Event` header value of `pull_request` and an `action` payload value of `opened`, it calls the `handlePullRequestOpened` event handler that is defined above. app.webhooks.on("pull_request.opened", handlePullRequestOpened); // This logs any errors that occur. app.webhooks.onError((error) => { if (error.name === "AggregateError") { console.error(`Error processing request: ${error.event}`); } else { console.error(error); } }); // This determines where your server will listen. // // For local development, your server will listen to port 3000 on `localhost`. When you deploy your app, you will change these values. For more information, see "[Deploy your app](#deploy-your-app)." const port = 3000; const host = 'localhost'; const path = "/api/webhook"; const localWebhookUrl = `http://${host}:${port}${path}`; // This sets up a middleware function to handle incoming webhook events. // // Octokit's `createNodeMiddleware` function takes care of generating this middleware function for you. The resulting middleware function will: // // - Check the signature of the incoming webhook event to make sure that it matches your webhook secret. This verifies that the incoming webhook event is a valid GitHub event. // - Parse the webhook event payload and identify the type of event. // - Trigger the corresponding webhook event handler. const middleware = createNodeMiddleware(app.webhooks, {path}); // This creates a Node.js server that listens for incoming HTTP requests (including webhook payloads from GitHub) on the specified port. When the server receives a request, it executes the `middleware` function that you defined earlier. Once the server is running, it logs messages to the console to indicate that it is listening. http.createServer(middleware).listen(port, () => { console.log(`Server is listening for events at: ${localWebhookUrl}`); console.log('Press Ctrl + C to quit.') });
import dotenv from "dotenv";
import {App, Octokit} from "octokit";
import {createNodeMiddleware} from "@octokit/webhooks";
import fs from "fs";
import http from "http";
These are the dependencies for this file.
You installed the dotenv
and octokit
modules earlier. The @octokit/webhooks
is a dependency of the octokit
module, so you don't need to install it separately. The fs
and http
dependencies are built-in Node.js modules.
dotenv.config();
This reads your .env
file and adds the variables from that file to the process.env
object in Node.js.
const appId = process.env.APP_ID;
const webhookSecret = process.env.WEBHOOK_SECRET;
const privateKeyPath = process.env.PRIVATE_KEY_PATH;
const enterpriseHostname = process.env.ENTERPRISE_HOSTNAME;
This assigns the values of your environment variables to local variables.
const privateKey = fs.readFileSync(privateKeyPath, "utf8");
This reads the contents of your private key file.
const app = new App({
appId: appId,
privateKey: privateKey,
webhooks: {
secret: webhookSecret
},
Octokit: Octokit.defaults({
baseUrl: `https://${enterpriseHostname}/api/v3`,
}),
});
This creates a new instance of the Octokit App class.
const messageForNewPRs = "Thanks for opening a new PR! Please follow our contributing guidelines to make your PR easier to review.";
This defines the message that your app will post to pull requests.
async function handlePullRequestOpened({octokit, payload}) {
console.log(`Received a pull request event for #${payload.pull_request.number}`);
try {
await octokit.request("POST /repos/{owner}/{repo}/issues/{issue_number}/comments", {
owner: payload.repository.owner.login,
repo: payload.repository.name,
issue_number: payload.pull_request.number,
body: messageForNewPRs,
headers: {
"x-github-api-version": "2022-11-28",
},
});
} catch (error) {
if (error.response) {
console.error(`Error! Status: ${error.response.status}. Message: ${error.response.data.message}`)
}
console.error(error)
}
};
This adds an event handler that your code will call later. When this event handler is called, it will log the event to the console. Then, it will use GitHub's REST API to add a comment to the pull request that triggered the event.
app.webhooks.on("pull_request.opened", handlePullRequestOpened);
This sets up a webhook event listener. When your app receives a webhook event from GitHub with a X-GitHub-Event
header value of pull_request
and an action
payload value of opened
, it calls the handlePullRequestOpened
event handler that is defined above.
app.webhooks.onError((error) => {
if (error.name === "AggregateError") {
console.error(`Error processing request: ${error.event}`);
} else {
console.error(error);
}
});
This logs any errors that occur.
const port = 3000;
const host = 'localhost';
const path = "/api/webhook";
const localWebhookUrl = `http://${host}:${port}${path}`;
This determines where your server will listen.
For local development, your server will listen to port 3000 on localhost
. When you deploy your app, you will change these values. For more information, see "Deploy your app."
const middleware = createNodeMiddleware(app.webhooks, {path});
This sets up a middleware function to handle incoming webhook events.
Octokit's createNodeMiddleware
function takes care of generating this middleware function for you. The resulting middleware function will:
- Check the signature of the incoming webhook event to make sure that it matches your webhook secret. This verifies that the incoming webhook event is a valid GitHub event.
- Parse the webhook event payload and identify the type of event.
- Trigger the corresponding webhook event handler.
http.createServer(middleware).listen(port, () => {
console.log(`Server is listening for events at: ${localWebhookUrl}`);
console.log('Press Ctrl + C to quit.')
});
This creates a Node.js server that listens for incoming HTTP requests (including webhook payloads from GitHub) on the specified port. When the server receives a request, it executes the middleware
function that you defined earlier. Once the server is running, it logs messages to the console to indicate that it is listening.
// These are the dependencies for this file.
//
// You installed the `dotenv` and `octokit` modules earlier. The `@octokit/webhooks` is a dependency of the `octokit` module, so you don't need to install it separately. The `fs` and `http` dependencies are built-in Node.js modules.
import dotenv from "dotenv";
import {App, Octokit} from "octokit";
import {createNodeMiddleware} from "@octokit/webhooks";
import fs from "fs";
import http from "http";
// This reads your `.env` file and adds the variables from that file to the `process.env` object in Node.js.
dotenv.config();
// This assigns the values of your environment variables to local variables.
const appId = process.env.APP_ID;
const webhookSecret = process.env.WEBHOOK_SECRET;
const privateKeyPath = process.env.PRIVATE_KEY_PATH;
const enterpriseHostname = process.env.ENTERPRISE_HOSTNAME;
// This reads the contents of your private key file.
const privateKey = fs.readFileSync(privateKeyPath, "utf8");
// This creates a new instance of the Octokit App class.
const app = new App({
appId: appId,
privateKey: privateKey,
webhooks: {
secret: webhookSecret
},
Octokit: Octokit.defaults({
baseUrl: `https://${enterpriseHostname}/api/v3`,
}),
});
// This defines the message that your app will post to pull requests.
const messageForNewPRs = "Thanks for opening a new PR! Please follow our contributing guidelines to make your PR easier to review.";
// This adds an event handler that your code will call later. When this event handler is called, it will log the event to the console. Then, it will use GitHub's REST API to add a comment to the pull request that triggered the event.
async function handlePullRequestOpened({octokit, payload}) {
console.log(`Received a pull request event for #${payload.pull_request.number}`);
try {
await octokit.request("POST /repos/{owner}/{repo}/issues/{issue_number}/comments", {
owner: payload.repository.owner.login,
repo: payload.repository.name,
issue_number: payload.pull_request.number,
body: messageForNewPRs,
headers: {
"x-github-api-version": "2022-11-28",
},
});
} catch (error) {
if (error.response) {
console.error(`Error! Status: ${error.response.status}. Message: ${error.response.data.message}`)
}
console.error(error)
}
};
// This sets up a webhook event listener. When your app receives a webhook event from GitHub with a `X-GitHub-Event` header value of `pull_request` and an `action` payload value of `opened`, it calls the `handlePullRequestOpened` event handler that is defined above.
app.webhooks.on("pull_request.opened", handlePullRequestOpened);
// This logs any errors that occur.
app.webhooks.onError((error) => {
if (error.name === "AggregateError") {
console.error(`Error processing request: ${error.event}`);
} else {
console.error(error);
}
});
// This determines where your server will listen.
//
// For local development, your server will listen to port 3000 on `localhost`. When you deploy your app, you will change these values. For more information, see "[Deploy your app](#deploy-your-app)."
const port = 3000;
const host = 'localhost';
const path = "/api/webhook";
const localWebhookUrl = `http://${host}:${port}${path}`;
// This sets up a middleware function to handle incoming webhook events.
//
// Octokit's `createNodeMiddleware` function takes care of generating this middleware function for you. The resulting middleware function will:
//
// - Check the signature of the incoming webhook event to make sure that it matches your webhook secret. This verifies that the incoming webhook event is a valid GitHub event.
// - Parse the webhook event payload and identify the type of event.
// - Trigger the corresponding webhook event handler.
const middleware = createNodeMiddleware(app.webhooks, {path});
// This creates a Node.js server that listens for incoming HTTP requests (including webhook payloads from GitHub) on the specified port. When the server receives a request, it executes the `middleware` function that you defined earlier. Once the server is running, it logs messages to the console to indicate that it is listening.
http.createServer(middleware).listen(port, () => {
console.log(`Server is listening for events at: ${localWebhookUrl}`);
console.log('Press Ctrl + C to quit.')
});
Agregar un script para ejecutar el código de la aplicación
-
En el objeto
scripts
del archivopackage.json
, agrega un script denominadoserver
que ejecutanode app.js
. Por ejemplo:JSON "scripts": { "server": "node app.js" }
"scripts": { "server": "node app.js" }
Si has llamado al archivo que contiene el código de la aplicación algo distinto de
app.js
, reemplazaapp.js
por la ruta de acceso relativa al archivo que contiene el código de la aplicación. -
En el archivo
package.json
, agrega una clave de nivel superiortype
con el valormodule
. Por ejemplo:{ // rest of the JSON object, "version": "1.0.0", "description": "", "type": "module", // rest of the JSON object, }
El archivo package.json
debe tener un aspecto similar al siguiente. El valor name
y los números de versión en dependencies
y devDependencies
pueden diferir en tu caso.
{
"name": "github-app-webhook-tutorial",
"version": "1.0.0",
"description": "",
"main": "index.js",
"type": "module",
"scripts": {
"server": "node app.js"
},
"keywords": [],
"author": "",
"license": "ISC",
"dependencies": {
"dotenv": "^16.0.3",
"octokit": "^2.0.14"
},
"devDependencies": {
"smee-client": "^1.2.3"
}
}
Prueba
Siga estos pasos para probar la aplicación que creaste anteriormente.
Instalación de la aplicación
Para que la aplicación deje un comentario en las solicitudes de cambios de un repositorio, debe instalarse en la cuenta propietaria del repositorio y se debe conceder acceso a ese repositorio. Como tu aplicación es privada, solo puede instalarse en la cuenta propietaria de la aplicación.
-
En la cuenta propietaria de la aplicación que creaste, crea un nuevo repositorio en el que instalar la aplicación. Para obtener más información, vea «Crear un repositorio nuevo».
-
Ve a la página "Configuración" de la aplicación:
-
En la esquina superior derecha de cualquier página en GitHub Enterprise Server, haga clic en su fotografía de perfil.
-
Navega a la configuración de tu cuenta.
- Para una aplicación propiedad de una cuenta personal, haga clic en Configuración.
- Para una aplicación propiedad de una organización:
- Haga clic en Sus organizaciones.
- A la derecha de la organización, haga clic en Configuración.
-
En la barra lateral izquierda, haz clic en Configuración del desarrollador.
-
En la barra lateral de la izquierda, haga clic en GitHub Apps .
-
Junto al nombre de la aplicación, haz clic en Editar.
-
-
Haz clic en Página pública.
-
Haga clic en Instalar.
-
Elige Solo seleccionar repositorios.
-
Selecciona el menú desplegable Seleccionar repositorios y haz clic en el repositorio que elegiste al principio de esta sección.
-
Haga clic en Instalar.
Inicio del servidor
Para realizar pruebas, usarás el equipo o el codespace como servidor. La aplicación solo responderá a webhooks cuando se ejecute el servidor.
-
En un terminal, ve al directorio donde se almacena el código de la aplicación.
-
Para recibir los webhooks reenviados desde Smee.io, ejecuta
npx smee -u WEBHOOK_PROXY_URL -t http://localhost:3000/api/webhook
. ReemplazaWEBHOOK_PROXY_URL
por la dirección URL del proxy de webhook anterior. Si olvidaste la dirección URL, puedes encontrarla en el campo "Dirección URL de webhook" en la página de configuración de la aplicación.Deberías ver una salida con el siguiente aspecto, en la que
WEBHOOK_PROXY_URL
es la dirección URL del proxy del webhook.Forwarding WEBHOOK_PROXY_URL to http://localhost:3000/api/webhook Connected WEBHOOK_PROXY_URL
-
En una segunda ventana del terminal, ve al directorio donde se almacena el código de la aplicación.
-
Ejecute
npm run server
. El terminal debe indicar,Server is listening for events at: http://localhost:3000/api/webhook
.
Prueba de la aplicación
Ahora que el servidor está funcionando y recibiendo eventos de webhooks reenviados, prueba la aplicación abriendo una solicitud de cambios en el repositorio que seleccionaste al instalar la aplicación.
-
Abre una solicitud de cambios en el repositorio que seleccionaste al instalar la aplicación. Para obtener más información, vea «Crear una solicitud de incorporación de cambios».
Asegúrate de que usas el repositorio que seleccionaste al instalar la aplicación, no el repositorio donde se almacena el código de la aplicación. Para más información, consulta Instalación de la aplicación.
-
Vaya a la dirección URL del proxy del webhook en smee.io. Verá el evento
pull_request
. Esto indica que GitHub envió correctamente un evento de solicitud de cambios al crear una solicitud de este tipo. -
En el terminal en el que ejecutaste
npm run server
, deberías ver algo parecido a "Se ha recibido un evento de solicitud de cambios #1", donde el entero después de#
es el número de la solicitud de cambios que abriste. -
En la escala de tiempo de la solicitud de cambios, deberías ver un comentario de la aplicación.
-
En ambas ventanas de terminal, escribe Ctrl+C para detener el servidor y dejar de escuchar webhooks reenviados.
Pasos siguientes
Ahora que tienes una aplicación que responde a eventos de webhook, es posible que quieras expandir el código de la aplicación, implementar la aplicación y hacer que la aplicación sea pública.
Modificación de la aplicación
En este tutorial se muestra cómo publicar un comentario en una solicitud de cambios que abriste. Puedes actualizar el código para responder a diferentes tipos de eventos de webhook o para hacer algo diferente en respuesta al evento de webhook.
Recuerda actualizar los permisos de la aplicación si esta necesita permisos adicionales para las solicitudes de API que quieres realizar o los eventos de webhook que quieres recibir. Para obtener más información, vea «Elección de permisos para una aplicación de GitHub».
En este tutorial se almacenó todo el código en un único archivo, pero es posible que quieras mover funciones y componentes a archivos independientes.
Implementación de la aplicación
En este tutorial se muestra cómo desarrollar la aplicación localmente. Cuando estés listo para implementar la aplicación, debes realizar cambios para atenderla y mantener la credencial de la aplicación segura. Los pasos que realices dependerán del servidor que uses, pero las secciones siguientes ofrecen instrucciones generales.
Hospedaje de la aplicación en un servidor
En este tutorial se usó el equipo o codespace como servidor. Una vez que la aplicación esté lista para su uso en producción, debes implementarla en un servidor dedicado. Por ejemplo, puedes usar Azure App Service.
Actualización de la dirección URL del webhook
Una vez que tengas un servidor configurado para recibir tráfico de webhook de GitHub, actualiza la dirección URL del webhook en la configuración de la aplicación. No debes usar Smee.io para reenviar los webhooks en producción.
Actualización de las constantes port
y host
Cuando implementes la aplicación, querrás cambiar el host y el puerto donde escucha el servidor.
Por ejemplo, puedes establecer una variable de entorno PORT
en el servidor para indicar el puerto donde debe escuchar el servidor. Puedes establecer una variable de entorno NODE_ENV
en el servidor en production
. A continuación, puedes actualizar el lugar en el que el código define las constantes port
y host
para que el servidor escuche todas las interfaces de red disponibles (0.0.0.0
) en lugar de la interfaz de red local (localhost
) en el puerto de implementación:
const port = process.env.PORT || 3000; const host = process.env.NODE_ENV === 'production' ? '0.0.0.0' : 'localhost';
const port = process.env.PORT || 3000;
const host = process.env.NODE_ENV === 'production' ? '0.0.0.0' : 'localhost';
Protección de las credenciales de la aplicación
Nunca debes publicar la clave privada ni el secreto de webhook de la aplicación. En este tutorial se almacenan las credenciales de la aplicación en un archivo gitignored .env
. Cuando implementes la aplicación, debes elegir una manera segura de almacenar las credenciales y actualizar el código para obtener el valor en consecuencia. Por ejemplo, puedes almacenar las credenciales con un servicio de administración de secretos, como Azure Key Vault. Cuando se ejecuta la aplicación, puedes recuperar las credenciales y almacenarlas en variables de entorno en el servidor donde se implementa la aplicación.
Para obtener más información, vea «Procedimientos recomendados para crear una aplicación de GitHub».
Compartición de la aplicación
Si quieres compartir la aplicación con otros usuarios y organizaciones, haz que la aplicación sea pública. Para obtener más información, vea «Hacer pública o privada a una GitHub App».
Seguimiento de los procedimientos recomendados
Debes intentar seguir los procedimientos recomendados con tu instancia de GitHub App. Para obtener más información, vea «Procedimientos recomendados para crear una aplicación de GitHub».