Trigger the app

[github-learning-lab[bot]]

Triggering GitHub Apps

Actions that a person or tool takes on GitHub can be used to trigger events. Creating an issue, making a commit, or leaving a comment, to name a few, are logged on GitHub. If GitHub doesn't use it, it can still be useful to other applications.

When you install an app, you give the app permission to receive some of this data from GitHub. That data allows the apps to react in ways that are useful to you. You can also allow the app to send information back, or change information completely.

It's important to mention that GitHub Apps are not people. You can't interact with them by doing things like using an @mention, or assigning them to review your work. On the other hand, they can do things that humans can't - like crunch big data, piece together networks of information and find bugs or errors that people wouldn't.

App components

An app is like a home security system. It's equipped to watch your house at all times, but only notifies you for specific criteria. When you install a home security system, you need to worry about a few components:

• Electricity to have the power to run continuously. You don't want failure when you aren't watching.
• Standard behaviors to detect things like movement, noise, and doors opening. You don't want to have to program it to understand these actions -- you want to select how it responds to them.
• A location that will be watched.
• A notification delivery service -- either to your phone, a dedicated security service, or both.

Just like a home security system, a GitHub App only watches for specific actions, and then responds in predetermined ways.

Step 2: Trigger the WIP app

WIP is a common abbreviation to mean work in progress.

The app you've just installed is concerned with one action: changing the title of a pull request. Let's test it out and see what the result is by updating the title of this pull request.

:keyboard: Activity: Test the app by editing the pull request title

1. To the right of the pull request title, click the Edit button
2. Add WIP to the beginning of the title
3. Click Save

---

After changing the title, look for my response in this pull request

[github-learning-lab[bot]]

Nice job! Something changed on this repo when you added the "WIP" command. Let's try to get more insight into our app before we look at those changes.

Breaking down the WIP app components

• Electricity: Since this is a Probot app, the power to run comes from deployment, set up by the app creators. We don't need to worry about this until we build an app ourselves.
• Standard behaviors: GitHub has a list of documented events that can alert an app.
• Location: Apps are designed to look for pre-determined events in whichever repositories they've been installed. On installation, it has to ask permission for each event type that it wants to monitor.
• Notification service: If the expected action occurs, a notification delivery is sent to the app as a webhook payload -- a specific set of data transmitted via GitHub's API.

GitHub Apps will then process this data in the background, responding to the repository with their expected default actions.

Extra credit: For more information about webhooks, we recommend this GitHub Community Forum article.

Step 3: Looking under the hood

For the next exercise, let's add our own notification service to get a better idea of what apps are receiving behind the scenes.

:keyboard: Activity: Adding a webhook payload delivery service

1. Navigate to https://smee.io/ in another tab or window (keep this tab open for the rest of the course).
2. Click Start a new channel
3. Copy your unique "Webhook Proxy URL"
4. In your webhooks settings, click Add webhook
5. Paste your unique smee.io URL in the "Payload URL" field
6. Choose application/json in the Content type dropdown
7. Leave the "Secret" field blank
8. For "Which events would you like to trigger this webhook?", select Send me everything
9. Click Add webhook
10. Return to this pull request and paste your smee.io URL as a comment

---

Look for my response in a comment on this pull request

Sometimes I respond too fast for the page to update! If you perform an expected action and don't see a response from me, wait a few seconds and refresh the page for your next steps.

[codewear]

https://smee.io/xrfFGzsrPfh2wzb4

[github-learning-lab[bot]]

Nice work adding smee.io!

WIP on the surface

When you added "WIP" to the title of this pull request, something changed. Do you see that the pull request's status is "pending" with a yellow dot? This is to block merging while the title includes "WIP".

Let's breakdown how WIP works:

1. The app listens specifically for a change to a pull request title
2. When a pull request title changes, the app searches for the key-word, "WIP"
3. If the search finds "WIP", the app sends a request to GitHub's API to block merging in that pull request

Step 4: Watching for webhooks

Let's use this next activity to find out what's happening behind the scenes.

:keyboard: Activity: Remove WIP from pull request title

When you made this pull request a work in progress, I took it as a cue to add some good content to this repository! Now that we've got some real work, let's remove the WIP label so that we can merge.

1. To the right of the pull request title, click the Edit button
2. Remove WIP from the title
3. Click Save

---

Look for my response in a comment on this pull request

[github-learning-lab[bot]]

WIP below the surface

Since installation, smee.io has been running patiently in the background and keeping a ledger of each webhook event that we've performed on the repository.

When you edited the pull request title, that triggered a specific type of event.

When that event was triggered, it sent a payload of data to our app. Each type of event delivers a different payload template to the app. When customizing or creating apps, having this knowledge becomes crucial.

Step 5: Name the event

Can you tell which type of event was sent back to the application when you changed the pull request header?

:keyboard: Activity: Connecting actions on GitHub to events and payloads

1. Return to your unique smee.io link, accessible via your settings if you closed it
2. Identify the webhook event that was triggered. Remember, you edited the pull request title
3. Post the event exactly as it's written in smee.io in a comment on this pull request

---

Look for my response in a comment on this pull request

[codewear]

pull_request

[github-learning-lab[bot]]

Perfect! As you might guess, pull_request is a broad event.

In the next exercise, we'll take a look at how apps can take general event payloads and turn those into specific responses via the API.

Step 6: Merging

After you removed WIP from the pull request title, the pull request was unblocked. Now, you're able to merge.

:keyboard: Activity: Merge

1. Merge this pull request, and delete your branch

Sometimes I respond too fast for the page to update! If you perform an expected action and don't see a response from me, wait a few seconds and refresh the page for your next steps.

[github-learning-lab[bot]]

Step 7: Explore another app

Now that we've explored the WIP app, let's move onto what request info can do. We'll use request info to learn about how GitHub's API, webhooks, and configuration files can combine to give apps customized repository automation.

:keyboard: Activity: Open a pull request

1. Open a pull request using this link, without changing the title or body

---

I'll respond in your new pull request