Skills

GitHub Skills Quickstart Guide

Build your own GitHub Actions-powered courses in a few simple steps.

This guide covers planning your course, building your course, and best practices for GitHub Actions-powered courses.

If you’re interested in creating single exercises with GitHub Actions, check out Project Looking Glass instead.

Take a look at our GitHub Skills courses for examples and templates.

Table of contents

Author prerequisites

Course authors should be familiar with Markdown, YAML, and GitHub Actions before starting to make their own courses.

Some courses will require knowledge of GitHub CLI and command line.

Planning your course

Write down your learning goals

Outline your steps

Set up your repository

Writing your README

Your README file will have a few sections: a header, a start step, three to five workflow steps, a finish step, and a footer.

The raw source of the README in Introduction to GitHub includes many comments you can use to guide the development of your course’s README file.

Writing your README: Header

Start with a short paragraph describing what you’ll teach. Be sure to include information on how the course is relevant to the learner. This paragraph should answer the question, “Why should I take this course?”

Include the course title in sentence case, and a concise description in emphasis.

Writing your README: Start

Wrap your start section in:

<details id=0 open>
<summary><h2>Start</h2></summary>
  
</details>

or

<!--step0-->

## How to start this course

<!--endstep0-->

A brief paragraph should describe the goal of the course, what the learner will learn, and why they should take the course.

A brief list of the following items can help the learner decide if the course is right for them:

Include clear directions on how to start the course.

Writing your README: Steps

Each step should:

Try to keep your formatting consistent so the learner can more easily find what they are looking for.

The first step is the hardest, so pick something easy! On the first step, encourage users to open new tabs for steps.

Wrap each step with the following:

<details id=1>
<summary><h2>Step N: Step title</h2></summary>

</details>

or

<!--step1

## Step 1: Step title

endstep1-->

Writing your README: Finish

In the finish section,

Wrap the finish step in the following:

<details id=X>
<summary><h2>Finish</h2></summary>

</details>

or

<!--stepX

## Finish

endstepX-->

The footer should not be included in the finish section. The footer should appear regardless of which step the learner is currently on.

Writing your Actions workflow files

Writing your Actions workflow files: Connect your steps to GitHub Actions events

Every step will have an Actions workflow file that triggers on GitHub Actions events. Start by reviewing which event corresponds with each of your steps.

Writing your Actions workflow files: Identify what GitHub Actions will need to do in each step

You can use GitHub CLI in your Actions workflows to perform almost any GitHub interaction you can think of. Write down everything each step will need to do to complete the step. Store links for reference as your work on your course.

Writing your Actions workflow files: Sections of the workflow file

Take a look at Introduction to GitHub for example workflow files.

Each workflow file has the name format: N-brief-summary.yml, where N is the step number and brief-summary describes the step. We recommend this format to make it easy to see the order the steps will run in.

Each workflow file will have a few sections, the name, describing comments, event trigger, job header, and steps.

The first section is the name:

name: Step 0, Start

Next, add comments describing what the Actions workflow will do:

# This step triggers after the learner creates a new repository from the template
# This step sets STEP to 1
# This step closes <details id=0> and opens <details id=1>

Followed by the event trigger:

# This will run every time we create push a commit to `main`
# Reference https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows
on:
  workflow_dispatch:
  push:
    branches:
      - main

Next is the job header. You can add if tags to limit the scope of the event trigger here. You’ll also need to specify runs-on to get your Actions workflow running.

jobs:
  on_start:
    name: On start
    
    # We will only run this action when:
    # 1. This repository isn't the template repository
    # Reference https://docs.github.com/en/actions/learn-github-actions/contexts
    # Reference https://docs.github.com/en/actions/learn-github-actions/expressions
    if: ${{ !github.event.repository.is_template }}}

    # We'll run Ubuntu for performance instead of Mac or Windows
    runs-on: ubuntu-latest

Last, we are finally in the steps of the Actions workflow. This is the heart of the file, where you can customize your course the most.

    steps:
      # We'll need to check out the repository so that we can edit the README
      - name: Checkout
        uses: actions/checkout@v2

      # Update README and set STEP to '1'
      - name: Update to step 1
        uses: skills/action-update-step@v1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          from_step: 0
          to_step: 1
          branch_name: my-first-branch

You may include the update step action in your course, however it is not fully required. You may also customize this script to meet the needs of your course.

Include thorough comments in your workflow files to describe each section. Other authors and your future self will thank you later.

Testing and monitoring your course

Best practices for building courses

Content

Actions workflows

Sharing your course