Struct Annotation 

pub struct Annotation { /* private fields */ }

Fluent builder for a located annotation.

All fields are optional — an empty Annotation simply produces a plain annotation with no location. Build it, then emit with Annotation::notice, Annotation::warning or Annotation::error.

use actions_rs::Annotation;
let cmd = Annotation::new()
    .file("src/lib.rs")
    .line(10)
    .end_line(12)
    .title("clippy")
    .command(actions_rs::AnnotationKind::Warning, "unused variable");
assert_eq!(
    cmd.to_string(),
    "::warning title=clippy,file=src/lib.rs,line=10,endLine=12::unused variable"
);

Implementations

impl Annotation

pub fn new() -> Self

Create an empty annotation (no location, no title).

Examples

use actions_rs::{Annotation, AnnotationKind};
let c = Annotation::new().command(AnnotationKind::Notice, "hi");
assert_eq!(c.to_string(), "::notice::hi");

Examples found in repository

examples/demo.rs (line 31)

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 19)

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 title(self, title: impl Into<String>) -> Self

Set the annotation title shown in the GitHub UI.

Examples

use actions_rs::{Annotation, AnnotationKind};
let c = Annotation::new().title("clippy").command(AnnotationKind::Warning, "w");
assert_eq!(c.to_string(), "::warning title=clippy::w");

Examples found in repository

examples/demo.rs (line 35)

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 25)

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 file(self, file: impl Into<String>) -> Self

Set the file path the annotation refers to (relative to the workspace).

Examples

use actions_rs::{Annotation, AnnotationKind};
let c = Annotation::new().file("src/lib.rs").command(AnnotationKind::Error, "e");
assert_eq!(c.to_string(), "::error file=src/lib.rs::e");

Examples found in repository

examples/demo.rs (line 32)

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 20)

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 line(self, line: u32) -> Self

Set the (1-based) start line.

Examples

use actions_rs::{Annotation, AnnotationKind};
let c = Annotation::new().file("x").line(42).command(AnnotationKind::Warning, "w");
assert_eq!(c.to_string(), "::warning file=x,line=42::w");

Examples found in repository

examples/demo.rs (line 33)

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 end_line(self, end_line: u32) -> Self

Set the (1-based) end line of a multi-line span.

Examples

use actions_rs::{Annotation, AnnotationKind};
let c = Annotation::new().file("x").line(10).end_line(12)
    .command(AnnotationKind::Warning, "w");
assert_eq!(c.to_string(), "::warning file=x,line=10,endLine=12::w");

Examples found in repository

examples/demo.rs (line 34)

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 col(self, col: u32) -> Self

Set the (1-based) start column.

Examples

use actions_rs::{Annotation, AnnotationKind};
let c = Annotation::new().file("x").line(7).col(3)
    .command(AnnotationKind::Warning, "w");
assert_eq!(c.to_string(), "::warning file=x,line=7,col=3,endColumn=3::w");

pub fn end_column(self, end_column: u32) -> Self

Set the (1-based) end column.

Examples

use actions_rs::{Annotation, AnnotationKind};
let c = Annotation::new().file("x").line(7).col(3).end_column(9)
    .command(AnnotationKind::Warning, "w");
assert_eq!(c.to_string(), "::warning file=x,line=7,col=3,endColumn=9::w");

pub fn span(self, span: AnnotationSpan) -> Self

Replace the current location fields with a span that is valid by construction.

Examples

use actions_rs::{Annotation, AnnotationKind, AnnotationSpan};
let c = Annotation::new()
    .span(AnnotationSpan::Line { start: 4, end: Some(6) })
    .command(AnnotationKind::Notice, "block");
assert_eq!(c.to_string(), "::notice line=4,endLine=6::block");

Examples found in repository

examples/ci_selfcheck.rs (lines 21-24)

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 command( &self, kind: AnnotationKind, message: impl Into<String>, ) -> WorkflowCommand

Build the WorkflowCommand for this annotation and message without emitting it. Useful for testing or custom sinks.

Property order matches @actions/core: title, file, line, endLine, col, endColumn.

Examples

use actions_rs::{Annotation, AnnotationKind};
// Inspect the wire form without writing to stdout.
let cmd = Annotation::new().file("a.rs").line(1).command(AnnotationKind::Error, "e");
assert_eq!(cmd.to_string(), "::error file=a.rs,line=1::e");

Examples found in repository

examples/ci_selfcheck.rs (lines 26-29)

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 notice(&self, message: impl Into<String>)

Emit a ::notice:: annotation to stdout.

Examples

use actions_rs::Annotation;
Annotation::new().file("README.md").line(1).notice("looks good");

pub fn warning(&self, message: impl Into<String>)

Emit a ::warning:: annotation to stdout.

Examples

use actions_rs::Annotation;
Annotation::new().file("src/lib.rs").line(42).title("lint").warning("unused import");

Examples found in repository

examples/demo.rs (line 36)

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 error(&self, message: impl Into<String>)

Emit an ::error:: annotation to stdout.

Examples

use actions_rs::Annotation;
Annotation::new().file("src/main.rs").line(7).error("type mismatch");

Examples found in repository

examples/demo.rs (line 41)

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)");
}

Trait Implementations

impl Clone for Annotation

fn clone(&self) -> Annotation

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Annotation

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

Formats the value using the given formatter.

impl Default for Annotation

fn default() -> Annotation

Returns the “default value” for a type.

impl PartialEq for Annotation

fn eq(&self, other: &Annotation) -> 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 Annotation

impl StructuralPartialEq for Annotation