Your first Docker based action

[github-learning-lab]

Hello world with Docker 🐳

@JonClayton we are going to start with the typical "Hello World" example and build something more complex after, but first let's decide if a Docker based action is the right action for us!

Why use Docker when writing GitHub Actions?

That's a super great question to ask. Before we talk about the components that make up Docker based actions, we should understand the good and the bad of Docker based actions.

Advantages	Disadvantages
Docker actions package the source code that will be executed right alongside any dependencies that source code has.	Slower execution time because the image containing your source code and dependencies gets built with every workflow run.
Docker containers package the environment with the GitHub Actions code. This creates a more consistent and reliable unit of work because the consumer of the action does not need to worry about the tools or dependencies.	Docker container actions can only execute in the GitHub-hosted Linux environment.
Ideal for running in environments with very specific configurations and tools.	Debugging can be difficult with containers.
Actions can be written in any language you choose.	More files to maintain when changes to the action occur.

Got it, what now?

Let's begin by exploring the components of a Docker based action and discuss how they fit together!

[github-learning-lab]

Anatomy of an action

Earlier you learned how the different pieces of GitHub Actions work together. Now you will learn about the components that make up an individual action.

Remember, an action is the unit of work that a workflow file executes when it reaches that task. They are called by referencing them as the value to the uses: key in a workflow step.

What makes up an action?

Docker actions consist of three key components:

Component	Description
Action source code files	These files contain the logic of your action. This includes any dependencies or custom modules that your main logic may need.
Action metadata file	This file contains information that the actions source code can use. An example of this is allowing a developer to specify an API key as an input variable for your action to consume. This file MUST be named action.yml
Dockerfile	This file defines the environment and dependencies for the action. It is best practice that this file be named Dockerfile

Let's take a look at how those components fit together.

• The workflow, usually workflow.yml, is the user facing component. It must be housed in .github/workflows/ and doesn't need to be called workflow.yml, but its essence is a workflow. This is what we interact with directly when we want to supply input, or consume the output of a given action. You can think of workflow.yml as a user-interface for the action.yml file.
• The action's metadata, called action.yml, is the interface between the user and the source code of the action. It is housed in a directory just for the action. This file may contain default values for inputs and outputs that the source code relies on. Those values can be overwritten by the workflow.yml file, but their default values live here and allow the action to execute properly if no values are supplied. This file also defines a high-level environment for the source code, such as whether to use Docker or Node.js and the execution entry point.
• The action's source code files define the logic of an action. It is housed in a directory just for the action. The user doesn't interact with these files directly. There could be as little as one source code file, but there is no hard rule on how modular an action can be!
• Dockerfile is only needed when creating Docker based actions and it is responsible for packaging up the environment as well as the source code for the given action. It is housed in a directory just for the action. This file is read and a Docker image is created from it. Once the image is created a container is created from the image and the action is executed.

Although the workflow file is used to allow us to set the inputs and outputs using the with: keyword it is not a required component of an individual action.

---

The failing workflow

You may be following along on the Actions tab of this repository. If you are, you'll notice that the workflow we set up previously is failing. That is the currently expected behavior: we referenced an action in the hello-world directory, which doesn't yet exist. We will be fixing that as we move forward with the lesson.

[github-learning-lab]

Action metadata

Since every GitHub Action that we write needs to be accompanied by a metadata file this is the file we will create first.

This file has a few rules to it, lets outline those now:

• Filename must be action.yml
• Required for both Docker container and JavaScript actions
• Written in YAML syntax

This file defines the following information about your action:

Parameter	Description	Required
Name	The name of your action. Helps visually identify the actions in a job.	✅
Description	A summary of what your action does.	✅
Inputs	Input parameters allow you to specify data that the action expects to use during runtime. These parameters become environment variables in the runner.	❌
Outputs	Specifies the data that subsequent actions can use later in the workflow after the action that defines these outputs has run.	❌
Runs	The command to run when the action executes.	✅
Branding	You can use a color and Feather icon to create a badge to personalize and distinguish your action in GitHub Marketplace.	❌

---

📖Read more about Action metadata

[github-learning-lab]

Create the action metadata

Now that we know what action metadata is, let's create the metadata for our hello-world action.

⌨️ Activity: Create an action.yml file and add necessary metadata

💡All of the following steps take place inside of the .github/actions/hello-world directory.

We will start with using the parameters that are required and later implement some optional parameters as our action knowledge grows.

1. Create and add the following contents to the .github/actions/hello-world/action.yml file:
   You can use this link to easily create this file.

   name: "my hello action"
   
   description: "say hello with GitHub Actions"
   
   runs:
     using: "docker"
     image: "Dockerfile"

2. Commit the changes to a new branch named hello-world

3. Create a pull request titled Add a Hello World action.

4. Supply the pull request body content and click Create pull request.

---

I'll respond when you create a new pull request.