But before we start, just a quick reminder that this is my second post in the series about GitHub Actions workflow. And if you would like to see the introduction, then check out my previous article and learn how to create your first workflow.

Video Tutorial

If you prefer video content, then check out my video:

If you find this content useful, please leave a subscription  😉

Trigger Workflow On workflow_run

Let’s assume that we would like to add a new workflow to our GitHub Actions, workflow B, which will trigger whenever workflow A completes successfully. We go to the events documentation and figure out that the workflow_run will be the right choice.

So, for the following workflow A:

name: Workflow A

on:
  push:
    branches: [ "main" ]

jobs:
  some_job:  
    runs-on: ubuntu-latest
    steps:
      - name: Some Step 
        run: echo "Hello!"

We pretty quickly came up with something, like this:

name: Workflow B

on:
  workflow_run:
    workflows: ["Workflow A"]
    types:
      - completed

jobs:  
  run_on_workflow_a_success:
    if: ${{ github.event.workflow_run.conclusion == 'success' }}
    runs-on: ubuntu-latest
    steps:
      - name: Run on workflow A success
        run: echo "Workflow A completes successfully"

Whenever the workflow A completes successfully, we simply print out a message to the output.

Problem With Passing Data

But life is not usually that simple and we pretty quickly realize that we need to find a way to pass the data between our GitHub workflows.

If we learned from my previous article or spent some time with the official documentation, we finally land on the contexts page and try to find the necessary information.

If are lucky enough and the data we need are present, we can simply access them with one line of code.

Just like we did previously:

github.event.workflow_run.conclusion

As we can see, the above line accesses information about conclusion from the github context.

But what if we would like to access some custom data produced by the workflow A within the workflow B?

Well- that’s the point where the story begins 🙂

Pass Data Between GitHub Workflows With Artifacts

Unfortunately, at the moment when I am writing this article, there’s no such thing as a custom context or something similar where we could put the data and access them inside another (dependent) workflow.

Fortunately, we can bypass this limitation by producing artifacts.

Let’s update our workflow A first:

name: Workflow A

on:
  push:
    branches: [ "main" ]

jobs:
  some_job:  
    runs-on: ubuntu-latest
    steps:
      - name: Some Step 
        run: echo "Hello!"

  job_producing_data:  
    runs-on: ubuntu-latest
    steps:
      - name: Some Step 
        run: |
            printf '{ 
              "prop_1": "Some value",  
              "prop_2": true
            }' >> context.json
      - uses: actions/upload-artifact@v3
        with:
          name: context.json
          path: ./

With this solution, we produce a JSON file called context.json, which then we publish as an artifact.

In simple words, GitHub artifacts are files (or collections of files), that we can produce during the workflow run and access later- from other workflows, through the API, or simply in the actions tab:

Following, let’s update the workflow B to consume this file and access its data:

name: Workflow B

on:
  workflow_run:
    workflows: ["Workflow A"]
    types:
      - completed

jobs:  
  run_on_workflow_a_success:
    if: ${{ github.event.workflow_run.conclusion == 'success' }}
    runs-on: ubuntu-latest
    steps:
      - name: Run on workflow A success
        run: echo "Workflow A completes successfully"

  download_context_artifact:
    runs-on: ubuntu-latest
    steps:
      - name: 'Download artifact'
        uses: actions/github-script@v6
        with:
          script: |
            let allArtifacts = await github.rest.actions.listWorkflowRunArtifacts({
               owner: context.repo.owner,
               repo: context.repo.repo,
               run_id: context.payload.workflow_run.id,
            });
            
            let matchArtifact = allArtifacts.data.artifacts.filter((artifact) => {
              return artifact.name == "context.json"
            })[0];
            
            let download = await github.rest.actions.downloadArtifact({
               owner: context.repo.owner,
               repo: context.repo.repo,
               artifact_id: matchArtifact.id,
               archive_format: 'zip',
            });
            
            let fs = require('fs');
            fs.writeFileSync(`${process.env.GITHUB_WORKSPACE}/context.zip`, Buffer.from(download.data));
            
      - name: 'Unzip artifact'
        run: unzip context.zip

      - name: 'Return Parsed JSON'
        uses: actions/github-script@v6
        id: return-parsed-json
        with:
          script: |
            let fs = require('fs');
            let data = fs.readFileSync('./context.json');
            return JSON.parse(data);

    outputs:
      property_one: ${{fromJSON(steps.return-parsed-json.outputs.result).prop_1}}
      property_two: ${{fromJSON(steps.return-parsed-json.outputs.result).prop_2}}

  log_context_values:
    needs:
      - download_context_artifact
    runs-on: ubuntu-latest
    steps:
      - name: 'Log Context Values'
        run: |
          echo "${{ needs.download_context_artifact.outputs.property_one }}"
          echo "${{ needs.download_context_artifact.outputs.property_two }}"

As we can see, we added two new jobs: download_context_artifact and log_context_values.

The first one is responsible for downloading the artifact (unfortunately GitHub API supports only zip files at the moment). We list all articles from the triggering flow (workflow A), match the one named context.json and download it.

Then, we unzip the file and parse its JSON content.

As the last thing in the first job, we produce two outputs. The output is nothing else than a map accessible in all downstream jobs dependent on this job. And to put it simply, in all jobs which point to this one using needs.

The interesting thing here is that in order to access the parsed json- return JSON.parse(data)– we need to use the <step id>.outputs.result.

The second job, log_context_values, simply prints out our values.

Summary

And that’s all for this tutorial, in which we learned how to pass data between workflows in GitHub actions.

I hope you enjoyed this one and if you would like to share your feedback with me or ask about anything, then let me know in the comments section.

