Struct Summary 

pub struct Summary { /* private fields */ }

Accumulating job-summary builder. Chain the builder methods, then write (append) or write_overwrite. Building is pure and inspectable via stringify; only the write* methods touch GITHUB_STEP_SUMMARY.

Examples

use actions_rs::Summary;

let mut s = Summary::new();
s.heading("Build", 2)
    .code_block("cargo test", Some("sh"));

assert_eq!(
    s.stringify(),
    "<h2>Build</h2>\n<pre lang=\"sh\"><code>cargo test</code></pre>\n"
);

// In a real action you would then persist it:
// s.write()?;  // appends to $GITHUB_STEP_SUMMARY

Implementations

impl Summary

pub fn new() -> Self

Create an empty summary buffer.

Examples

let s = actions_rs::Summary::new();
assert!(s.is_empty());

Examples found in repository

examples/demo.rs (line 62)

fn main() {
    log::info(format!(
        "in GitHub Actions: {} | CI: {} | step-debug: {}",
        env::is_github_actions(),
        env::is_ci(),
        log::is_debug()
    ));

    let ctx = actions_rs::Context::new();
    log::info(format!(
        "repo={:?} ref={:?} sha={:?}",
        ctx.repository(),
        ctx.ref_name(),
        ctx.sha()
    ));

    // Located annotation with a line range — should print:
    // ::warning title=demo,file=src/lib.rs,line=10,endLine=12::heads up
    Annotation::new()
        .file("src/lib.rs")
        .line(10)
        .end_line(12)
        .title("demo")
        .warning("heads up: this span looks suspicious");

    // Escaping check: newline in data, colon/comma in a property.
    Annotation::new()
        .title("type: mismatch, really")
        .error("line one\nline two");

    let total = log::group("expensive step", || {
        log::info("...working...");
        2 + 2
    });
    log::info(format!("group returned {total}"));

    actions_rs::warning!("formatted macro: {} items left", 7);

    output::set_output("answer", 42).expect("set_output");
    match output::export_var("DEMO_FLAG", true) {
        Ok(()) => {}
        Err(actions_rs::Error::UnavailableFileCommand {
            var: "GITHUB_ENV", ..
        }) => {
            log::info("GITHUB_ENV unset; skipping export_var in local demo");
        }
        Err(err) => panic!("export_var: {err}"),
    }

    let mut summary = Summary::new();
    summary
        .heading("Demo Report", 2)
        .raw("Built by the `demo` example.", true)
        .table([
            vec![Cell::header("Check"), Cell::header("Result")],
            vec![Cell::new("clippy"), Cell::new("pass")],
            vec![Cell::new("tests"), Cell::new("36 pass")],
        ])
        .code_block("cargo test", Some("sh"));
    summary.write().expect("write summary");
    log::info("summary written (if GITHUB_STEP_SUMMARY was set)");
}

examples/ci_selfcheck.rs (line 96)

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
}

pub fn raw(&mut self, text: impl AsRef<str>, eol: bool) -> &mut Self

Append raw text without HTML escaping. When eol is true a newline is appended after it.

Safety

This is the one builder method that does not escape & < > ". Passing untrusted input here is an HTML-injection vector. Use it only for trusted or already-escaped markup; for arbitrary text prefer Summary::code_block / Summary::heading etc., which escape.

Examples

let mut s = actions_rs::Summary::new();
s.raw("<div class=\"trusted\">ok</div>", true);
assert_eq!(s.stringify(), "<div class=\"trusted\">ok</div>\n");

Examples found in repository

examples/demo.rs (line 65)

