Struct WorkflowCommand 

pub struct WorkflowCommand { /* private fields */ }

A single GitHub Actions workflow command: ::name key=val,...::message.

Properties are kept in insertion order to produce deterministic output (which the test-suite and @actions/core both rely on).
The Display implementation performs all required percent-encoding, so the rendered string is always safe to write to stdout.

Examples

use actions_rs::WorkflowCommand;

let cmd = WorkflowCommand::new("error")
    .property("file", "src/a,b.rs") // `,` is property-encoded
    .message("bad: x\ny");          // `\n` is data-encoded
assert_eq!(cmd.to_string(), "::error file=src/a%2Cb.rs::bad: x%0Ay");

Implementations

impl WorkflowCommand

pub fn new(name: &'static str) -> Self

Create a command with the given name and an empty message.

Examples

use actions_rs::WorkflowCommand;
assert_eq!(WorkflowCommand::new("endgroup").to_string(), "::endgroup::");

pub fn message(self, message: impl Into<String>) -> Self

Set the command message (the segment after the final ::).

Examples

use actions_rs::WorkflowCommand;
let c = WorkflowCommand::new("warning").message("low disk");
assert_eq!(c.to_string(), "::warning::low disk");

pub fn property(self, key: &'static str, value: impl Into<String>) -> Self

Append a property. The value is percent-encoded on render.

Examples

use actions_rs::WorkflowCommand;
let c = WorkflowCommand::new("notice").property("line", "42").message("m");
assert_eq!(c.to_string(), "::notice line=42::m");

pub fn property_opt( self, key: &'static str, value: Option<impl Into<String>>, ) -> Self

Append a property only when value is Some.

Examples

use actions_rs::WorkflowCommand;
let c = WorkflowCommand::new("notice")
    .property_opt("file", Option::<String>::None) // skipped
    .property_opt("line", Some("10"))
    .message("m");
assert_eq!(c.to_string(), "::notice line=10::m");

pub fn issue_to<W: Write>(&self, w: W) -> Result<()>

Render and write this command followed by a newline to w.

Used by the test-suite to capture output; the convenience helpers use WorkflowCommand::issue.

Errors

Propagates any write error from w.

Examples

use actions_rs::WorkflowCommand;
let mut buf = Vec::new();
WorkflowCommand::new("debug").message("d").issue_to(&mut buf).unwrap();
assert_eq!(buf, b"::debug::d\n");

pub fn issue(&self)

Render and write this command to stdout followed by a newline.

Stdout is the runner’s command channel; a failed write here cannot be meaningfully recovered from inside an action, so the result is dropped deliberately (matching @actions/core behaviour).

Examples

use actions_rs::WorkflowCommand;
// Emit a command the higher-level API does not cover.
WorkflowCommand::new("add-matcher").message(".github/pm.json").issue();

Examples found in repository

examples/ci_selfcheck.rs (line 42)

fn main() -> ExitCode {
    let notice = Annotation::new()
        .file("examples/ci_selfcheck.rs")
        .span(AnnotationSpan::Line {
            start: 18,
            end: Some(24),
        })
        .title("ci_selfcheck")
        .command(
            AnnotationKind::Notice,
            "actions-rs self-check ran in this job",
        );
    let warning = Annotation::new()
        .file("src/summary.rs")
        .span(AnnotationSpan::Column {
            line: 112,
            start: 5,
            end: None,
        })
        .title("example warning")
        .command(
            AnnotationKind::Warning,
            "ranged warning annotation covering Summary::code_block",
        );
    notice.issue();
    warning.issue();

    if let Err(e) = output::set_output("answer", "42\nwith newline") {
        eprintln!("::error::set_output: {e}");
        return ExitCode::FAILURE;
    }
    if let Err(e) = output::export_var("DEMO_FLAG", true)
        && !matches!(
            e,
            actions_rs::Error::UnavailableFileCommand {
                var: "GITHUB_ENV",
                ..
            }
        )
    {
        eprintln!("::error::export_var: {e}");
        return ExitCode::FAILURE;
    }

    let gh_output = read_env_file("GITHUB_OUTPUT").unwrap_or_else(|| "<local: unset>".into());
    let gh_env = read_env_file("GITHUB_ENV").unwrap_or_else(|| "<local: unset>".into());

    // Build the whole report once.
    let mut report = String::new();
    for (label, body) in [
        ("workflow commands (stdout)", format!("{notice}\n{warning}")),
        ("GITHUB_OUTPUT", gh_output.clone()),
        ("GITHUB_ENV", gh_env.clone()),
    ] {
        let _ = write!(report, "===== {label} =====\n{body}\n");
    }

    // 1. normal out (the job log).
    print!("{report}");

    // 2. a tmpfile on the runner.
    let tmp = std::env::var_os("RUNNER_TEMP")
        .map(PathBuf::from)
        .unwrap_or_else(std::env::temp_dir)
        .join("ci_selfcheck.report.txt");
    if let Err(e) = std::fs::write(&tmp, &report) {
        eprintln!("::error::tmpfile write: {e}");
        return ExitCode::FAILURE;
    }

    // 3. read the tmpfile back, drop it into the summary as one code block.
    let captured = match std::fs::read_to_string(&tmp) {
        Ok(c) => c,
        Err(e) => {
            eprintln!("::error::tmpfile read: {e}");
            return ExitCode::FAILURE;
        }
    };
    let mut summary = Summary::new();
    summary
        .heading("actions-rs ci_selfcheck", 2)
        .code_block(&captured, None);
    if let Err(e) = summary.write_overwrite() {
        eprintln!("::error::summary.write_overwrite: {e}");
        return ExitCode::FAILURE;
    }

    // round-trip assertions (only meaningful when the runner set the files).
    let mut exit = ExitCode::SUCCESS;
    if std::env::var_os("GITHUB_OUTPUT").is_some() {
        for (var, needle, hay) in [
            ("GITHUB_OUTPUT", "answer<<", &gh_output),
            ("GITHUB_ENV", "DEMO_FLAG<<", &gh_env),
        ] {
            if !hay.contains(needle) {
                eprintln!("::error::{var} missing {needle:?}");
                exit = ExitCode::FAILURE;
            }
        }
    }
    exit
}

Trait Implementations

impl Clone for WorkflowCommand

fn clone(&self) -> WorkflowCommand

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for WorkflowCommand

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for WorkflowCommand

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for WorkflowCommand

fn eq(&self, other: &WorkflowCommand) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for WorkflowCommand

impl StructuralPartialEq for WorkflowCommand