feat: optionally apply github-build-setup steps to additional jobs.

For some use cases, such as using private Git crate dependencies in a
project's Cargo.toml manifest, Github Actions requires a certain amount
of ceremony to alias the private repo's Git URL to to something that can
be cloned using an access token. For the `build-local-artifacts` job,
this can be accomplished by adding the authentication step in the
`github-build-setup` YML file.

There are additional jobs that necessitate these credentials be set,
mainly the `plan`, `build-global-artifacts`, and `host`. This
appears to be due to the fact they invoke `cargo metadata` (which
attempts to pull dependencies).

Support these use-cases by introducing a `github-build-setup-jobs` collection
which allows users to opt-in to including the `github-build-setup`
steps in various jobs.

Fixes #2065

Author: arusahni

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Unreleased
 
+## `github-build-setup` Job Customization
+
+It's now possible to specify to which jobs `github-build-setup` steps are added.
+
+```toml
+github-build-setup = "build-steps.yml"
+github-build-setup-jobs = ["plan", "build-local-artifacts", "build-global-artifacts", "host"]
+```
+
+If not configured, this defaults to `build-local-artifacts`.
+
 # Version 0.30.0 (2025-09-07)
 
 This release contains several improvements to ZIP archives, the installers and additional build workflow customization options.

book/src/reference/config.md

