richardloof / writing-javascript-actions

Welcome to your course 🎉

Getting started

In this repository we will be diving into the world of writing GitHub Actions! I will guide you through the process of writing a custom JavaScript based GitHub Actions.

You may be asking yourself, "is JavaScript the only way to create custom GitHub Actions?"

Currently, there are two supported ways to create your own GitHub Actions:

• Docker container actions
• JavaScript actions

As you can see we aren't necessarily limited to JavaScript even though it is the focal point for this course.

---

Creating vs consuming actions

Although we are going to focus on creating and consuming a custom action, in this course we will also be consuming some actions that have been made public to us. Because your workflows will most likely do the same, I found it important to show you where to look for actions that already exist.

After all, for each time we need to reinvent the wheel for our specific use-case there are a handful of times when we are better off using a wheel that's already made!

• The GitHub Actions Marketplace is the primary place to find open-source actions that the community has written and released. Your action, should you choose to release it, could also reside here one day, ready to be consumed by the world!
• The GitHub Actions Repository is where you can find actions that are written by GitHub. We will leverage an action named [checkout](https://github.com/actions/checkout) from this repository as we go through this course. I'll explain more about what it does when we use it!
• Your repositories may also contain private actions and they will most likely be located in the .github/actions directory in the root of your repository. This is the convention we will be using as we learn how to create our own action.

---

Using actions and Learning Lab

In other courses, you may have noticed that some behaviors take me longer to respond to than others. In this course, many of the behaviors we'll see demonstrated will be related to our GitHub Actions workflow. Those workflows sometimes take longer to complete, up to several minutes. Don't be concerned if I take a few minutes to respond, or if I respond too quickly. Sometimes, I'll let you know what the workflow will say before it finishes! Please wait for the workflows to finish before moving on to your next step.

If you aren't already familiar, it may be a good idea to go through the Introduction to GitHub Learning Lab.

---

Please navigate to the open issue in this repository to get started!

writing-javascript-actions's Issues

Start here!

Configuring a workflow

Actions are enabled on your repository by default, but we still have to tell our repository to use them. We do this by creating a workflow file in our repository.

A workflow file can be thought of as the recipe for automating a task. They house the start to finish instructions, in the form of jobs and steps, for what should happen based on specific triggers.

Your repository can contain multiple workflow files that carry out a wide variety of tasks. It is important to consider this when deciding on a name for your workflow. The name you choose should reflect the tasks being performed.

In our case, we will use this one workflow file for many things, which leads us to break this convention for teaching purposes.

📖Read more about workflows

⌨️ Activity: Create a pull request to prepare the repository for actions

1. Create a new workflow file titled my-workflow.yml inside of the folders .github/workflows/ by using the instructions below, or this quicklink.
   • Go to the Actions tab.
   • Choose the Set up a workflow yourself option, located on the top right hand corner of the screen.
   • Change the name of the file to .github/workflows/my-workflow.yml.
2. Commit the workflow to a new branch, you can name it add-initial-workflow.
3. Create a pull request titled Create a workflow.
4. Supply the pull request body content and click Create pull request.

It is important to place meaningful content into the body of the pull requests you create throughout this course. This repository will stay with you long after you complete the course. It is advisable that you use the body of the pull requests you create as a way to take long lived notes about thing you want to remember.

Suggested body content

Workflow files are the recipe for task automation. This is where actions are placed if I want to use them for a task.

I'll respond in the new pull request when I detect it has been created.

---

If at any point you're expecting a response and don't see one, refresh the page.

Your first JavaScript action

On to your development environment

@richardloof our JavaScript actions are going to leverage the GitHub ToolKit for developing GitHub Actions.

This is an external library that we will install using npm which means that you will need Node.js installed.

I find writing actions to be easier from a local environment vs trying to do everything right here in the repository. Doing these steps locally allows you to use the editor of your choice so that you have all the extensions and snippets you are used to when writing code.

If you do not have a preferred environment then I suggest following along with me exactly as you see on the screen, which means you'll need to install Visual Studio Code.

Don't forget to set up your workstation 😉

Most of your work going forward will take place away from your Learning Lab repository, so before continuing with the course ensure you have the following installed on your local machine.

1. Node.js
2. Visual Studio Code or your editor of choice
3. Git

⌨️ Activity: Initialize a new JavaScript project

Once you have the necessary tools installed locally, follow these steps to begin creating your first action.

1. Open the Terminal (Mac and Linux) or Command Prompt (Windows) on your local machine

2. Clone your Learning Lab repo to your local machine:

   git clone https://github.com/richardloof/writing-javascript-actions.git

3. Navigate to the folder you just cloned:

   cd writing-javascript-actions

4. Create a new branch named hello-world. This is the branch we will use to write our first action. Please do not capitalize letters unless I do, I run case-sensitive checks to make sure I can help you along the way!

   git checkout -b hello-world

5. Create a new folder for our actions files:

   mkdir -p .github/actions/hello-world

6. Navigate to the hello-world folder you just created:

   cd .github/actions/hello-world

7. Initialize a new project:

   npm init -y

8. Install the core dependency from the GitHub ToolKit:

   npm install --save @actions/core

9. Commit those newly added files,we will remove the need to upload node_modules in a later step:

   git add .
   git commit -m 'add project dependencies'

10. Push your changes to your repository:

    git push -u origin hello-world

---

I will respond once you have finished.