GitHub for Beginners: Getting started with GitHub Actions

Welcome back to our ongoing GitHub for Beginners series, now in its third season! Our previous episode was the first of the season, and we talked about getting started with GitHub Issues and Projects. This time we’re jumping into another very popular GitHub feature called GitHub Actions. By the end of this post, you’ll know how to use GitHub Actions and will have created your first automated workflow.

As always, if you prefer to watch the video or want to reference it, we have all of our GitHub for Beginners episodes available on YouTube. (And you can watch the full video of this tutorial above!)

What are GitHub Actions?

GitHub Actions is a Continuous Integration/Continuous Delivery (CI/CD) and automation platform built right into GitHub. You’ll often hear people call these “action workflows” or just “workflows.” It allows you to automate repetitive tasks and deployment processes using YAML files stored in your repository. You might use GitHub Actions for tasks like running vulnerability scans, tests, creating releases, or even reminding your team about important updates.

Action workflows are triggered by GitHub events like pushes, pull requests, or schedules, and they run in a virtual environment.

How workflows work

Before jumping right into the details about how workflows do their job, we need to define some essential terms.

• Event: A specific activity that triggers a workflow (e.g., pushing code, opening a pull request, creating an issue, etc.)
• Hosted runners: A virtual machine that executes jobs in a workflow. GitHub provides hosted runners, or you can set up your own self-hosted runners.
• Jobs: A set of steps executed within the same runner. Each step is either a shell command or a prebuilt action from the GitHub Marketplace.

Workflows are triggered by events in a repository. This can be something like a pull request, merging a branch, or even opening an issue. When you create the workflow, you determine what the triggering event is.

When that event fires and triggers the workflow, GitHub spins up one or more jobs that execute on a runner. GitHub then follows the steps you programmed into the workflow until it reaches the end. And it does this all on its own, without any interaction necessary on your behalf. This is essentially how the GitHub Action workflow works.

Want more practice creating your own workflows and getting more familiar with GitHub Actions? Try out the Hello GitHub Actions skill exercise in our skills repository.

Looking at a repository’s actions

Navigate to our sample repository, fork it, then select the Actions tab at the top. This page lists all of the current workflows for the repository. Select the green New workflow button in the left-hand column. This brings you to a new page, which presents several suggested workflows for this repository.

Select the Configure button for one of the suggested actions. For right now, it doesn’t matter which one you select. This pulls up an editor with a template written in YAML with three main sections you need to know when building an action workflow:

• Name: Describes what your workflow does.
• On: Defines what triggers the workflow.
• Jobs: Where the actual work associated with this workflow happens.

Building a workflow

One of the best ways to learn is by doing, so let’s go ahead and create a simple workflow that will automatically label new issues created in our repository. First, head back to the main page for the sample repository and clone it to your machine. Then, navigate to the action-start branch.

GitHub Actions uses YAML syntax to define workflows. Each workflow is stored in a .yml file in a special .github\workflows directory in your repository. Go ahead and navigate to that directory.

When creating workflow files, you should use descriptive names that tell you what they do at a glance (e.g., build-and-test.yml, security-scanner.yml). Since we know that we want to have this workflow label new issues, create a new file in this directory and call it label-new-issue.yml. Add the following to the top of the file:

Name: Label New Issues 

Now we need to decide what will trigger this workflow. GitHub has tons of trigger options, all of which are listed in our trigger workflows reference documentation, so you can choose based on what you’re building. In our case, we specifically want to have this workflow trigger whenever someone opens an issue. We do this by adding the following code to the bottom of the YAML file.

on: 

  issues: 

    types: [opened]

Now we get to the good stuff: the jobs section, where the actual work happens. The first thing we’ll do is give our job a title and choose what type of machine runs it. GitHub provides hosted runners with different versions of Ubuntu, Windows, and macOS.

