Building: The steps block

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

Steps are the building blocks of your course, and they are defined in config.yml. Steps are triggered by events, and execute actions.

Options for steps

A step is composed of the following fields:

Field	Required	Description
title	✓	The title of the step. Appears in the the course page in Learning Lab, and is used for notifications on course progress.
description	✓	A longer description of the action expected in the step. Displayed below the step title, and used for notifications on course progress.
video		A YouTube or Vimeo embed link, to include a video in the step. The video will appear in the progress tab after a user has registered for the course.
event	✓	An webhook event name from the GitHub API. Used to trigger the step.
link		A link to a section in the repository, usually an issue or pull request. Used to help the learner locate where they're expected to interact for the existing step.
actions	✓	A list of actions that will execute when the step is triggered. The completion of all the actions in a step is required for the step to be marked complete.

Usage examples

Example:

steps:
  - title: Install your first GitHub Apps
    description: Learn what GitHub Apps are and how to install them
    event: issues.closed
    link: '{{ repoUrl }}/issues/1'
    actions:
    - type: updateBranchProtection
    - type: createPullRequest
      title: Trigger the app
      head: add-to-list
      body: 02_trigger-wip.md
      action_id: first_pr
    - type: respond
      with: 01_successful-close.md
      data:
        url: '%actions.first_pr.data.html_url%'

  - title: Trigger the WIP app
    description: Once installed, learn how to interact with the app
    event: "pull_request.edited"
    link: '{{ repoUrl }}/pull/1'
    actions:
      - type: gate
        left: '%payload.pull_request.title%'
        operator: search
        right: WIP
        else:
          - type: respond
            with: 02_WIP-error-message.md
      - type: mergeBranch
        head: finish-list
        base: add-to-list
      - type: respond
        with: 02_adding-smee.md
        data:
         repoUrl: '%payload.repository.html_url%'

Keeping data from actions persistent

In some cases, you might want to persist data across actions in a step, or even propagate data to responses. Consider the following scenario:

1. Learner comments on issue #1, as instructed by Learning Lab.
2. Learning Lab opens issue #2.
3. Learning Lab closes issue #1.
4. Learning Lab directs the user to issue #2 with a link.

This is a common scenario, that presents two challenges:

• the payload from the event that triggers a step (issue_comment.created, in this case) doesn't contain information we need to perform an action (the URL of issue #2, in order to link the user).
• we'd like the response text to link the user to a newly created issue, something which we can't plan for only with Markdown

We can, however, get issue #2's URL to persist across the actions in this step, and to the response file, as follows:

title: Point users to a new issue and close this one
steps:
  - title: Comment on this issue
    event: issue_comment.created
    actions:
      - type: createIssue
        title: New issue
        body: an-issue.md
        # Store the response for this new issue by assigning an action_id
        action_id: new_issue

        # Close the issue the user just commented on
      - type: closeIssue

        # Respond in the issue the user just commented on
      - type: respond
        with: a-response.md
        # Include a `data` object to provide some template variables
        data:
          # Reference the response of the `new_issue` action
          nextIssueUrl: '%actions.new_issue.data.html_url%'

In this example, identify the API response from the createIssue action with action_id: new_issue. We can replace new_issue with any identifier we desire. This allows us to later refer to that information inside of an actions array: '%actions.new_issue.data.html_url%'.

To pass it into the text of a response, we can include it in the data key, and give it a variable name. We can then refer to it in a-response.md as follows:

Great! Move on to the next issue, which is found at: {{ nextIssueUrl }}

Sample configs

The best way to get familiar with YAML, actions, and payloads, is to start building your own course. If you'd like, you can explore more examples and use cases from our own courses like those above, and you can brush up on each action's documentation and syntax.