Rollup merge of rust-lang#136911 - Kobzol:ci-helper-link, r=marcoieni

Add documentation URL to selected jobs

This PR adds the possibility to attach URLs to selected CI jobs, which are then printed at the end of the CI log when a failure happens in that job. The motivation is to allow contributors to find how to fix the specific jobs more quickly.

This was proposed on [Zulip](https://rust-lang.zulipchat.com/#narrow/channel/242791-t-infra/topic/Automatic.20useful.20links.20when.20a.20particular.20CI.20job.20fails.3F).

An example output can be seen [here](https://github.com/rust-lang/rust/actions/runs/13836290091/job/38712112523?pr=136911).

r? `@ghost`

Author: jhpratt

.github/workflows/ci.yml

@@ -68,6 +68,7 @@ jobs:
     timeout-minutes: 360
     env:
       CI_JOB_NAME: ${{ matrix.name }}
+      CI_JOB_DOC_URL: ${{ matrix.doc_url }}
       CARGO_REGISTRIES_CRATES_IO_PROTOCOL: sparse
       # commit of PR sha or commit sha. `GITHUB_SHA` is not accurate for PRs.
       HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
@@ -190,8 +191,20 @@ jobs:
           CARGO_INCREMENTAL=0 CARGO_TARGET_DIR=../../../build/citool cargo build
 
       - name: run the build
-        # Redirect stderr to stdout to avoid reordering the two streams in the GHA logs.
-        run: src/ci/scripts/run-build-from-ci.sh 2>&1
+        run: |
+          set +e
+          # Redirect stderr to stdout to avoid reordering the two streams in the GHA logs.
+          src/ci/scripts/run-build-from-ci.sh 2>&1
+          STATUS=$?
+          set -e
+
+          if [[ "$STATUS" -ne 0 && -n "$CI_JOB_DOC_URL" ]]; then
+            echo "****************************************************************************"
+            echo "To find more information about this job, visit the following URL:"
+            echo "$CI_JOB_DOC_URL"
+            echo "****************************************************************************"
+          fi
+          exit ${STATUS}
         env:
           AWS_ACCESS_KEY_ID: ${{ env.CACHES_AWS_ACCESS_KEY_ID }}
           AWS_SECRET_ACCESS_KEY: ${{ secrets[format('AWS_SECRET_ACCESS_KEY_{0}', env.CACHES_AWS_ACCESS_KEY_ID)] }}

src/ci/citool/src/jobs.rs

@@ -24,6 +24,8 @@ pub struct Job {
     /// Free additional disk space in the job, by removing unused packages.
     #[serde(default)]
     pub free_disk: Option<bool>,
+    /// Documentation link to a resource that could help people debug this CI job.
+    pub doc_url: Option<String>,
 }
 
 impl Job {
@@ -103,6 +105,8 @@ struct GithubActionsJob {
     continue_on_error: Option<bool>,
     #[serde(skip_serializing_if = "Option::is_none")]
     free_disk: Option<bool>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    doc_url: Option<String>,
 }
 
 /// Skip CI jobs that are not supposed to be executed on the given `channel`.
@@ -188,6 +192,7 @@ fn calculate_jobs(
                 env,
                 continue_on_error: job.continue_on_error,
                 free_disk: job.free_disk,
+                doc_url: job.doc_url,
             }
         })
         .collect();

src/ci/citool/tests/jobs.rs

@@ -40,7 +40,7 @@ try-job: dist-i686-msvc"#,
 fn pr_jobs() {
     let stdout = get_matrix("pull_request", "commit", "refs/heads/pr/1234");
     insta::assert_snapshot!(stdout, @r#"
-    jobs=[{"name":"mingw-check","full_name":"PR - mingw-check","os":"ubuntu-24.04","env":{"PR_CI_JOB":1},"free_disk":true},{"name":"mingw-check-tidy","full_name":"PR - mingw-check-tidy","os":"ubuntu-24.04","env":{"PR_CI_JOB":1},"continue_on_error":true,"free_disk":true}]
+    jobs=[{"name":"mingw-check","full_name":"PR - mingw-check","os":"ubuntu-24.04","env":{"PR_CI_JOB":1},"free_disk":true},{"name":"mingw-check-tidy","full_name":"PR - mingw-check-tidy","os":"ubuntu-24.04","env":{"PR_CI_JOB":1},"continue_on_error":true,"free_disk":true,"doc_url":"https://foo.bar"}]
     run_type=pr
     "#);
 }

src/ci/citool/tests/test-jobs.yml

@@ -75,6 +75,7 @@ pr:
     <<: *job-linux-4c
   - name: mingw-check-tidy
     continue_on_error: true
+    doc_url: https://foo.bar
     <<: *job-linux-4c
 
 # Jobs that run when you perform a try build (@bors try)

src/ci/github-actions/jobs.yml

@@ -267,11 +267,13 @@ auto:
     # nightly features to compile, and this job would fail if
     # executed on beta and stable.
     only_on_channel: nightly
+    doc_url: https://rustc-dev-guide.rust-lang.org/tests/fuchsia.html
     <<: *job-linux-8c
 
   # Tests integration with Rust for Linux.
   # Builds stage 1 compiler and tries to compile a few RfL examples with it.
   - name: x86_64-rust-for-linux
+    doc_url: https://rustc-dev-guide.rust-lang.org/tests/rust-for-linux.html
     <<: *job-linux-4c
 
   - name: x86_64-gnu

src/ci/run.sh

@@ -6,6 +6,10 @@ if [ -n "$CI_JOB_NAME" ]; then
   echo "[CI_JOB_NAME=$CI_JOB_NAME]"
 fi
 
+if [ -n "$CI_JOB_DOC_URL" ]; then
+  echo "[CI_JOB_DOC_URL=$CI_JOB_DOC_URL]"
+fi
+
 if [ "$NO_CHANGE_USER" = "" ]; then
   if [ "$LOCAL_USER_ID" != "" ]; then
     id -u user &>/dev/null || useradd --shell /bin/bash -u $LOCAL_USER_ID -o -c "" -m user