fn main() {
    log::info(format!(
        "in GitHub Actions: {} | CI: {} | step-debug: {}",
        env::is_github_actions(),
        env::is_ci(),
        log::is_debug()
    ));

    let ctx = actions_rs::Context::new();
    log::info(format!(
        "repo={:?} ref={:?} sha={:?}",
        ctx.repository(),
        ctx.ref_name(),
        ctx.sha()
    ));

    // Located annotation with a line range — should print:
    // ::warning title=demo,file=src/lib.rs,line=10,endLine=12::heads up
    Annotation::new()
        .file("src/lib.rs")
        .line(10)
        .end_line(12)
        .title("demo")
        .warning("heads up: this span looks suspicious");

    // Escaping check: newline in data, colon/comma in a property.
    Annotation::new()
        .title("type: mismatch, really")
        .error("line one\nline two");

    let total = log::group("expensive step", || {
        log::info("...working...");
        2 + 2
    });
    log::info(format!("group returned {total}"));

    actions_rs::warning!("formatted macro: {} items left", 7);

    output::set_output("answer", 42).expect("set_output");
    match output::export_var("DEMO_FLAG", true) {
        Ok(()) => {}
        Err(actions_rs::Error::UnavailableFileCommand {
            var: "GITHUB_ENV", ..
        }) => {
            log::info("GITHUB_ENV unset; skipping export_var in local demo");
        }
        Err(err) => panic!("export_var: {err}"),
    }

    let mut summary = Summary::new();
    summary
        .heading("Demo Report", 2)
        .raw("Built by the `demo` example.", true)
        .table([
            vec![Cell::header("Check"), Cell::header("Result")],
            vec![Cell::new("clippy"), Cell::new("pass")],
            vec![Cell::new("tests"), Cell::new("36 pass")],
        ])
        .code_block("cargo test", Some("sh"));
    summary.write().expect("write summary");
    log::info("summary written (if GITHUB_STEP_SUMMARY was set)");
}

pub fn eol(&mut self) -> &mut Self

Append a newline.

Examples

let mut s = actions_rs::Summary::new();
s.raw("a", false).eol().raw("b", false);
assert_eq!(s.stringify(), "a\nb");

pub fn heading(&mut self, text: impl Into<SummaryText>, level: u8) -> &mut Self

Append an <h1>–<h6> heading (level clamped to 1..=6). Text is escaped unless you pass SummaryText::html.

Examples

let mut s = actions_rs::Summary::new();
s.heading("Result", 9); // level clamps to 6
assert_eq!(s.stringify(), "<h6>Result</h6>\n");

Examples found in repository

examples/demo.rs (line 64)

fn main() {
    log::info(format!(
        "in GitHub Actions: {} | CI: {} | step-debug: {}",
        env::is_github_actions(),
        env::is_ci(),
        log::is_debug()
    ));

    let ctx = actions_rs::Context::new();
    log::info(format!(
        "repo={:?} ref={:?} sha={:?}",
        ctx.repository(),
        ctx.ref_name(),
        ctx.sha()
    ));

    // Located annotation with a line range — should print:
    // ::warning title=demo,file=src/lib.rs,line=10,endLine=12::heads up
    Annotation::new()
        .file("src/lib.rs")
        .line(10)
        .end_line(12)
        .title("demo")
        .warning("heads up: this span looks suspicious");

    // Escaping check: newline in data, colon/comma in a property.
    Annotation::new()
        .title("type: mismatch, really")
        .error("line one\nline two");

    let total = log::group("expensive step", || {
        log::info("...working...");
        2 + 2
    });
    log::info(format!("group returned {total}"));

    actions_rs::warning!("formatted macro: {} items left", 7);

    output::set_output("answer", 42).expect("set_output");
    match output::export_var("DEMO_FLAG", true) {
        Ok(()) => {}
        Err(actions_rs::Error::UnavailableFileCommand {
            var: "GITHUB_ENV", ..
        }) => {
            log::info("GITHUB_ENV unset; skipping export_var in local demo");
        }
        Err(err) => panic!("export_var: {err}"),
    }

    let mut summary = Summary::new();
    summary
        .heading("Demo Report", 2)
        .raw("Built by the `demo` example.", true)
        .table([
            vec![Cell::header("Check"), Cell::header("Result")],
            vec![Cell::new("clippy"), Cell::new("pass")],
            vec![Cell::new("tests"), Cell::new("36 pass")],
        ])
        .code_block("cargo test", Some("sh"));
    summary.write().expect("write summary");
    log::info("summary written (if GITHUB_STEP_SUMMARY was set)");
}

