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.yml
file 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 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(())
}
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.set_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.
use ghactions::prelude::*;
#[derive(Actions, Debug, Clone)]
#[action(
// Action Name
name = "My Action",
// Action Location (use `generate` feature to generate action.yml file)
path = "./action.yml",
// Set the Actions Dockerfile image
// `ghactions` will check the Dockerfile exists
image = "./examples/advanced/Dockerfile",
)]
struct MyAction {
/// My Input
#[input(
// Input Description
description = "My Input Description",
// Default Value
default = "default"
)]
my_input: String,
#[output(
// Output Description
description = "My Output Description",
)]
my_output: String,
}
At build time, the action.yml
file will be generated with the following content:
name: My Action
inputs:
my_input:
description: My Input Description
default: default
outputs:
my_output:
description: My Output Description
runs:
using: "docker"
image: "Dockerfile"
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(())
}
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
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.