✅ Deploy Preview for zarf-docs ready!

Name	Link
🔨 Latest commit	a4cee81
🔍 Latest deploy log	https://app.netlify.com/projects/zarf-docs/deploys/68a39dd6e12b780008821abb
😎 Deploy Preview	https://deploy-preview-4035--zarf-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

Codecov Report

✅ All modified and coverable lines are covered by tests.

Two more questions? Does this create a tag that sdk users will be able to consume? What will the UI look like for releases. When someone opens up the main repo page will they see the nightly or most recent regular release in this block? I'd assume the latter, but just want to double check.

Two more questions? Does this create a tag that sdk users will be able to consume?

This may be a gap to be honest. The tag is re-used - so it indeed can be used. But this would not be the advisable method as opposed to using commit sha's directly.

What will the UI look like for releases. When someone opens up the main repo page will they see the nightly or most recent regular release in this block? I'd assume the latter, but just want to double check.

The nightly should be marked as a pre-release and thus the latest will still be the primary release when opening the repository on the web.

I added a What does this look like? section to the PR description above.

I would prefer nightly tags are not the default option for the agent and init shown by github here https://github.com/zarf-dev/zarf/pkgs/container/packages%2Finit, but I don't think that's possible to configure, and it's necessary to publish them for true nightly builds imo. Most users will not check that repo anyway.

The one worry I do have for these cases is how they will affect renovate or dependabot updates? Will those tools skip them because there is a nightly? Looking at repo1/ironbank I think so, given that it looks at the github releases https://repo1.dso.mil/dsop/opensource/zarf-dev/zarf/zarf-agent/-/blob/development/renovate.json?ref_type=heads, so I would assume it doesn't include pre-release. However, if a user was to instead use renovate on the init package or images, they might get a renovate / dependabot PR every night

I would prefer nightly tags are not the default option for the agent and init shown by github here https://github.com/zarf-dev/zarf/pkgs/container/packages%2Finit, but I don't think that's possible to configure, and it's necessary to publish them for true nightly builds imo. Most users will not check that repo anyway.

This is certainly a tradeoff for the process.

The one worry I do have for these cases is how they will affect renovate or dependabot updates? Will those tools skip them because there is a nightly? Looking at repo1/ironbank I think so, given that it looks at the github releases https://repo1.dso.mil/dsop/opensource/zarf-dev/zarf/zarf-agent/-/blob/development/renovate.json?ref_type=heads, so I would assume it doesn't include pre-release. However, if a user was to instead use renovate on the init package or images, they might get a renovate / dependabot PR every night

The answer should be no - these updates will not affect renovate/dependabot. Both treat a suffix such as -nightly as a Semantic-Versioning pre-release label. Their default behaviour is to ignore pre-release versions unless the project is already pinned to a pre-release of the same series or you explicitly opt-in to them.

This does raise a question for whether we want to be able to debug potentially older nightly releases - IE to identify when some regression might have occurred (current implementation). Or whether we focus on a static nightly tag which can reduce how many items we see in the packages pages. I'll take a look at that strategy.

Gotcha, and from what I can gather currently the agent would have a nightly tag and be replaced each night while the init package would have a unique tag since the init package version and zarf version and tightly coupled. Zarf itself is coupled to the init package given that the init process references component names, so I don't think we're yet in a position to break that coupling. We could make the CLI version nightly, though then knowing which nightly you have is more difficult to determine. So tradeoffs here on both sides, and I can see an argument for either decision.

Mapping this out:

flowchart TD
  %% -------- Repo gating (fork safety) --------
  subgraph RepoGuard
    RG0["env.UPSTREAM_REPO = <code>zarf-dev/zarf</code>"] --> RG1{"github.repository == env.UPSTREAM_REPO?"}
    RG1 -- No --> RGX["Skip all jobs"]
    RG1 -- Yes --> BuildAndPublish
  end

  %% -------- Build & Publish path --------
  subgraph BuildAndPublish
    A["Checkout<br/>(fetch-depth: 0, tags available)"] --> B["Compute <b>CLI_VERSION</b><br/>&bull; Find highest semver tag (preserve 'v')<br/>&bull; incpatch + <code>-nightly</code><br/>e.g., <code>v0.60.0</code> → <code>v0.60.1-nightly</code>"]
    B --> C["Build CLI with <b>CLI_VERSION</b>"]
    C --> D["Build Agent Image"]
    D --> E["Push to GHCR<br/><code>ghcr.io/zarf-dev/zarf/agent:<b>CLI_VERSION</b></code>"]
    E --> F["Inspect image and capture digest"]
    F --> G["Cosign sign by digest<br/>annotation <code>version=<b>CLI_VERSION</b></code>"]
    G --> H["Build init packages<br/><code>AGENT_IMAGE_TAG=<b>CLI_VERSION</b></code>"]
    H --> I["Publish init packages (OCI + skeleton)<br/>uses <b>CLI_VERSION</b>"]
    I --> J["Upload build artifacts"]
    I --> R["Native use:<br/>&bull; <code>zarf init</code><br/>&bull; <code>zarf tools download-init</code><br/>(uses <b>CLI_VERSION</b>)"]
  end

  %% -------- Validate path --------
  subgraph Validate
    J --> V1["Download artifacts"]
    V1 --> V2["Run e2e tests<br/>(<code>CLI_VERSION</code>, appliance mode)"]
    V2 --> V3["Save logs (always)"]
  end

  %% -------- Release with GoReleaser --------
  subgraph ReleaseWithGoReleaser
    J --> GR1["GoReleaser (Pro) <code>--nightly</code>"]
    GR1 --> GR2["Env: <code>GORELEASER_CURRENT_TAG=<b>CLI_VERSION</b></code>"]
    GR2 --> GR3["<code>.Version</code>/<code>.Tag</code> resolve to <b>CLI_VERSION</b> in config"]
    GR3 --> GR4["Produce nightly release artifacts for <b>CLI_VERSION</b>"]
  end

That map checks out, and I believe presents a good solution. To make sure I understand this correctly, this will produce a tag in the git repository v0.60.1-nightly, however the value of the Zarf CLI CLIVersion variable for that nightly will be v0.60.1-<commit-hash>-nightly?

That map checks out, and I believe presents a good solution. To make sure I understand this correctly, this will produce a tag in the git repository v0.60.1-nightly, however the value of the Zarf CLI CLIVersion variable for that nightly will be v0.60.1-<commit-hash>-nightly?

As it stands currently:
git tag = nightly - never changes
CLIVersion = <semver-patch+1>-<commit-hash>-nightly (CLI and zarf init package tagged accordingly)
Release Name = <semver-patch+1>-nightly

I am considering removing the commit hash. So that it reduces the sprawl down to:
git tag = nighty (keeps this from being noisy during search)
release name / CLI Version = <semver-patch+1>-nightly

So if current version is v0.60.0 then the current nightly will be v0.60.1-nightly. I don't believe we need the commit hash versioning. If the nightly fails we should be responding promptly.

Thoughts?

Ah gotcha, I was missing the differentiation between git tag and release name.

Yeah, I think the latter strategy would make sense, I like starting simpler and adding more if we need it.

Updated the mermaid diagram and the PR description to reflect the latter strategy.