Actionoscope

Actionoscope is a CLI tool to run steps from a GitHub Actions workflow locally. It is meant to be a simplified version of the very complete project act. I highly recommend that you look at it. The main difference is that Actionoscope avoids using docker containers to run workflow steps, which in practice means that:

• it is not able to run any step that uses another action - in fact, it will ignore any step that uses an action; if you need this, please refer to act;
• it is faster to run, and will not bloat your local disk with docker images;

Motivation

what is it for

Avoid the tedious doom loop of pushing endless commits, waiting ages for github runners to pick your workflow, just to find out that there was yet another typo on the CI/CD workflow. actionoscope is meant to make it dead simple to run locally individual steps (one or multiple) of your GitHub Actions workflow, so you can keep your mental sanity. Last but not least, it is also meant to be a lightweight alternative to the very awesome act

what is it not for

actionoscope is not meant to:

• work with any other CI/CD tool other than GitHub Actions (forget it Jenkins).
• replace the actual CI/CD pipeline.

Features

• Automatically detect existing workflows in the current directory repository, and run all or a subset of their steps;
• Ability to specify to run just a single job from a workflow, or even just a single step;
• Ability to provide a dot-env file to replace secrets variables;
• Ability to automatically extract github metadate from the current git repository, namely ${{ github.repository_owner }}, ${{ github.repository }}, ${{ github.ref_name }};
• list existing workflows in the current directory repository;

Installation

To install Actionoscope, you have two options:

a) grab one of the pre-built binaries from the releases page; b) build it yourself.

To build it yourself, you need to have Rust installed. If you don't have Rust installed, you can install it using rustup.

# clone the repo
git clone git@github.com:diogoaurelio/actionoscope.git

cd actionoscope
# build the project & copy the project to your local bin so you can run it from anywhere as > actionoscope
cargo clean && cargo build --release && cp target/release/actionoscope ~/.local/bin/

# fun
actionoscope --help

Usage

Running a Single Step

To run a single step from a workflow file:

actionoscope run --workflow-file <path_to_workflow_file> --job <job_name> --step <step_name>

Or with short notation:

actionoscope run -w <path_to_workflow_file> -j <job_name> -s <step_name>

Running All Steps Since a given step

To run all steps from a specified step:

actionoscope run --workflow-file <path_to_workflow_file> --job <job_name> --from-step <step_name>

Or with short notation:

actionoscope run -w <path_to_workflow_file> -j <job_name> -f <starting_step_name>

Running All Steps from a given step until another given step

To run a subset of steps:

actionoscope run --workflow-file <name_of_workflow_file> --job <job_name> --from-step <starting_step_name> --to-step <final_step_name>

Note that the provided steps are inclusive - they will also be run.

Or with short notation:

actionoscope run -w <name_of_workflow_file> -j <job_name> -f <starting_step_name> -t <final_step_name>

Running All Steps except some that should be skipped

To run some steps except a few that should be skipped, you can use the --skip-step flag. You can specify multiple steps to skip by using the flag multiple times. For example, to skip step-x and step-y:

actionoscope run --workflow-file <name_of_workflow_file> --job <job_name> --skip-step <step-x> --skip-step <step-y>

Note that the match is done by name or id, so you can use either the name of the step or its id as defined in the workflow file.

Or with short notation:

actionoscope run -w <name_of_workflow_file> -j <job_name> -k <step-x> -k <step-y>

Providing secrets variables

In case you use secrets in your workflow (for example ${{ secrets.MY_VAR }}), you can provide them using the --secrets flag. The secrets should be provided in the format SECRET_NAME=SECRET_VALUE. For example:

actionoscope run --workflow-file <name_of_workflow_file> -j <job_name> --secrets-file .env

Or with short notation:

actionoscope run -w <name_of_workflow_file> -j <job_name> -e .env

Examples

Example Workflow File

Here is an example of a GitHub Actions workflow file

name: CI
on:
  push:
    branches:
      - main
  pull_request: {}
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        id: first
        uses: actions/checkout@v3
      - name: Run tests
        id: second
        run: cargo test

To run the Run tests step from the example workflow file:

actionoscope run --workflow-file example_workflow.yml --job build --step second

# or using just short notation
actionoscope run -w example_workflow.yml -j build -s second

Development

Running Tests

To run the tests for the project:

RUST_BACKTRACE=1 cargo test --all-features

# OR, sprinkling a bit of inception:
actionoscope run -w on.pr.yaml -j build -s test

Running full CI pipeline

To run the full CI pipeline (linter checks and tests), you can simply run:

actionoscope run -w on.pr.yaml

License

This project is licensed under the MIT License. See the LICENSE file for details.