Let’s call this job label-issues and run it on ubuntu-latest. This tells GitHub to grab a machine from their pool of Ubuntu runners using the latest version available.

We also need to add permissions so the action can read the content of the repository and add the label. When we use the permissions keyword inside of a job, all actions and run commands within that job gain the access rights specified.

jobs: 

  label-issues:  

    runs-on: ubuntu-latest 

    permissions: 

      issues: write 

      contents: read

Okay, now we need to add the actual steps. This is where we define what happens in the job.

    steps: 

      - name: Checkout repository 

        uses: actions/checkout@v6 

      - name: Add triage label 

        env: 

            GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} 

            ISSUE_NUMBER: ${{ github.event.issue.number }} 

            LABEL: "triage" 

        run: gh issue edit "$ISSUE_NUMBER" --add-label "$LABEL" 

You’ll see two main keywords here: uses and run.

When you see uses, that’s pulling in a prebuilt action from the GitHub Marketplace. These are open-source reusable actions that handle common tasks, so you don’t have to write everything from scratch. Some examples of these type of actions include checking out your code or setting up NodeJS.

When you see run, that’s executing a command or script. This same keyword is used if it’s just a single line of code or a script that spans multiple lines.

The env section is where we define our environment variables. Since we are using the GitHub CLI in our run section, we need to provide an access token for the action to be able to access the repository. We do this by setting the GH_TOKEN environment variable. GitHub automatically provides a temporary access token when it creates this job and provides it in the GITHUB_TOKEN variable.

We also need to have variables to indicate which issue we want to update, as well as which label we want to add. In order for this to work, that label needs to already exist in the repository.

Congratulations! You’ve now successfully completed authoring your first workflow!

Testing your workflow

Now that we have the workflow, it’s time to test it. In order to do so, we first need to push these changes up to the repository and merge them into the main branch. So go ahead and do that now. Once it’s in the main branch, we can see it in action. If you have any questions about how to push your code, you can check out our earlier GitHub for Beginners episode about adding code to your repository.

Once your workflow is uploaded, let’s see it work. Navigate to the repository in your browser, and select the Issues tab. In the top-right corner, select the green New issue button. Provide a title and description indicating that you’re testing the workflow, and then click Create at the bottom of the window.

GitHub will create the issue and automatically bring you to the page showing the issue’s history. Assuming everything is working correctly, you’ll see the triage label added within seconds of when you created the issue.

Nice work! You can now see how convenient it can be to have some actions automatically handle tasks based on specific triggers.

Reviewing current workflows

Select the Actions tab at the top of the window. You’ll see all of the actions listed in a column on the left-hand side of the window. Select Label New Issues to filter the view to show just the times this workflow has run.

Select the top workflow, which should be for the test issue you created in the previous step. This brings you to a detail page where you can see more information about this specific instance of the workflow. Select label-issues in the main window.

Now you can see all of the steps taken in order to complete the workflow. This can be very useful for debugging purposes if one of your workflows is not working as expected. If you want to rerun this workflow, you can do so by clicking the Re-run all jobs button in the top-right.

If there’s ever a situation where you need to pause a workflow, you can do that from the Actions tab. Navigate back to that tab, and once again select Label New Issues in the left column. Click the three dots (…) in the window on the right, next to the search box. One of the options is Disable workflow. If you select this, it will stop the workflow from running, but it will still exist in the repository, so you can enable it later.

The Actions tab is where you’ll go to see and manage all of your workflows. You can check deployments, runners, metrics, performance, and caches all from this view. You can also view and edit your workflow files directly from this tab.

What’s next?

GitHub Actions can do a lot more than just label your issues. You can create actions to publish packages, greet new contributors, build and test your code, and even run security checks.

Keep learning about GitHub Actions by checking out our GitHub Actions documentations and start experimenting with creating your own workflows.

Happy coding!

The post GitHub for Beginners: Getting started with GitHub Actions appeared first on The GitHub Blog.