examples/ci_selfcheck.rs (line 98)

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
}

pub fn code_block( &mut self, code: impl AsRef<str>, lang: Option<&str>, ) -> &mut Self

Append a fenced <pre><code> block with an optional language hint.

Examples

let mut s = actions_rs::Summary::new();
s.code_block("cargo test", Some("sh"));
assert_eq!(s.stringify(), "<pre lang=\"sh\"><code>cargo test</code></pre>\n");

Examples found in repository

examples/demo.rs (line 71)

fn main() {
    log::info(format!(
        "in GitHub Actions: {} | CI: {} | step-debug: {}",
        env::is_github_actions(),
        env::is_ci(),
        log::is_debug()
    ));

    let ctx = actions_rs::Context::new();
    log::info(format!(
        "repo={:?} ref={:?} sha={:?}",
        ctx.repository(),
        ctx.ref_name(),
        ctx.sha()
    ));

    // Located annotation with a line range — should print:
    // ::warning title=demo,file=src/lib.rs,line=10,endLine=12::heads up
    Annotation::new()
        .file("src/lib.rs")
        .line(10)
        .end_line(12)
        .title("demo")
        .warning("heads up: this span looks suspicious");

    // Escaping check: newline in data, colon/comma in a property.
    Annotation::new()
        .title("type: mismatch, really")
        .error("line one\nline two");

    let total = log::group("expensive step", || {
        log::info("...working...");
        2 + 2
    });
    log::info(format!("group returned {total}"));

    actions_rs::warning!("formatted macro: {} items left", 7);

    output::set_output("answer", 42).expect("set_output");
    match output::export_var("DEMO_FLAG", true) {
        Ok(()) => {}
        Err(actions_rs::Error::UnavailableFileCommand {
            var: "GITHUB_ENV", ..
        }) => {
            log::info("GITHUB_ENV unset; skipping export_var in local demo");
        }
        Err(err) => panic!("export_var: {err}"),
    }

    let mut summary = Summary::new();
    summary
        .heading("Demo Report", 2)
        .raw("Built by the `demo` example.", true)
        .table([
            vec![Cell::header("Check"), Cell::header("Result")],
            vec![Cell::new("clippy"), Cell::new("pass")],
            vec![Cell::new("tests"), Cell::new("36 pass")],
        ])
        .code_block("cargo test", Some("sh"));
    summary.write().expect("write summary");
    log::info("summary written (if GITHUB_STEP_SUMMARY was set)");
}

examples/ci_selfcheck.rs (line 99)

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
}

pub fn list<I, S>(&mut self, items: I, ordered: bool) -> &mut Self

where I: IntoIterator<Item = S>, S: Into<SummaryText>,

Append a <ul> (or <ol> when ordered) of items.

Examples

let mut s = actions_rs::Summary::new();
s.list(["a", "b"], false);
assert_eq!(s.stringify(), "<ul><li>a</li><li>b</li></ul>\n");

pub fn table(&mut self, rows: impl IntoIterator<Item = Vec<Cell>>) -> &mut Self

Append a <table>. Each row is a list of Cells.

Examples

use actions_rs::{Cell, Summary};
let mut s = Summary::new();
s.table([vec![Cell::header("k"), Cell::new("v")]]);
assert_eq!(
    s.stringify(),
    "<table><tr><th colspan=\"1\" rowspan=\"1\">k</th>\
     <td colspan=\"1\" rowspan=\"1\">v</td></tr></table>\n"
);