@@ -95,6 +95,7 @@ We're currently in the middle of [a major config migration](https://github.com/a
     * [`github-custom-job-permissions`](#github-custom-job-permissions)
     * [`github-custom-runners`](#github-custom-runners)
     * [`github-build-setup`](#github-build-setup)
+    * [`github-build-setup-jobs`](#github-build-setup-jobs)
     * [`github-action-commits`](#github-action-commits)
 * [custom ci jobs](#custom-ci-jobs)
     * [`plan-jobs`](#plan-jobs)
@@ -1382,8 +1383,28 @@ These settings are specific to [your dist GitHub CI][github-ci].
 
 This configuration value should be a path relative to the repository your `.github/workflows` directory.
 The file located at that path should contain a yaml array of [steps][github-workflow-step] which will be
-performed before we call `dist build`.
+performed before we call `dist build` in the `build-local-artifacts` job. These
+steps can be added to additional jobs by defining
+[`github-build-setup-jobs`](#github-build-setup-jobs).
 
+#### `github-build-setup-jobs`
+
+> <span style="float:right">since 1.0.0<br>[global-only][]</span>
+> 🔧 this is an experimental feature! \
+> [📖 read the ci customization guide!][github-ci] \
+> default = `<none>`
+>
+> *in your dist-workspace.toml or dist.toml:*
+> ```toml
+> [dist]
+> # Defaults to "build-local-artifacts"
+> github-build-setup-jobs = ["plan", "build-local-artifacts"]
+> ```
+
+This configuration value should accompany
+[`github-build-setup`](#github-build-setup). When not specified, it defaults to
+`["build-local-artifacts"]`. Otherwise, the listed jobs will have the steps
+defined in `github-build-setup` added.
 
 #### `github-custom-job-permissions`
 

cargo-dist/src/backend/ci/github.rs

@@ -100,6 +100,8 @@ pub struct GithubCiInfo {
     pub root_permissions: Option<GithubPermissionMap>,
     /// Extra build steps
     pub github_build_setup: Vec<GithubJobStep>,
+    /// The jobs to which the [`GithubCiInfo::github_build_setup`] steps should be prepended
+    pub github_build_setup_jobs: Vec<String>,
     /// Info about making a GitHub Release (if we're making one)
     #[serde(flatten)]
     pub github_release: Option<GithubReleaseInfo>,
@@ -372,6 +374,7 @@ impl GithubCiInfo {
             })
             .transpose()?
             .unwrap_or_default();
+        let github_build_setup_jobs = ci_config.build_setup_jobs.clone();
 
         let default_action_versions = [
             ("actions/checkout", "v4"),
@@ -420,6 +423,7 @@ impl GithubCiInfo {
             hosting_providers,
             root_permissions,
             github_build_setup,
+            github_build_setup_jobs,
             github_release,
             actions,
             need_cargo_auditable,

cargo-dist/src/config/v0.rs

@@ -539,10 +539,14 @@ pub struct DistMetadata {
     #[serde(default, with = "opt_string_or_vec")]
     pub install_libraries: Option<Vec<LibraryStyle>>,
 
-    /// Any additional steps that need to be performed before building local artifacts
+    /// Any additional steps that need to be performed before executing certain job steps
     #[serde(default)]
     pub github_build_setup: Option<String>,
 
+    /// The jobs to which the [`DistMetadata::github_build_setup`] steps should be prepended
+    #[serde(default)]
+    pub github_build_setup_jobs: Option<Vec<String>>,
+
     /// Configuration specific to Mac .pkg installers
     #[serde(skip_serializing_if = "Option::is_none")]
     #[serde(default)]
@@ -645,6 +649,7 @@ impl DistMetadata {
             package_libraries: _,
             install_libraries: _,
             github_build_setup: _,
+            github_build_setup_jobs: _,
             mac_pkg_config: _,
             min_glibc_version: _,
             binaries: _,
@@ -752,6 +757,7 @@ impl DistMetadata {
             package_libraries,
             install_libraries,
             github_build_setup,
+            github_build_setup_jobs,
             mac_pkg_config,
             min_glibc_version,
             binaries,
@@ -880,6 +886,9 @@ impl DistMetadata {
         if github_build_setup.is_some() {
             warn!("package.metadata.dist.github-build-setup is set, but this is only accepted in workspace.metadata (value is being ignored): {}", package_manifest_path);
         }
+        if github_build_setup_jobs.is_some() {
+            warn!("package.metadata.dist.github-build-setup-jobs is set, but this is only accepted in workspace.metadata (value is being ignored): {}", package_manifest_path);
+        }
 
         // Merge non-global settings
         if installers.is_none() {

cargo-dist/src/config/v0_to_v1.rs

@@ -88,6 +88,7 @@ impl DistMetadata {
             package_libraries,
             install_libraries,
             github_build_setup,
+            github_build_setup_jobs,
             min_glibc_version,
             binaries,
             cargo_auditable,
@@ -165,13 +166,15 @@ impl DistMetadata {
             if github_custom_runners.is_some()
                 || github_custom_job_permissions.is_some()
                 || github_build_setup.is_some()
+                || github_build_setup_jobs.is_some()
                 || github_action_commits.is_some()
             {
                 Some(GithubCiLayer {
                     common: CommonCiLayer::default(),
                     runners: github_custom_runners,
                     permissions: github_custom_job_permissions,
                     build_setup: github_build_setup,
+                    build_setup_jobs: github_build_setup_jobs,
                     action_commits: github_action_commits,
                 })
             } else {

cargo-dist/src/config/v1/ci/github.rs

@@ -25,10 +25,14 @@ pub struct GithubCiLayer {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub permissions: Option<SortedMap<String, GithubPermissionMap>>,
 
-    /// Custom permissions for jobs
+    /// Custom steps for jobs
     #[serde(skip_serializing_if = "Option::is_none")]
     pub build_setup: Option<String>,
 
+    /// What jobs to which the [`GithubCiLayer::build_setup`] steps should be prepended
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub build_setup_jobs: Option<Vec<String>>,
+
     /// Use these commits for actions
     #[serde(skip_serializing_if = "Option::is_none")]
     pub action_commits: Option<SortedMap<String, String>>,
@@ -46,9 +50,12 @@ pub struct GithubCiConfig {
     /// Custom permissions for jobs
     pub permissions: SortedMap<String, GithubPermissionMap>,
 
-    /// Custom permissions for jobs
+    /// Custom steps for jobs
     pub build_setup: Option<String>,
 
+    /// What jobs to which the [`GithubCiConfig::build_setup`] steps should be prepended
+    pub build_setup_jobs: Vec<String>,
+
     /// Use these commits for github actions
     pub action_commits: SortedMap<String, String>,
 }
@@ -62,6 +69,7 @@ impl GithubCiConfig {
             permissions: Default::default(),
             action_commits: Default::default(),
             build_setup: None,
+            build_setup_jobs: vec!["build-local-artifacts".to_string()],
         }
     }
 }
@@ -75,6 +83,7 @@ impl ApplyLayer for GithubCiConfig {
             runners,
             permissions,
             build_setup,
+            build_setup_jobs,
             action_commits,
         }: Self::Layer,
     ) {
@@ -143,6 +152,7 @@ impl ApplyLayer for GithubCiConfig {
         }));
         self.permissions.apply_val(permissions);
         self.build_setup.apply_opt(build_setup);
+        self.build_setup_jobs.apply_val(build_setup_jobs);
         self.action_commits.apply_val(action_commits);
     }
 }
@@ -155,13 +165,15 @@ impl ApplyLayer for GithubCiLayer {
             runners,
             permissions,
             build_setup,
+            build_setup_jobs,
             action_commits,
         }: Self::Layer,
     ) {
         self.common.apply_layer(common);
         self.runners.apply_opt(runners);
         self.permissions.apply_opt(permissions);
         self.build_setup.apply_opt(build_setup);
+        self.build_setup_jobs.apply_opt(build_setup_jobs);
         self.action_commits.apply_opt(action_commits);
     }
 }

cargo-dist/src/init/v0.rs

@@ -252,6 +252,7 @@ fn get_new_dist_metadata(
             package_libraries: None,
             install_libraries: None,
             github_build_setup: None,
+            github_build_setup_jobs: None,
             mac_pkg_config: None,
             min_glibc_version: None,
             binaries: None,
@@ -765,6 +766,7 @@ fn apply_dist_to_metadata(metadata: &mut toml_edit::Item, meta: &DistMetadata) {
         bin_aliases: _,
         system_dependencies: _,
         github_build_setup: _,
+        github_build_setup_jobs: _,
         binaries: _,
     } = &meta;