[Feature Request] Create a dedicated GitHub Action

[cstanislawski]

Problem Statement

Currently, using argocd-diff-preview in a GitHub Actions workflow requires users to copy a fairly complex and verbose docker run command into their YAML file.

This approach has several drawbacks:

• It's verbose and error-prone - Users need to correctly configure multiple volume mounts (-v), network settings (--network=host), and map workflow variables to the container's environment variables (-e). A small mistake can easily break the setup,
• It exposes implementation details: The user is forced to interact directly with Docker and understand the internal directory structure (/base-branch, /target-branch) that the tool expects.

Proposed Solution

I propose creating a dedicated, composite GitHub Action for this tool. This would abstract away the complexity of the docker run command and provide a much cleaner, more intuitive, and native user experience within GitHub Actions.

Key benefits would include:

• Simplicity - Drastically reduces the amount of boilerplate YAML needed,
• Encapsulation - Hides all the Docker-specific complexity from the end-user,
• Discoverability - Allows the action to be published on the GitHub Marketplace,
• Clear Inputs/Outputs - Provides a well-defined interface with inputs and outputs for better workflow integration.

---

IMO this would be a huge improvement for usability and would make the project much more approachable for new users.

I'd be happy to work on the implementation, but before doing so, I'd like to get some feedback on the idea, what do you think?

[dag-andersen]

Hi @cstanislawski ! Thank you for sharing your thoughts!

The reason I’ve kept it as a Docker container is:

• I wanted the tool to be easy to use for non-GitHub users. Keeping the docker run code examples in the documentation ensures that anyone can simply copy, paste, and tweak the command for their use case (e.g., if they’re on GitLab or something similar). This approach was recommended to me before I presented it at ArgoCon last year.
• I worry that using a GitHub Action might actually make things more confusing. There are many ways to run the tool (which is why it has so many flags and options), and it’s easy to misconfigure if you don’t fully understand what’s happening. When someone sets it up incorrectly, it’s usually because they misunderstood how it works. I understand the goal of “Simplicity – drastically reduce the amount of boilerplate YAML needed,” but I’m not sure this is a good change. The current amount of boilerplate forces the user to look at each option and verify it’s set correctly. It actually “teaches” the user how the tool works and what it needs, rather than hiding that logic behind the scenes.

That said, I’m sure I’m biased here! 😄 I personally prefer tools where it’s clear which commands are being run, compared to a “magic GitHub Action” that just does something. I like being able to see exactly what’s happening when I run other people’s code.

But I know some people love Actions! You’re absolutely welcome to turn it into a nice little GitHub Action :) I just don’t have much experience with them myself.

When adding it to the documentation, we need to be careful not to make the tool harder to use for GitLab users. We should always include both an example using the GitHub Action and an example showing how to solve the problem manually by running individual commands.

[cstanislawski]

Thanks for the feedback @dag-andersen

I agree with your points about keeping it accessible for non-GitHub users and avoiding a "magic" black box. My goal is definitely to add this as an optional approach to run the tool, not change the core behavior/distribution that works.

The Action would be exactly what you suggested: a simple wrapper, with both methods clearly documented.

Sounds like we're on the same page - I'll start working on a PR soon-ish. Thanks for the green light :)