Building: Events as triggers

	A course on GitHub Learning Lab can guide you through this step.

Every step in a course will be triggered by a webhook event sent from GitHub. All possible events are documented in Events Types & Payloads on the GitHub Developer Guide.

As a course author, you'll often want more information about the event that triggered a step. Additional information from the event comes in the event payload.

Events are defined in the step in the config.yml file:

steps:
  - title: Assign yourself
    event: issues.assigned

You can also define your step to be trigger by multiple events. This will act if either of the events were triggered:

steps:
  - title: Write some code
    event:
      - pull_request.opened
      - pull_request.synchronize

Usage examples of event payloads

Example 1:

1. A course step asks the learner to open an issue with title "Hello".
2. The learner opens an issue with the title "Hi"
3. An issues event is sent to Learning Lab.
4. The course uses the issue payload to determine that the issue's title doesn't match what was expected.

Example 2:

1. A course step asks the learner to commit to their desired branch.
2. The learner pushes to a branch called feature.
3. A push event is sent to Learning Lab.
4. The course uses the push payload to provide respond to the learner in the pull request for the branch.

Example 3:

1. A course step asks the learner to push code to a repository using continuous integration (CI).
2. The learner pushes.
3. The CI provider kicks off a build.
4. A check_run event is sent to Learning Lab.
5. The course uses the deployment payload to determine that the CI has started its build, but has not reported a completion.
6. The CI provider finishes building the repository.
7. Another check_run event is sent to Learning Lab.
8. The course uses the new deployment payload to validate that CI has completed.
9. The course marks that step complete.

Accessing event payloads

The event's entire payload is accessible using the syntax: '{{ payload }}' and passed to the response rendering engine. We'll usually access it within the list of actions. The information in the payload will vary depending on the event that it accompanies. Examples of all payloads are accessible in Events Types & Payloads.

Within the '{{ payload }}' object, we can use dot notation to access its properties. We'll use the usage examples to demonstrate.

Example 1: The issues event sends the following payload (truncated):

{
  "action": "edited",
  "issue": {
    "url": "https://api.github.com/repos/Codertocat/Hello-World/issues/2",
    "repository_url": "https://api.github.com/repos/Codertocat/Hello-World",
    "labels_url": "https://api.github.com/repos/Codertocat/Hello-World/issues/2/labels{/name}",
    "comments_url": "https://api.github.com/repos/Codertocat/Hello-World/issues/2/comments",
    "events_url": "https://api.github.com/repos/Codertocat/Hello-World/issues/2/events",
    "html_url": "https://github.com/Codertocat/Hello-World/issues/2",
    "id": 327883527,
    "node_id": "MDU6SXNzdWUzMjc4ODM1Mjc=",
    "number": 2,
    "title": "Spelling error in the README file",
    "user": {
      "login": "Codertocat",
      ...
    } 
  } 
}

The title is accessible using '{{ payload.issue.title }}'. Remember, you can access the payload's properties in the config file or in the response file using the liquid syntax.

Example 2: The push event sends the following payload (truncated):

{
  "ref": "refs/tags/simple-tag",
  "before": "a10867b14bb761a232cd80139fbd4c0d33264240",
  "after": "0000000000000000000000000000000000000000",
  "created": false,
  "deleted": true,
  "forced": false,
  "base_ref": null,
  "compare": "https://github.com/Codertocat/Hello-World/compare/a10867b14bb7...000000000000",
  "commits": [...]
}

The name of the branch is accessible at '{{ payload.ref }}'. Furthermore, we could get a URL to the diff by using '{{ payload.compare }}'.

Example 3: Each check_run event sends the following payload (truncated):

{
  "action": "rerequested",
  "check_run": {
    "id": 4,
    "head_sha": "d6fde92930d4715a2b49857d24b940956b26d2d3",
    "external_id": "",
    "url": "https://api.github.com/repos/github/hello-world/check-runs/4",
    "html_url": "http://github.com/github/hello-world/runs/4",
    "status": "completed",
    "conclusion": "neutral",
    ...
  }
}

The status of the check run is accessible at '{{ payload.action }}'. Furthermore, the previous status of the check_run is accessible at '{{ payload.check_run.status }}', and its result is at '{{ payload.check_run.conclusion }}'.