Create my first workflow

[github-learning-lab[bot]]

Oh no... I found an error ⚠️

Error The title of this pull request isn't what I expected!

Solution Verify the name of your pull request is Create my first workflow and keep in mind that this is case-sensitive.

Follow these steps to rename your pull request:

1. Click on Edit next to the pull request's title.
2. The title will turn to a text field, Create my first workflow in the title field.
3. Click Save.

I'll respond when I detect this pull request has been renamed.

[github-learning-lab[bot]]

You have triggered a workflow!

Great job adding the workflow. Adding that file to this branch is enough for GitHub Actions to begin running on your repository. The time this takes will vary based on the complexity of the workflow. At this point we can ignore the workflow because it doesn't do anything yet, but while this runs I'll briefly explain the components of the workflow you just added.

If you want to inspect your running workflow you can do so by heading over to the Actions tab of this repository.

[github-learning-lab[bot]]

Anatomy of GitHub Actions

GitHub Actions is a unique world that lives alongside your repository. It is one made up of many moving parts and having a general understanding of these parts will help us understand the behavior we are going to program into our action.

From 30,000 feet GitHub Actions is made up of the following components, with each component having its own complexities:

Component	Description
Action	Individual tasks that you combine as steps to create a job. Actions are the smallest portable building block of a workflow. To use an action in a workflow, you must include it as a step.
Artifact	Artifacts are the files created when you build and test your code. Artifacts might include binary or package files, test results, screenshots, or log files. Artifacts can be used by the other jobs in the workflow or deployed directly by the workflow.
Event	A specific activity that triggers a workflow run.
Job	A defined task made up of steps. Each job is run in a fresh instance of the virtual environment. Jobs can run at the same time in parallel or be dependent on the status of a previous job and run sequentially.
Runner	Any machine with the GitHub Actions runner application installed. You can use a runner hosted by GitHub or host your own runner. A runner waits for available jobs. Runners run one job at a time reporting the progress, logs, and final result back to GitHub.
Step	A step is a set of tasks performed by a job. Steps can run commands or actions.
Virtual Environment	The virtual environment of a GitHub-hosted runner includes the virtual machine's hardware configuration, operating system, and installed software.
Workflow	A configurable automated process that you can set up in your repository. Workflows are made up of one or more jobs and can be scheduled or activated by an event.

How these pieces fit together

When a repository is configured with a workflow file, like we just created, the following series of events occurs.

1. Your GitHub repository listens for an event
2. That event triggers a workflow run which starts a runner
3. The runner, regardless of the hosting method, is responsible for carrying out the jobs which are defined
4. A job is series of steps, which can be actions or commands
5. When the steps complete a report is generated and can be viewed by anyone with access to the repository

[github-learning-lab[bot]]

Go on... Tell me more!

I'm glad you asked. Let's take a look at the workflow file that we just committed to this repository.

name: CI

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v1
      - name: Run a one-line script
        run: echo Hello, world!
      - name: Run a multi-line script
        run: |
          echo Add other actions to build,
          echo test, and deploy your project.

This file is made up of a series of metadata, as well as behaviors that we wish to happen when the workflow is triggered.

Let's take a second to talk about each of the pieces that we see here:

• name: CI
  • This is the user-defined name for the workflow. This shows up on the Actions tab so we can see which workflows, and their statuses, run on this repository.
  • As you can see, our's is currently named CI
• on: [push]
  • This defines the event that will tigger a workflow on this repository. Currently we are listening for any push event that happens within this repository.
  • Also note that this is an array, which means we can trigger this workflow on more than one event if that is our intended behavior.
• Jobs:
  • This is our first block of instructions. We are defining our first job for this workflow.
  • In this case, the job has been named build
  • We also define the runner for the job as runs-on: ubuntu-latest
  • Finally we define the steps for this job which can either rely on specific actions, or run commands directly. As we can see there are three steps which show a mixed usage of actions and commands.
  • uses: actions/checkout@v1

  • name: Run a one-line script
    run: echo Hello, world!

  • name: Run a multi-line script
    run: |
    echo Add other actions to build,
    echo test, and deploy your project.

---

📖Take a deeper dive into workflow components 📖Read more about configuring workflows

[github-learning-lab[bot]]

Digging into a step

As I mentioned earlier, a step is a task that is either an action or a command. This can be slightly confusing, so I want to take a little time to ensure I explain it to you before moving on.

