jarvusinnovations / background-action Goto Github PK

Background commands with log tailing/capture; waits until file/port/socket/http are ready to proceed. Isolates/dedupe errors.

License: Apache License 2.0

JavaScript 100.00%

background process command wait-on logging bg fg

background-action's Introduction

background-action

Run commands in the background with logging and failure detection. background-action will send your processes to the background once a set of files, ports, sockets or http resources are available. It can optionally tail output until ready/timeout and/or log output stderr/stdout post-run.

Purpose

Use background-action to bootstrap your system under test to eliminate workflow timeouts, race conditions, and test suite failures when the system fails to start. Specify the resources (http, file, tcp, socket) to wait-on and how long to wait-for before continuing to the next step. tail stdout/stderr while you wait and/or log-output post-run conditionally using log-output-if.

What can happen when a system under test running in the background fails to start?

No indication of the cause of failure
Costly workflow timeouts
Spurious test failures
Lost log output

background-action addresses these issues directly and was purpose-built to bootstrap your system under test in a discrete step to isolate failures at the source. We hope that it saves you and your team time and reduces frustration in these trying times.

Crafted with ❤️ by Jarvus Innovations in Philadelphia

Usage

Example

jobs:
  tests:
    runs-on: ubuntu-latest
    env:
      API_PORT: 1212
    steps:
      - uses: actions/checkout@v4
      - uses: JarvusInnovations/background-action@v1
        name: Bootstrap System Under Test (SUT)
        with:
          run: |
            npm install
            PORT=$API_PORT node test/server.js &
            PORT=2121 node test/server.js &
            PORT=3232 node test/server.js &
          # your step-level and job-level environment variables are available to your commands as-is
          # npm install will count towards the wait-for timeout
          # whenever possible, move unrelated scripts to a different step
          # to background multiple processes: add & to the end of the command

          wait-on: |
            http://localhost:${{ env.API_PORT }}
            http-get://localhost:2121
            tcp:localhost:3232
            file://very-important-secrets.txt
          # IMPORTANT: to use environment variables in wait-on, you must use this form: ${{ env.VAR }}
          # See wait-on section below for all resource types and prefixes

          tail: true # true = stderr,stdout
          # This will allow you to monitor the progress live

          log-output-resume: stderr
          # Eliminates previously output stderr log entries from post-run output

          wait-for: 5m

          log-output: stderr,stdout # same as true

          log-output-if: failure
          # failure = exit-early or timeout

          working-directory: backend
          # sets the working directory (cwd) for the shell running commands

    - name: Tests that require the resources defined above to run
      run: npm test

Configuration

Parameter	Description	Allowed Values	Default
`run`	Commands to run, supports multiple lines
`wait-on`	What resources to wait for: `http\|tcp\|file\|socket\|unix://`	See `wait-on` below
`wait-for`	How long to wait for (default unit: `ms`)	`#ms, #s/sec, #m/min, #h/hr`	`5m`
`tail`	Which outputs to tail while you wait	`stderr,stdout,true,false`	`stderr,stdout`
`log-output`	Which outputs to log post-run (after the job)	`stderr,stdout,true,false`	`stderr,stdout`
`log-output-resume`	Which outputs should resume where tail left off (no duplicate lines)	`stderr,stdout,true,false`	`stderr,stdout`
`log-output-if`	Whether or not to log output	`failure,exit-early,timeout,success,true,false`
`working-directory`	Sets the working directory (cwd) for the shell running commands

wait-on

background-action leverages the handy wait-on package to control flow. You can pass any number of resources in the wait-on configuration parameter separated by commas or newlines. For advanced use cases, such as: client-side SSL certs, authorization, proxy configuration and/or custom http headers you can provide a JSON serialized configuration object that matches wait-on's node.js api usage.

Resource Types

Prefix	Description	Example
`file:`	Regular file (also default type)	`file:/path/to/file`
`http:`	HTTP HEAD returns 2XX response	`http://m.com:90/foo`
`https:`	HTTPS HEAD returns 2XX response	`https://my/bar`
`http-get:`	HTTP GET returns 2XX response	`http://m.com:90/foo`
`https-get:`	HTTPS GET returns 2XX response	`https://my/bar`
`tcp:`	TCP port is listening	`1.2.3.4:9000 or foo.com:700`
`socket:`	Domain Socket is listening	`socket:/path/to/sock`
`http://unix:`	http: over socket	`http://unix:SOCK_PATH:URL_PATH`
`http-get://unix:`	http-get: over socket	`http-get://unix:/path/to/sock:/foo/bar`

See the actions tab for runs of this action! 🚀

