Create a workflow

[cyrfer]

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

[github-learning-lab[bot]]

While we wait!

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

---

Actions workflow not running? Click here

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]]

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 a workflow file similar to what 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, ours 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

if you don't see a response from me below this, try making a new commit to this branch. Your workflow may have finished before I was ready to listen

[github-learning-lab[bot]]

Our workflow has finished 🎉

Our workflow has finished so let's take a look at the results now that we have learned a little bit about workflows while we waited.

In the left-hand panel of this screen you can see that this workflow, named CI was triggered on: push and ran the job titled build.

The right-hand panel shows real-time logging of the steps executed by the build job. There are currently 5 steps defined for this job:

• Set up job
• Run actions/checkout@v1
• Run a one-line script
• Run a multi-line script
• Complete job

🤔This is interesting, in the my-workflow.yml file we defined 3 steps, not 5, so what happened?

GitHub Actions will always add the Set up job and Complete job steps to each job in a workflow. These steps are what configure the virtual environment before running your steps and shut it down properly before moving onto the next job in your workflow.

If you recall, we had 1 step that used an action and 2 steps that ran commands, can you identify which step used the action?

Answer to above question

If you said `actions/checkout@v1` you'd be correct 😄!

---

If you want to see this for yourself head over to your [Actions tab]() and examine the workflow named CI

[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: Modify my-workflow.yml to remove boilerplate steps

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

   name: JS 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 in this pull request once you make these changes.

[github-learning-lab[bot]]

Finishing the workflow

@cyrfer 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

:keyboard: Activity: Modify my-workflow.yml to run our custom action

1. Edit the my-workflow.yml to contain the following:

   name: JS 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 I notice you've made these changes