How to reference another yml file from the main github action yaml file?

Question

I'm defining a github action script that's referencing to another yaml file, hoping to put the configuration into a more organised way.

Here is my job file, named as deploy.yml in the path of ./.github/workflows/, where the first . is the root folder of my project.

....
jobs:
  UnitTest:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ./.github/workflows/unittest.yml

In the same ./.github/workflows/ folder, I created another file called unittest.yml as below:

name: "UnitTest"
description: "Perform Unit Test"
runs:
  # using: "composite"
  - name: Dependency
    run: |
      echo "Dependency setup commands go here"

  - name: UnitTest
    run: make test.unit

However, when I tried to test the script locally using act with command act --secret-file .secrets --container-architecture linux/amd64, I received the following error:

[Deploy/UnitTest]   ✅  Success - Main actions/checkout@v3
[Deploy/UnitTest] ⭐ Run Main ./.github/workflows/unittest.yml
[Deploy/UnitTest]   ❌  Failure - Main ./.github/workflows/unittest.yml
[Deploy/UnitTest] file does not exist
[Deploy/UnitTest]   Job failed

I have tried to put just the file name unittest.yml or ./unittest.yml or myrepo_name/.github/workflows/unittest.yml or put the file into a subfolder like step 2 of this document illustrated, but all no luck.

Based on examples of runs for composition actions, I would imagine this should work.

Would anyone please advise?

P.S. You might have noticed the commented line of using: "composite" in the unittest.yml. If I uncomment the line, I'll receive error:

Error: yaml: line 3: did not find expected key

Answer 1

Composite actions are not referenced by YAML file, but a folder. In that folder, you are expected to have an action.yml describing the action.

This is why you're getting the error with using: composite, you're defining a workflow (because it's in ./github/workflows), but you are using action syntax.

I would advise this folder structure:

.github/
 |-- workflows/
    | -- deploy.yml
unittest-action/
 |-- action.yml

With this structure, you should be able to reference the action with

- uses: actions/checkout@v3
- uses: ./unittest-action

Please see the docs for more information.

---

Depending on your use-case and setup, you might also want to consider reusable workflows.

You can define a reusable workflow in your .github/workflows directory like so:

# unittest.yml
on: workflow_call

jobs:
  deploy:
    # ...

and then call it like so:

jobs:
  UnitTest:
    uses: ./.github/workflows/unittest.yml

Note how the reusable workflow is an entire job. This means, you can't do the checkout from the outside and then just run the unit test in the reusable job. The reusable job (unittest.yml) needs to do the checkout first.

---

Which one to pick?

Here's a blog post summarising some of the differences between composite actions and reusable workflows, like:

• reusable workflows can contain several jobs, composite actions only contain steps
• reusable workflows have better support for using secrets
• composite actions can be nested, but as of Jul '22, reusable workflows can't call other reusable workflows