GHActions is a Rust based library for helping users write amazing GitHub Actions in Rust!
Run the following command to add the library to your Cargo.toml file:
cargo add ghactions- Easy to use
- Validate GitHub Actions files
- Automatic input and output parsing
- Generate
action.ymlfile automatically from code- feature:
generate
- feature:
- Octocrab support
- feature:
octocrab
- feature:
- Actions ToolCache support
- Locating tools in the toolcache
- feature:
toolcache
Here is a simple ex 8000 ample 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(())
}You can use the cargo-generate tool to create a new GitHub Action project with the library.
cargo generate --git https://github.com/42ByteLabs/ghactionsAnother 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(())
}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:
imagemode:- This will generate the
action.ymlfile with a containerimage.
- This will generate the
entrypointmode:- This will generate a composite Action with an entrypoint script.
installermode:- 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.
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(())
}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.
This project is licensed under the terms of the MIT open source license. Please refer to MIT for the full terms.