Back in the days, and it’s still under active development, there was act
, a tool to test GitHub Actions locally. Although it’s a great project and I suggest it for complex setup, sometimes you need something easier, and now there’s an official solution for that. Let’s see how it works together.
Looking for a solution to test GitHub Actions locally, I found act
: a popular third-party tool to do so. It has been around for a while, and it got a VS Code extension as well, but it’s far more complex than I need. It depends on Docker and supports GitHub CLI, for example.
But I just want to execute some lines of JavaScript, then I kept going until I found a permanent solution: Local Action Debugger is the official way of doing it, and it’s pretty easy to use. All you have to do is installing it as a development dependency in your GitHub Actions project.
npm i -D @github/local-action
Notice that the package name has no ending “s”. It will also work without being installed: anyway, it supports pnpm
and yarn
as well. GitHub says that it only includes basic functionalities, so don’t expect it to fit large projects. You can always rely on act
for them.
Local Action Debugger is useful with either JavaScript or TypeScript GitHub Actions: if you want it to be 100% compatible with your project, you may want to start it using a template. I’m doing this for something I’ll share with you soon. The best way to integrate it is by setting a script in your package.json
file.
"scripts": {
"local-action": "npx @github/local-action . src/main.ts .env"
}
Of course, you can use the same npx
command everywhere, even without installing the dependency. One of the most important details here is the .env
file: although you must exclude it from being pushed to a repository, it’s crucial for testing. I added a .env.example
file to help contributor in my own project.
You should follow the official GitHub instructions, since the debugger will locate and execute your sources from a specific folder structure. TypeScript support needs allowJs
to be set as false
for it to work—and I can assure you that this is the case. Then, you can execute the command.
npm run local-action
This will start the Local Action Debugger, which at first will print a list of files and folders ordered by their index: the Action Path
, the Entrypoint
, and the Environment File
you specified as arguments. So, you will get the metadata, and the output if you set any in action.yml
.
I built a GitHub Action that export a file in the root, and I got it generated right there. I don’t think I could be more satisfied: this solution is fast, easy, and maintained directly by GitHub, so it uses the standard libraries to provide its functionalities. I strongly suggest you to implement it in your projects.
Curious about what I’m cooking? I already talked about it in a previous article. I’m also planning to replace Rollup with Rolldown in GitHub Actions as well, so stay tuned for further developments: I’m 75% ready to share my project, but it still need some improvements before being published.
Top comments (0)