The post How To Pass Data Between Workflows in GitHub Actions? appeared first on Codersee blog- Kotlin on the backend.

At the end of this tutorial, you will know precisely how to:

• navigate in GitHub actions and create new workflows,
• trigger workflows manually,
• create a job that runs only when another job succeeds,
• use GitHub context and access its data.

Video Tutorial

If you prefer video content, then check out my video:

If you find this content useful, please leave a subscription  😉

What Is GitHub Actions?

GitHub Actions is nothing else than a CI/CD (continuous integration/continuous delivery) platform.

To put it simply, it is a platform, that allows us to automate builds, testing, deployments, and many other things related to the process in your company, or the project.

In practice, we define so-called workflows, which are triggered whenever some event happens in our repository. An event can be a merge to the main, a push to the remote branch, a deployment update, and plenty more.

Each workflow consists of jobs running inside their own machine runner and each job can have multiple steps responsible for performing an actual action, like code check, running a test, or creating a deployment.

Lastly, each workflow is nothing else than a YAML file placed within the .github/workflows directory.

Create First Workflow

With all of that said, let’s navigate to our GitHub repository and select the actions tab. Alternatively, you can do that with the following link: https://github.com/codersee-blog/{YOUR_REPO_NAME}/actions/new.

Nextly, let’s click the configure button:

As a result, we should see the editor with the following code:

# This is a basic workflow to help you get started with Actions

name: CI

# Controls when the workflow will run
on:
  # Triggers the workflow on push or pull request events but only for the "main" branch
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This workflow contains a single job called "build"
  build:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest

    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
      - uses: actions/checkout@v3

      # Runs a single command using the runners shell
      - name: Run a one-line script
        run: echo Hello, world!

      # Runs a set of commands using the runners shell
      - name: Run a multi-line script
        run: |
          echo Add other actions to build,
          echo test, and deploy your project.

So, let’s clean it up a bit to avoid distraction:

name: CI

on:
  push:
    branches: [ "main" ]
  
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - 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.

To sum up, we’ve defined a new GitHub Actions workflow, named CI, which will be triggered whenever we push a new commit to the main branch.

Our workflow consists of one job, build, which will be run on the Ubuntu runner. This job will invoke has two steps, which will be run one after another:

• firstly, it will print out a one-line script,
• lastly, it will invoke the multiline script.

Quite easy, isn’t it?

So with all of that done, let’s change the name of the file to ci.yml and let’s commit our changes to the main branch:

How To View Workflow Run?

With all of that done, let’s see how we can see the result of our triggered workflow.

To do so, let’s navigate to the following URL: https://github.com/codersee-blog/{your-repo-name}/actions/workflows/ci.yml.

On this page, we should see that our workflow run has completed successfully:

As the next step, let’s click on the build job and let’s see the output:

Excellent!

Both our scripts run successfully and we can see the expected output.

How To Trigger Flow Manually?

At this point, you might be wondering if (and if yes, then how) we can manually trigger the flow.

Well, unfortunately, to do so, we must edit our YAML file a little:

name: CI

on:
  push:
    branches: [ "main" ]
  workflow_dispatch:  
  
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - 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.

As we can see, the only thing we need to add is the workflow_dispatch.

This event, allows us to trigger our workflow using the GitHub API, GitHub CLI, or GitHub browser interface:

How To Disable The Workflow?

But can we disable the workflow without deleting the file?

Yes, we can.

We can do that simply by using the Disable workflow button from the workflow runs page:

Contexts And Debugging

Wonderful. At this point, we already know the basics of workflows and navigation in GitHub Actions.

As the next step, let’s learn a bit more about contexts.

Contexts allow us to access information about the workflow runs, variables, runner environments, jobs, and steps. If you are looking for commit sha, PR author, branch name, or maybe GitHub access token, then that’s the place you should check out.

For the full list of contexts with descriptions please take a look at the official documentation.

But from my end, I wanted to show you a useful tip if you would like to debug anything:

name: CI

on:
  push:
    branches: [ "main" ]
  workflow_dispatch:  
  
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - 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.
  
      - name: Who initialized the flow? 
        run: echo "${{ github.actor }} initialized the flow."

      - name: Debug GitHub context
        run: |
            echo " ${{ toJSON(github) }}"

As we can see, the third step – Who initialized the flow?- prints out the “actor” (or simply the account) that initialized the flow.

The fourth step- Debug GitHub context- prints out github context to the output.

The toJson function returns a pretty-print JSON representation of our value.

As a result, we should see the following:

Whatsoever, when debugging we don’t need to worry about exposing our secrets.

GitHub hides them by default.

Run Job After Another Job Finishes Successfully

Excellent! At this point, we learned quite a lot about the GitHub Actions workflows.

We know how to declare them, how to debug contexts, and how to navigate inside the GitHub world.

As the last thing for our first meeting, let’s learn how we can make one job dependent on the other.

To do so, let’s edit our YAML file once again:

name: CI

on:
  push:
    branches: [ "main" ]
  workflow_dispatch:  
  
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - 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.
  
  second_job:        
    needs: build
    runs-on: ubuntu-latest
    
    steps:
      - name: I run only when build succeeds
        run: echo Hi!

As we can see, the only thing we need here is needs: build.

To be more specific, the needs instruction allows us to specify jobs that must be completed successfully before our job starts.

Of course, we can define multiple jobs using the array syntax: needs: [job1, job2].

Summary

And that’s all for this quick tutorial on how to create GitHub Actions workflows.

If you are interested in learning more about this topic, then I highly encourage you to check out their documentation. I’m pretty sure you will find there anything you need.

But if that’s not the case, then let me know in the comments section or by using the contact form 🙂

The post How To Create a GitHub Actions Workflow appeared first on Codersee blog- Kotlin on the backend.