Getting started with GitHub Actions

This article was written by automation created by GitHub Actions.
Not really.
But it could have been.

No matter your role in the software development lifecycle or your skill level: if your repository lives on GitHub, GitHub Actions is for you, and it can help automate your workflows!

  • Are you the maintainer of an Open Source project? Actions can help you automate the maintenance of issues raised by the community, for example.
  • Do you manage your organizationā€™s billing? You can use a simple and free action to check your organizationā€™s Actions billing info.
  • Is your project global, and localization/translation is important? Muito bom! This action created by the community can help you translate issues into different languages!
  • Are you just starting your career in software development? Welcome! GitHub Actions will be a valuable tool to use throughout your journey!
  • Are you developing the CI/CD pipeline between your project and other integrations? There are SO MANY actions for you!

The best part about GitHub Actions is that getting started is as easy as 1, 2, 3.

1. One file to rule them all: YAML

Start automating your workflows by writing a YAML file. A YAML file is, in a nutshell, a text file that contains key:value pairs. You can see an example of what its syntax looks like in the next section.
YAML files are also known as workflow files, and they must:

  • Live in the .github/workflows directory in your GitHub repository
  • Have either the .yml or .yaml extension

2. Two ways to get started

Now that you know what a YAML file is, itā€™s time to get started! You can:

  1. Use actions created by the community: they are free, available on the GitHub Marketplace, and can be easily added to your workflow file. Little to no programming experience is needed to start using this option.
  2. Write your own action: create customized workflows that fit your needs specifically, by writing the code and the workflow file.

Before you start building your workflow, make sure you have:

  • Identified what event will trigger your workflow: in this example, I am using the issues and issue_comment event triggers.

     	name: issue-translator
        on:  # when the events below happen, trigger the workflow
            types: [opened] # when a new issue is opened
            types: [created]  # when a new issue comment is created 
            runs-on: ubuntu-latest    # this job will run on a runner installed on the latest version of Ubuntu
            steps:   # what to do once the event triggers the workflow
              - uses: usthe/issues-translate-action@v2.6   # use this action at version 2.6
  • Selected your runner type appropriately: the runner is the application that runs a job from a GitHub Actions workflow. The example above uses a GitHub-hosted runner installed on the latest version of Ubuntu. Follow the steps on our documentation to use GitHub-hosted runners, or to host your own runners.

  • If you are using an action from the GitHub Marketplace: ensure you have the action and version noted. In this example, I am using the usthe/issues-translate-action@v2.6 action.

Here is the TL;DR for the example and steps above: when an issue or issue comment is created, a job will be triggered and run on a GitHub-hosted runner. The usthe/issues-translate-action@v2.6 action will be called, and the text within that issue or issue comment will be translated from its original language to English.

To see these steps in action (pun intended), visit this repository.

Simple, right? If you are ready to learn more, including migrating from other platforms into GitHub Actions, securing your actions, troubleshooting and monitoring your workflow runs, hosting you own runner and more, make sure to purchase a copy of Automating Workflows with GitHub Actions, written by yours truly :smiley:

Now that you understand the basics of GitHub Actions, you can automate workflows as simple or complex as you wish! And of course, GitHub and the community are here to collaborate, provide inspiration and help answer questions. Read the next section to see how you can keep the conversation going!

3. Getting help and contributing to the community

We canā€™t wait to see what you will build and automate with GitHub Actions! Stay engaged with the community and take advantage of these resources available to you: