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,6 +1,17 @@
 # Unreleased
 
-Nothing Yet!
+## `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"]`.
+
+- impl @arusahni [feat: optionally apply `github-build-setup` steps to additional jobs](https://github.com/axodotdev/cargo-dist/pull/2070)
 
 
 # Version 0.30.2 (2025-10-31)

book/src/reference/config.md

@@ -96,6 +96,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)
@@ -1384,8 +1385,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>,
@@ -364,6 +366,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"),
@@ -412,6 +415,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

@@ -466,10 +466,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)]
@@ -572,6 +576,7 @@ impl DistMetadata {
             package_libraries: _,
             install_libraries: _,
             github_build_setup: _,
+            github_build_setup_jobs: _,
             mac_pkg_config: _,
             min_glibc_version: _,
             binaries: _,
@@ -679,6 +684,7 @@ impl DistMetadata {
             package_libraries,
             install_libraries,
             github_build_setup,
+            github_build_setup_jobs,
             mac_pkg_config,
             min_glibc_version,
             binaries,
@@ -807,6 +813,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.rs

@@ -545,6 +545,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,
@@ -1058,6 +1059,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;
 

cargo-dist/templates/ci/github/partials/build_setup_jobs.yml.j2

@@ -0,0 +1,45 @@
+      {{%- for step in github_build_setup %}}
+      - name: {{{ step.name }}}
+        {{%- if step.id is not undefined %}}
+        id: {{{ step.id }}}
+        {{%- endif %}}
+        {{%- if step.uses is not undefined %}}
+        uses: {{{ step.uses }}}
+        {{%- endif %}}
+        {{%- if step.if is not undefined %}}
+        if: {{{ step.if }}}
+        {{%- endif %}}
+        {{%- if step.run is not undefined %}}
+        {{%- if step.run is multiline %}}
+        run: |
+          {{{ step.run|indent(10) }}}
+        {{%- else %}}
+        run: {{{ step.run }}}
+        {{%- endif %}}
+        {{%- endif %}}
+        {{%- if step.working_directory is not undefined %}}
+        working-directory: {{{ step.working_directory }}}
+        {{%- endif %}}
+        {{%- if step.shell is not undefined %}}
+        shell: {{{ step.shell }}}
+        {{%- endif %}}
+        {{%- if not step.with is empty %}}
+        with:
+          {{%- for (var,value) in step.with|items %}}
+          {{%- if value is mapping %}}
+          {{{ var }}}:
+            {{%- for (var,value) in value|items %}}
+            {{{ var }}}: {{{ value }}}
+            {{%- endfor %}}
+          {{%- else %}}
+          {{{ var }}}: {{{ value }}}
+          {{%- endif %}}
+          {{%- endfor %}}
+        {{%- endif %}}
+        {{%- if not step.env is empty %}}
+        env:
+          {{%- for (var,value) in step.env|items %}}
+          {{{ var }}}: {{{ value }}}
+          {{%- endfor %}}
+        {{%- endif %}}
+      {{%- endfor %}}

cargo-dist/templates/ci/github/release.yml.j2

@@ -128,6 +128,9 @@ jobs:
         with:
           name: cargo-dist-cache
           path: ~/.cargo/bin/dist
+      {{%- if "plan" in github_build_setup_jobs %}}
+{{%- include 'ci/github/partials/build_setup_jobs.yml' %}}
+      {{%- endif %}}
       # sure would be cool if github gave us proper conditionals...
       # so here's a doubly-nested ternary-via-truthiness to try to provide the best possible
       # functionality based on whether this is a pull_request, and whether it's from a fork.
@@ -235,57 +238,9 @@ jobs:
       - name: Use rustup to set correct Rust version
         run: rustup update {{{ rust_version }}} --no-self-update && rustup default {{{ rust_version }}}
       {{%- endif %}}
-      {{%- for step in github_build_setup %}}
-      - name: {{{ step.name }}}
-        {{%- if step.id is not undefined %}}
-        id: {{{ step.id }}}
-        {{%- endif %}}
-        {{%- if step.uses is not undefined %}}
-        uses: {{{ step.uses }}}
-        {{%- endif %}}
-        {{%- if step.if is not undefined %}}
-        if: {{{ step.if }}}
-        {{%- endif %}}
-        {{%- if step.run is not undefined %}}
-        {{%- if step.run is multiline %}}
-        run: |
-          {{{ step.run|indent(10) }}}
-        {{%- else %}}
-        run: {{{ step.run }}}
-        {{%- endif %}}
-        {{%- endif %}}
-        {{%- if step.working_directory is not undefined %}}
-        working-directory: {{{ step.working_directory }}}
-        {{%- endif %}}
-        {{%- if step.shell is not undefined %}}
-        shell: {{{ step.shell }}}
-        {{%- endif %}}
-        {{%- if not step.with is empty %}}
-        with:
-          {{%- for (var,value) in step.with|items %}}
-          {{%- if value is mapping %}}
-          {{{ var }}}:
-            {{%- for (var,value) in value|items %}}
-            {{{ var }}}: {{{ value }}}
-            {{%- endfor %}}
-          {{%- else %}}
-          {{{ var }}}: {{{ value }}}
-          {{%- endif %}}
-          {{%- endfor %}}
-        {{%- endif %}}
-        {{%- if not step.env is empty %}}
-        env:
-          {{%- for (var,value) in step.env|items %}}
-          {{{ var }}}: {{{ value }}}
-          {{%- endfor %}}
-        {{%- endif %}}
-        {{%- if step.continue_on_error is not undefined %}}
-        continue-on-error: {{{ step.continue_on_error }}}
-        {{%- endif %}}
-        {{%- if step.timeout_minutes is not undefined %}}
-        timeout-minutes: {{{ step.timeout_minutes }}}
-        {{%- endif %}}
-      {{%- endfor %}}
+      {{%- if "build-local-artifacts" in github_build_setup_jobs %}}
+{{%- include 'ci/github/partials/build_setup_jobs.yml' %}}
+      {{%- endif %}}
       {{%- if cache_builds %}}
       - uses: {{{actions["swatinem/rust-cache"] | safe }}}
         with:
@@ -421,6 +376,9 @@ jobs:
           pattern: artifacts-*
           path: target/distrib/
           merge-multiple: true
+      {{%- if "build-global-artifacts" in github_build_setup_jobs %}}
+{{%- include 'ci/github/partials/build_setup_jobs.yml' %}}
+      {{%- endif %}}
       - id: cargo-dist
         shell: bash
         run: |
@@ -536,6 +494,9 @@ jobs:
           merge-multiple: true
     {{%- if "github" in hosting_providers and release_phase == "announce" %}}
       # This is a harmless no-op for GitHub Releases, hosting for that happens in "announce"
+    {{%- endif %}}
+    {{%- if "host" in github_build_setup_jobs %}}
+{{%- include 'ci/github/partials/build_setup_jobs.yml' %}}
     {{%- endif %}}
       - id: host
         shell: bash