GitHub Actions for Beginners: Your First Workflow

github actions tutorial

Stuck wondering where to start with automation? This github actions tutorial gets you a working workflow: add one YAML file to .github/workflows in your repository, commit it, and GitHub runs it on every push.

If the terms feel new, read what is ci/cd first for the bigger picture.

Item Value
Workflow directory .github/workflows
Example file name github-actions-demo.yml
Allowed file extensions .yml or .yaml
Event that starts the example push
Runner label in the example ubuntu-latest
Checkout action in the example actions/checkout@v6

These figures come from the GitHub Docs quickstart and its markdown version. Documentation changes over time, so check the source before you rely on them.

What you need before you start

GitHub Actions is a continuous integration and continuous delivery (CI/CD) platform that automates your build, test, and deployment pipeline. You can create workflows that run tests whenever you push a change to your repository, as the quickstart describes.

The quickstart assumes very little. You need three things in place:

  • At least a basic knowledge of how to use GitHub, including repositories, branches and pull requests.
  • A repository on GitHub where you can add files.
  • Access to GitHub Actions.

If the Actions tab is not displayed under your repository name, Actions may be disabled for that repository. Check the repository’s Actions settings before you go further.

Create your first GitHub Actions workflow file

A workflow is just a file in your repository. GitHub only discovers it if you save it in a directory called .github/workflows, and you can name it anything you like as long as it ends in .yml or .yaml.

  1. Open your repository on GitHub and create a workflow file called github-actions-demo.yml in the .github/workflows directory.
  2. If that directory already exists, open it, click Add file, then Create new file. If it does not, start from the repository’s main page, click Add file, then Create new file, and type the full path .github/workflows/github-actions-demo.yml as the name. That creates both directories and the file in one step.
  3. Copy the demo YAML from the quickstart page into the file.
  4. Click Commit changes. In the dialog, either commit to the default branch or create a new branch and start a pull request, then confirm.

Committing the file to a branch triggers the push event and runs your workflow. If you chose to start a pull request you can create it, but that is not necessary for this exercise because the commit is already on a branch.

YAML is a markup language that is commonly used for configuration files. At this stage you do not need to understand every detail of the demo, so copy and paste it first and study it afterwards, as the markdown version of the quickstart suggests.

What the demo workflow does

Even without reading every line, you can recognise the building blocks of a workflow in the demo. Here is what each part does:

  • A name and a run name at the top label the workflow and each run. The run name uses a value called a context to show who triggered it.
  • The on line sets the trigger. The demo uses a push, so every push to the repository starts it.
  • The jobs section holds the work. The demo defines one job, and its runs-on line picks the runner, here ubuntu-latest.
  • Each entry under steps is either a plain command that echoes a message or an action that is reused from elsewhere.

Two of the steps are worth a closer look. One is named “Check out repository code” and uses actions/checkout@v6 to clone your repository onto the runner, and another is named “List files in the repository” and runs a listing command so you can see what was checked out.

The echo steps print details such as the event name, the runner operating system, the branch and the repository. Those details come from contexts, which the quickstart points to its Contexts reference to explain.

View your workflow results

Once the commit lands, the workflow runs on its own. You find the output in the Actions tab of your repository.

  1. On GitHub, go to the main page of the repository and click Actions.
  2. In the left sidebar, click the workflow you want to display, which in this example is “GitHub Actions Demo”.
  3. From the list of workflow runs, click the name of the run you want to see.
  4. In the left sidebar of the run page, under Jobs, click the Explore-GitHub-Actions job.
  5. Expand any step in the log to view its details.

The log shows you how each of the steps was processed. Expanding the “List files in the repository” step is a handy check, because it shows the files that were cloned to the runner.

github actions tutorial Developer workstation
A person wearing headphones sits at a desk facing multiple monitors.

Start faster with workflow templates

You do not have to write every workflow from scratch. GitHub provides preconfigured workflow templates that you can use as-is or customize to create your own workflow.

GitHub also analyzes your code and shows you templates that might be useful for your repository. For example, if your repository contains Node.js code, you will see suggestions for Node.js projects. The templates cover these groups:

  • CI: continuous integration workflows
  • Deployments: deployment workflows
  • Automation: automating workflows
  • Code Scanning: code scanning workflows
  • Pages: Pages workflows

You can browse the full list in the actions/starter-workflows repository, which the GitHub Docs quickstart links to.

Where your first workflow fits

Your demo only prints messages and lists files, but the same push trigger can run tests. That habit is the core of continuous integration best practices, so swapping the echo steps for a real test command is a natural next move.

When you are ready to split work into build, test and deployment steps, the overview of ci/cd pipeline stages shows how those parts connect. The quickstart’s own next step is to learn the workflow syntax, which it covers in its Workflows documentation.

Frequently asked questions

Where do I save a workflow file?

Show answer

Save it in a directory called .github/workflows at the root of your repository. GitHub does not discover workflow files saved anywhere else, according to the GitHub Docs quickstart.

Should I use .yml or .yaml?

Show answer

Either works. You can give the workflow file any name you like, but it must use .yml or .yaml as the file name extension.

Do I need to understand the YAML before I run it?

Show answer

No. The quickstart says you can copy and paste the demo at first and learn the syntax of workflow files afterwards.

Why can I not see an Actions tab?

Show answer

Actions may be disabled for the repository. The quickstart points to the repository’s GitHub Actions settings for how to manage that.

Do I have to open a pull request?

Show answer

No. Committing the workflow file to any branch in your repository triggers the push event and runs the workflow, so a pull request is optional for this exercise.