Actions

Actions are powerful. They are small programs written in either JavaScript or running inside of Docker containers, that add some functionality to your repository.

The things you can do with actions are limited only by your imagination. Want to send a tweet every time you tag a release? What about ordering 🍕just by creating an issue?

Let's not forget the more practical usage of actions, testing the source code of a repository or letting your team know that you are out of office 🏝 when they @ mention your name in issues or pull requests.

You can define an action's inputs, outputs, and environment variables to create reusable building blocks for your workflow.

Actions are portable. You are free to publish your actions to the Actions Marketplace where others can use your creation in their workflows! You can also share actions without publishing them to the marketplace by referencing the repository that contains the actions code!

Actions can even run commands 😏

📖Learn more About Actions

Commands

Commands are useful in the own respect, but are much more limited than actions.

Think about the tasks you might do from the command line of your local machine. Maybe you run npm install to install all of the dependencies for your project before running your unit tests. Maybe you run docker build to execute a Dockerfile.

You can accomplish the same set of tasks inside of a workflow but using run as a step in your job.

Commands are not easily shareable. There is no central location where you can consume the popular commands used in workflows. You do not have access to fine tuning the inputs, outputs or environment variables.

This does not mean commands offer no value in a workflow, but you should use them wisely and if you find yourself reusing the same commands repeatedly, consider turning them into actions.

---

Has Learning Lab stopped responding? Your Actions workflow might be failing. Click here for troubleshooting help.

When a GitHub Actions workflow is running, you should see some checks in progress, like the screenshot below.  If the checks don't appear or if the checks are stuck in progress, there's a few things you can do to try and trigger them: - Refresh the page, it's possible the workflow ran and the page just hasn't been updated with that change - Try making a commit on this branch. Our workflow is triggered with a `push` event, and committing to this branch will result in a new `push` - Edit the workflow file on GitHub and ensure there are no red lines indicating a syntax problem

[github-learning-lab[bot]]

Edit the current workflow

Currently my-workflow.yml is not set up correctly for our use-case. It worked great for allowing us to take a high-level look at workflows, but if we want to use our custom actions there are some changes that we have to make to it.

:keyboard: Activity: Remove boilerplate steps from my-workflow.yml

1. Edit the .github/workflows/my-workflow.yml so that it has the contents below:

   name: Docker Actions
   
   on: [push]
   
   jobs:
    action:
      runs-on: ubuntu-latest
   
      steps:
        - uses: actions/checkout@v1

2. Commit these file changes to this branch

---

I'll respond when you push changes to this pull request.

[github-learning-lab[bot]]

Finishing the workflow

@joelkraehemann you're doing great so far 😄! You've had to do a lot of workflow set up so we can begin writing custom actions. We have just one more thing to add to our my-workflow.yml file before we get to the action side of things.

Recap

Before we make our final workflow change let's do a quick recap about what we've done.

Action	Key Takeaways
Created my-workflow.yml inside of .github/workflows directory	GitHub repositories look in the .github/workflows folder for workflow files.
Used a templated workflow	GitHub provides many templates for workflow files. This is a great spot to look when setting up a new workflow. If you can't find what you are looking for, you can always click the setup a workflow yourself button for a minimal starter template
Workflow environment	You learned, from a high level, how a repository uses a workflow file to run commands or actions based on triggers. You also learned that where these commands or actions execute is something that can be specified
Workflow syntax	You were briefly introduced to the workflow YAML syntax.

If that seems like a lot of things just to get started... well, it is! GitHub Actions is a robust platform designed to automate a wide range of tasks for your repositories.

If you'd like to see more examples of workflows and actions then check out these Learning Lab courses all about GitHub Actions:

• GitHub Actions: Continuous Integration
• GitHub Actions: Continuous Delivery
• GitHub Actions: Publish to GitHub Packages

Add an action reference to the workflow

:keyboard: Activity: Reference our custom action from my-workflow.yml

1. Edit the my-workflow.yml to have the following contents:

   name: Docker Actions
   
   on: [push]
   
   jobs:
    action:
      runs-on: ubuntu-latest
   
      steps:
        - uses: actions/checkout@v1
   
        - name: hello-action
          uses: ./.github/actions/hello-world

2. Commit these file changes to this branch

---

I'll respond when you push changes to this pull request.