How do you write automated tests for reusable workflows (specifically using relative vs fully qualified action identifiers)?

[rdgoite]

Why are you starting this discussion?

Question

What GitHub Actions topic or product is this about?

General

Discussion Details

I'm currently writing a set of actions for reuse, and I'm struggling a bit with writing the automated tests that sit alongside the actions themselves. At the moment, I have defined the tests as workflows themselves that sit inside .github/workflows. They run as a suite every time changes are pushed. I think this works pretty well, however, I've run into limitations that are making the experience very difficult.

Firstly, when I'm referring to reusable actions in their corresponding test workflows, I use relative paths. I do this because I want the tests to run against the current version of their target action every time. However, this is not how they are going to be consumed ultimately; they will be referred to using a fully qualified identifier (e.g. my-org/my-repo/path/to/action). This would have been easy if the uses field can be specified variably, but it has no access to any context. There's an older discussion about this (#25246).

This is particularly a problem when the reusable actions refer to other reusable actions in the same repository. The relative paths in actions are relative to the repository they're running in, not relative to the repository that hosts them. I've worked around this by adding test run flags into my reusable actions, which, while hard to look at, seems to work. It looks like the following (very similar to a workaround described in the aforementioned discussion):

steps:
  - name: reuse action for test
    if: ${{ inputs.test }}
    uses: ./path/to/action
  - name: reuse action
    if: ${{ !inputs.test }}
    uses: my-org/my-repo/path/to/action@master

But yet again, I've run into another limitation. It looks like GitHub Actions are parsed and verified before being interpreted. If path/to/action does not exist in @master yet (when it's still being developed), the test workflows fail verification. I was hoping it simply ignores the specification because the if condition resolves to false anyway, but it doesn't.

I'm curious how people are approaching this, or is it common for people not to test reusable actions?

[Marjuk06]

This is a classic "chicken and egg" problem with testing Composite Actions.

The reason your if: ${{ inputs.test }} workaround failed is that GitHub Actions performs static analysis on the entire workflow graph before execution starts. It verifies that all uses: references (like my-org/my-repo/...@master) are valid and accessible. If your new action hasn't been merged to master yet, the workflow crashes during this pre-flight check, ignoring your if condition entirely.

The standard solution used by many maintainers is to keep your action.yml "pure" (pointing to production refs) and use a "Patch-on-Test" strategy.

Instead of putting test logic inside the action, modify the action dynamically inside the test workflow.

The "Sed" Strategy

1. Keep your action.yml pointing to production: Write your composite action as if it's already live.
   `name: "Parent Action"
   steps:

• name: Call Sibling
  uses: my-org/my-repo/actions/sibling-action@main`

2. Patch it in your Test Workflow: In your .github/workflows/test.yml, checkout the code and run a simple sed command to rewrite the remote reference to a local relative path before the test runs.
   `# .github/workflows/test-action.yml
   name: Test Suite
   on: [push]

jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

  # HACK: Rewrite the action.yml to use local relative paths for testing
  # This bypasses the static analysis check for the remote ref
  - name: Patch action.yml for local test
    run: |
      sed -i 's|my-org/my-repo/actions/sibling-action@main|./actions/sibling-action|g' actions/parent-action/action.yml

  # Now run the action using the local path
  # It will now see the sibling action via the relative path we just injected
  - name: Run Parent Action
    uses: ./actions/parent-action`

Why this works

• Bypasses Static Analysis: Because the test workflow references the action via ./, the runner reads the action.yml file from the disk at runtime. Since you patched it before the step ran, it loads your modified version with valid local paths.
• Cleaner Code: Your production action.yml stays clean and doesn't need messy if inputs or test flags.

[rdgoite]

Interesting. It's very hack-y, but given the restrictions, it's worth a try. Thanks!

Really would have been nice if we didn't have to resort to this kinds of workaround.

[ericsciple]

Hi everyone 👋

We've been working on something that may help here. We're proposing a new $/ syntax that means "this repo, at this SHA":

- uses: $/path/to/action   # same repo, same SHA

This gives you version-safe references without hardcoding. The $/ resolves based on the YAML file it appears in, making it easier to test reusable workflows with their companion actions.

I've posted the full proposal over in community#26245. We'd love your feedback there!

— The GitHub Actions Team

[MrxYacinex]

Hello @rdgoite,

It looks like you have hit one of the most persistent pain points in developing Composite Actions: Graph resolution happens before variable expansion.

Because GitHub validates all uses references before looking at if conditions or context variables, your conditional workaround fails static analysis.

Here is a summary of your options, ranging from the immediate workaround to the upcoming native solution.

1. The Immediate Fix: The "Sed" Strategy (Recommended)
   Marjuk06 is correct. Until the platform changes, manipulating the file specifically during the test job is the most reliable method. It keeps your source "pure" for consumers (pointing to @main or @v1) while allowing the test runner to see the local version.

You can streamline Marjuk's suggestion by adding a setup step to your reusable workflow tests:

YAML
jobs:
test-action:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

  # Dynamically swap the remote reference for a local relative path
  # ONLY for this test run
  - name: Patch nested action for local test
    run: |
      sed -i 's|my-org/my-repo/path/to/action@master|./path/to/action|g' action.yml
      
  - name: Run Action
    uses: ./ # Uses the action at the root (or ./path/to/action) which now contains the patched path

2. The Future Fix: The $/ Syntax
   As Eric mentioned in the thread, the GitHub Actions team is actively proposing a native solution for this exact scenario.

The proposed syntax:

YAML
uses: $/path/to/action
This effectively tells the runner: "Use the action located at this path, relative to the file defining this workflow, pinned to the current SHA/Ref."

This solves the two main problems:

Versioning: It works in PRs (checks out the commit) and Production (checks out the tag/branch) automatically.

Nesting: It resolves relative to the calling file, not the repository root.

[github-actions[bot]]

🕒 Discussion Activity Reminder 🕒

This Discussion has been labeled as dormant by an automated system for having no activity in the last 60 days. Please consider one the following actions:

1️⃣ Close as Out of Date: If the topic is no longer relevant, close the Discussion as out of date at the bottom of the page.

2️⃣ Provide More Information: Share additional details or context — or let the community know if you've found a solution on your own.

3️⃣ Mark a Reply as Answer: If your question has been answered by a reply, mark the most helpful reply as the solution.

Note: This dormant notification will only apply to Discussions with the Question label. To learn more, see our recent announcement.

Thank you for helping bring this Discussion to a resolution! 💬