Examples found in repository

examples/demo.rs (lines 66-70)

fn main() {
    log::info(format!(
        "in GitHub Actions: {} | CI: {} | step-debug: {}",
        env::is_github_actions(),
        env::is_ci(),
        log::is_debug()
    ));

    let ctx = actions_rs::Context::new();
    log::info(format!(
        "repo={:?} ref={:?} sha={:?}",
        ctx.repository(),
        ctx.ref_name(),
        ctx.sha()
    ));

    // Located annotation with a line range — should print:
    // ::warning title=demo,file=src/lib.rs,line=10,endLine=12::heads up
    Annotation::new()
        .file("src/lib.rs")
        .line(10)
        .end_line(12)
        .title("demo")
        .warning("heads up: this span looks suspicious");

    // Escaping check: newline in data, colon/comma in a property.
    Annotation::new()
        .title("type: mismatch, really")
        .error("line one\nline two");

    let total = log::group("expensive step", || {
        log::info("...working...");
        2 + 2
    });
    log::info(format!("group returned {total}"));

    actions_rs::warning!("formatted macro: {} items left", 7);

    output::set_output("answer", 42).expect("set_output");
    match output::export_var("DEMO_FLAG", true) {
        Ok(()) => {}
        Err(actions_rs::Error::UnavailableFileCommand {
            var: "GITHUB_ENV", ..
        }) => {
            log::info("GITHUB_ENV unset; skipping export_var in local demo");
        }
        Err(err) => panic!("export_var: {err}"),
    }

    let mut summary = Summary::new();
    summary
        .heading("Demo Report", 2)
        .raw("Built by the `demo` example.", true)
        .table([
            vec![Cell::header("Check"), Cell::header("Result")],
            vec![Cell::new("clippy"), Cell::new("pass")],
            vec![Cell::new("tests"), Cell::new("36 pass")],
        ])
        .code_block("cargo test", Some("sh"));
    summary.write().expect("write summary");
    log::info("summary written (if GITHUB_STEP_SUMMARY was set)");
}

pub fn details( &mut self, label: impl Into<SummaryText>, content: impl Into<SummaryText>, ) -> &mut Self

Append a <details> block with a <summary> label. Both text nodes are escaped unless you pass SummaryText::html.

Examples

let mut s = actions_rs::Summary::new();
s.details("logs", "all green");
assert_eq!(s.stringify(), "<details><summary>logs</summary>all green</details>\n");

pub fn image( &mut self, src: impl AsRef<str>, alt: impl AsRef<str>, size: Option<(u32, u32)>, ) -> &mut Self

Append an <img>. size is an optional (width, height) in pixels.

Examples

let mut s = actions_rs::Summary::new();
s.image("cov.svg", "coverage", Some((120, 20)));
assert_eq!(
    s.stringify(),
    "<img src=\"cov.svg\" alt=\"coverage\" width=\"120\" height=\"20\">\n"
);

pub fn link( &mut self, text: impl Into<SummaryText>, href: impl AsRef<str>, ) -> &mut Self

Append an <a> link. The link text is escaped unless you pass SummaryText::html; href is always attribute-escaped.

Examples

let mut s = actions_rs::Summary::new();
s.link("run", "https://example.com/run/1");
assert_eq!(s.stringify(), "<a href=\"https://example.com/run/1\">run</a>\n");

pub fn quote( &mut self, text: impl Into<SummaryText>, cite: Option<&str>, ) -> &mut Self

Append a <blockquote> with an optional cite URL. Quote text is escaped unless you pass SummaryText::html.

Examples

let mut s = actions_rs::Summary::new();
s.quote("ship it", None);
assert_eq!(s.stringify(), "<blockquote>ship it</blockquote>\n");

pub fn separator(&mut self) -> &mut Self

Append an <hr>.

Examples

