cmdev-zk / write-docker-actions

https://lab.github.com/githubtraining/github-actions:-write-docker-container-actions
MIT License
0 stars 0 forks source link

Your first Docker based action #3

Closed github-learning-lab[bot] closed 3 years ago

github-learning-lab[bot] commented 3 years ago

Hello world with Docker 🐳

@cmdev-zk 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[bot] commented 3 years ago

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.

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[bot] commented 3 years ago

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:

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. :white_check_mark:
Description A summary of what your action does. :white_check_mark:
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. :white_check_mark:
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[bot] commented 3 years ago

Create the action metadata

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

:keyboard: 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.

github-learning-lab[bot] commented 3 years ago

Great job πŸ‘

I have created a new pull request where we will continue this lesson. Click the link to meet me over there.

In the meantime I have closed this issue since we wont be needing it anymore πŸ˜„