background-action's People

Contributors

Stargazers

Watchers

Forkers

ross-forallsecure rubendinho kostyay fathom-global rmichalak rafalwilinski th-le craigw multimo cclauss

background-action's Issues

Error: Cannot find module '@actions/core'

Hi there

I tried this out on a project and got this error:

Run JarvusInnovations/background-action@c44874fd82200490d31d804b7270350705582a23
node:internal/modules/cjs/loader:936
  throw err;
  ^

Error: Cannot find module '@actions/core'
Require stack:
- /home/runner/work/_actions/JarvusInnovations/background-action/c44874fd82200490d31d804b7270350705582a23/index.js
    at Function.Module._resolveFilename (node:internal/modules/cjs/loader:933:15)
    at Function.Module._load (node:internal/modules/cjs/loader:778:27)
    at Module.require (node:internal/modules/cjs/loader:1005:19)
    at require (node:internal/modules/cjs/helpers:102:18)
    at Object.<anonymous> (/home/runner/work/_actions/JarvusInnovations/background-action/c44874fd82200490d31d804b7270350705582a23/index.js:1:14)
    at Module._compile (node:internal/modules/cjs/loader:1105:14)
    at Object.Module._extensions..js (node:internal/modules/cjs/loader:1159:10)
    at Module.load (node:internal/modules/cjs/loader:981:32)
    at Function.Module._load (node:internal/modules/cjs/loader:822:12)
    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:77:12) {
  code: 'MODULE_NOT_FOUND',
  requireStack: [
    '/home/runner/work/_actions/JarvusInnovations/background-action/c44874fd82200490d31d804b7270350705582a23/index.js'
  ]
}

With this config, mostly copied from the README.

      - uses: JarvusInnovations/background-action@c44874fd82200490d31d804b7270350705582a23 # v1.0.3
        name: Bootstrap System Under Test (SUT)
        with:
          run: |
            script/server &

          wait-on: |
            http://localhost:4274

          tail: true # true = stderr,stdout

          log-output-resume: stderr
          # Eliminates previosuly output stderr log entries from post-run output

          wait-for: 1m

          log-output: stderr,stdout # same as true

          log-output-if: failure
          # failure = exit-early or timeout

          working-directory: renderer
          # sets the working directory (cwd) for the shell running commands

I tried installing @actions/core into my own project but that didn't work. Is there more here that I need to do?

.out and .err files should be created in a temp dir

Currently, the .out and .err files are created in the working directory, or the workspace directory if the working directory is not set. This is a problem because it means the files are inside the Git repo. I have an automated release workflow that updates some files and commits them, and the .out and .err files got accidentally committed to the repo because of that.

So I suggest that the .out and .err files should be created in a temp directory outside the workspace instead. The RUNNER_TEMP environment variable provides a temp directory that you could use.

Deprecated save-state

Hi - this is a great action and exactly what I'm looking for.

I did notice the below warnings when running the action:

Warning: The `save-state` command is deprecated and will be disabled soon. Please upgrade to using Environment Files. For more information see: https://github.blog/changelog/2022-10-11-github-actions-deprecating-save-state-and-set-output-commands/

Post-job Log Output: Improve Error Handling for ENOENT in complex workflows

Hi, I am running this action in my pipeline:

      - name: Forward ports using kubectl
        uses: JarvusInnovations/[email protected]
        with:
          run: |
            kubectl port-forward mypod1 8080:8080 &
            kubectl port-forward mypod2 9200:9200 &
          wait-on: http://localhost:8080/api/info/version

The post job "Post Forward ports using kubectl" fails the pipeline with the following error message:

Post job cleanup.
Output:
Error: ENOENT: no such file or directory, open '/home/runner/work/myrepo/myrepo/1646.out

Any idea why this could happen? Thank you!

Add artifact support for multi-job workflows

Reported in #187

It appears if a workflow contains multiple jobs, the post-run job will fail as the log files are no longer present in the file system.

In order to address this we'd need to use actions/upload-artifact and actions/download-artifact to pass the log files between jobs.

I haven't researched whether this is something that can be done declaratively by end-users or if we need to make changes to the post-run.js code to support this.

Deprecation Warnings for Node 16

Hello 👋

Thanks for your work on this plugin, super useful!

However, we have started to receive deprecation warnings from github actions for node v16. I have a PR that hopefully helps with the upgrade #184 .

I am new to actions so not sure if there is more that is necessary here.

https://github.blog/changelog/2023-09-22-github-actions-transitioning-from-node-16-to-node-20/#:~:text=Node%2016%20has%20reached%20its,before%20finalizing%20the%20transition%20date.