let mut s = actions_rs::Summary::new();
s.separator();
assert_eq!(s.stringify(), "<hr>\n");

pub fn break_(&mut self) -> &mut Self

Append a <br>.

Examples

let mut s = actions_rs::Summary::new();
s.break_();
assert_eq!(s.stringify(), "<br>\n");

pub fn stringify(&self) -> &str

The buffered summary content.

Examples

let mut s = actions_rs::Summary::new();
s.heading("Hi", 1);
assert_eq!(s.stringify(), "<h1>Hi</h1>\n");

pub fn is_empty(&self) -> bool

Whether nothing has been buffered yet.

Examples

let mut s = actions_rs::Summary::new();
assert!(s.is_empty());
s.eol();
assert!(!s.is_empty());

pub fn clear(&mut self) -> &mut Self

Clear the buffer (does not touch the file).

Examples

let mut s = actions_rs::Summary::new();
s.heading("x", 1);
s.clear();
assert!(s.is_empty());

pub fn write(&mut self) -> Result<()>

Append the buffer to the job summary file.

Errors

Error::SummaryTooLarge if the buffer exceeds 1 MiB, or an I/O error.

Examples

let mut s = actions_rs::Summary::new();
s.heading("Build passed", 2);
s.write()?; // appends to $GITHUB_STEP_SUMMARY

Examples found in repository

examples/demo.rs (line 72)

fn main() {
    log::info(format!(
        "in GitHub Actions: {} | CI: {} | step-debug: {}",
        env::is_github_actions(),
        env::is_ci(),
        log::is_debug()
    ));

    let ctx = actions_rs::Context::new();
    log::info(format!(
        "repo={:?} ref={:?} sha={:?}",
        ctx.repository(),
        ctx.ref_name(),
        ctx.sha()
    ));

    // Located annotation with a line range — should print:
    // ::warning title=demo,file=src/lib.rs,line=10,endLine=12::heads up
    Annotation::new()
        .file("src/lib.rs")
        .line(10)
        .end_line(12)
        .title("demo")
        .warning("heads up: this span looks suspicious");

    // Escaping check: newline in data, colon/comma in a property.
    Annotation::new()
        .title("type: mismatch, really")
        .error("line one\nline two");

    let total = log::group("expensive step", || {
        log::info("...working...");
        2 + 2
    });
    log::info(format!("group returned {total}"));

    actions_rs::warning!("formatted macro: {} items left", 7);

    output::set_output("answer", 42).expect("set_output");
    match output::export_var("DEMO_FLAG", true) {
        Ok(()) => {}
        Err(actions_rs::Error::UnavailableFileCommand {
            var: "GITHUB_ENV", ..
        }) => {
            log::info("GITHUB_ENV unset; skipping export_var in local demo");
        }
        Err(err) => panic!("export_var: {err}"),
    }

    let mut summary = Summary::new();
    summary
        .heading("Demo Report", 2)
        .raw("Built by the `demo` example.", true)
        .table([
            vec![Cell::header("Check"), Cell::header("Result")],
            vec![Cell::new("clippy"), Cell::new("pass")],
            vec![Cell::new("tests"), Cell::new("36 pass")],
        ])
        .code_block("cargo test", Some("sh"));
    summary.write().expect("write summary");
    log::info("summary written (if GITHUB_STEP_SUMMARY was set)");
}

pub fn write_overwrite(&mut self) -> Result<()>

Overwrite the job summary file with the buffer.

Errors

Error::SummaryTooLarge if the buffer exceeds 1 MiB, or an I/O error.

Examples

let mut s = actions_rs::Summary::new();
s.heading("Replaces any prior summary", 2);
s.write_overwrite()?;

Examples found in repository

examples/ci_selfcheck.rs (line 100)

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 Summary

fn clone(&self) -> Summary

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Summary

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

Formats the value using the given formatter.

impl Default for Summary

fn default() -> Summary

Returns the “default value” for a type.