Crate ghactions 

GitHub Actions library written in Rust

GHActions is a Rust based library for helping users write amazing GitHub Actions in Rust!

📦 Install

Run the following command to add the library to your Cargo.toml file:

cargo add ghactions

📚 Features

• Easy to use
• Validate GitHub Actions files
• Automatic input and output parsing
• Generate action.yml file automatically from code
  • feature: generate
• Octocrab support
  • feature: octocrab
• Actions ToolCache support
  • Locating tools in the toolcache
  • feature: toolcache

🚀 Usage

Here is a simple example of how to use the library:

use ghactions::prelude::*;

#[derive(Actions)]
struct MyAction {}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialise the Action
    let action = MyAction::init()?;

    group!("Main Workflow");

    // Do something...

    Ok(())
}

Using Template (cargo-generate)

You can use the cargo-generate tool to create a new GitHub Action project with the library.

cargo generate --git https://github.com/42ByteLabs/ghactions

Advance Usage

Another feature of ghactions is the ability to automatically parse inputs and outputs from the action.

use ghactions::prelude::*;

#[derive(Actions, Debug, Clone)]
#[action(
    // Action Name
    name = "My Action",
    // Action Description
    description = "My Action Description",
)]
struct MyAction {
    /// My Input
    #[input(
        // Change the name of the input from `my_mode` to `mode`
        name = "mode",
        // Input Description
        description = "My Input Description",
        // Default Value
        default = "default"
    )]
    my_mode: String,

    // Automatical type conversion
    #[input(
        // Input Description
        description = "My Input Description",
        default = "42",
    )]
    my_int: i32,

    // Multiple Inputs
    #[input(
        // Input Description
        description = "My Second Input Description",
        // Automatically split the input by `,`
        split = ",",
    )]
    mutiple: Vec<String>,

    // Output called `version`
    #[output(
        // Output Description
        description = "My Output Description",
    )]
    version: String,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialise the Action
    let action = MyAction::init()?;

    group!("Main Workflow");
    info!("Action :: {:?}", action);

    info!("My Input Mode :: `{}`", action.my_mode);
    info!("My Multiple Input :: `{:?}`", action.mutiple);
    info!("My Output Version :: `{}`", action.version);

    groupend!();

    // Using the toolcache feature
    group!("ToolCache");
    
    // Load the ToolCache from the `examples/toolcache` folder
    let toolcache = ToolCache::from("examples/toolcache");
    // Find the Node.js 18.4.0 tool
    let tool = toolcache.find("node", "18.4.0").await?;
    info!("Tool :: {:?}", tool);

    groupend!();

    // There are 3 ways to set the output
    group!("Set Outputs");

    // Using the dynamically name Action method
    action.output_version("1.0.0");
    // Using the `set_output` method
    MyAction::set_output("version", "1.0.0")?;
    // Or the Macro `setoutput!` directly
    setoutput!("version", "1.0.0");

    groupend!();

    Ok(())
}

Generating the action.yml file

The generate feature will allow you to generate the action.yml file from the code. There are 3 ways to generate the action.yml file:

• image mode:
  • This will generate the action.yml file with a container image.
• entrypoint mode:
  • This will generate a composite Action with an entrypoint script.
• installer mode:
  • This will generate a composite Action with an installer script.

use ghactions::prelude::*;

#[derive(Actions, Debug, Clone)]
#[action(
    // Container / Docker file to supply the Action
    image = "./examples/advanced/Dockerfile",
    // [Optional] Supply a entrypoint for the container image
    entrypoint = "./examples/entrypoint/entrypoint.sh",
)]
struct ContainerAction {
    // ...
}

#[derive(Actions, Debug, Clone)]
#[action(
    // Entrypoint is a Composite Action with an entrypoint script
    entrypoint = "./examples/entrypoint/entrypoint.sh",
)]
struct EntrypointAction {
    // ...
}

#[derive(Actions, Debug, Clone)]
#[action(
    // Composite Action with an installer script
    installer
)]
struct InstallerAction {
    // ...
}

At build time, the action.yml file will be generated with the following content.

Using Octocrab

Enabling the octocrab feature will allow you to use the Octocrab library.

use ghactions::prelude::*;

#[derive(Actions, Debug, Clone)]
struct MyAction {}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let action = MyAction::init()?;

    group!("Octocrab");
    // Automatically setup Octocrab with the GitHub Instance and Token
    let octocrab = action.octocrab()?;

    // ... Do something...

    Ok(())
}

🦸 Support

Please create GitHub Issues if there are bugs or feature requests.

This project uses Semantic Versioning (v2) and with major releases, breaking changes will occur.

📓 License

This project is licensed under the terms of the MIT open source license. Please refer to MIT for the full terms.

Modules

prelude

Prelude module to re-export the most commonly used types

Macros

errorf

Error for files (including line and column numbers)

group

Group Macros

groupend

End Group Macros

setoutput

Sets the output of the Actions which can be used in subsequent Actions.

Structs

ToolCache

Tool Cache

Enums

ActionsError

Actions Error

ToolCacheArch

Tool Cache CPU Architecture enum

ToolPlatform

Tool Cache Platform

Traits

ActionTrait

Action Trait

Functions

init_logger

Initialise and create a env_logger::Builder which follows the GitHub Actions logging syntax.

Derive Macros

Actions

Derive macro for GitHub Actions