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.
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.
.gitignore
file. You can see an example .gitignore
. We recommend at minimum ignoring operating system generated files.skills-course
in the repository topics.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.
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.
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.
Each step should:
### :keyboard: Activity: Specific description
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-->
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.
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.
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.
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.