Artifacts in Bitbucket Pipelines serve as the connective tissue between the steps of a pipeline. They are the files a team chooses to upload during execution so that downstream stages can retrieve them for testing, packaging or release. In practice, artifacts often include build outputs such as compiled binaries, archives, and coverage results, as well as diagnostic files used to validate quality gates. When artifacts are modeled well, they make workloads more deterministic because every step receives only what it needs in a predictable structure. When they are modeled poorly, teams download everything by default, wasting build minutes and creating brittle chains that slow the delivery loop. That is why changes to artifact behavior have an outsized impact on performance and clarity across CI and CD workflows.
Atlassian introduced two upgrades that aim to refine how teams define and consume artifacts across steps. The first upgrade adds new artifact types that give teams fine grained control over what can be shared across steps and what remains scoped to the current context. The second upgrade adds selective download, which lets a step declare whether it needs every prior artifact, none at all, or only a curated subset. Together, these capabilities reduce unnecessary transfers, cut pipeline time, and promote clearer patterns of ownership. As teams adopt more granular pipelines, these controls become essential to keeping costs predictable and language neutral across complex projects. The result is cleaner handoffs, more reliable logs, and fewer surprises during both routine and peak workloads, which is especially valuable in multi step delivery lines that run many times per day.
New artifact types give you two modes for publishing and consuming files across steps. Shared artifacts are intended for cross step use and can be downloaded by subsequent stages. Scoped artifacts are confined to the producing step and are not available to other steps. This distinction eliminates accidental sharing of step specific files and helps align artifact design with intention.
Selective download allows each step to choose which artifacts to retrieve. A step can download everything from earlier steps, download nothing, or download only specific artifact names. This controls bandwidth and processing time for steps that do not need a full set of outputs. It also reinforces the habit of explicit dependencies rather than implicit ones that accumulate over time. The net effect is leaner pipelines and faster feedback cycles without sacrificing traceability or reproducibility when that is needed.
Shared artifacts are the files a team expects to hand off across steps, such as packaged applications or assets destined for deployment. By design, they remain available to subsequent steps that opt to download them, which makes them appropriate for cross stage dependencies. When a pipeline is organized around shared artifacts, concerns become clearer because producers publish consistent outputs and consumers request exactly what they need. This approach is particularly helpful when multiple jobs converge on a later stage that needs a common input. Structured naming further reinforces their purpose and makes it simpler to audit which steps are consuming which assets over time.
An advantage of shared artifacts is predictability across branches and environments. When the same artifact name and path conventions are used, steps do not need to rediscover how to locate inputs, which reduces the maintenance burden as pipelines evolve. Teams can also group multiple path patterns under a single shared artifact name, which cuts down the total number of artifacts created and simplifies search for operators and developers. This grouping capability supports cleaner user interfaces and avoids clutter that grows as projects scale. It also aligns with the principle of explicit contracts between steps, which is foundational in resilient CI and CD designs.
Scoped artifacts are limited to the step where they are created. They are not downloaded by other steps, which means they are ideal for files that only matter in context. Common examples include log files, test reports, and screenshots produced during validation, where the primary consumer is a human reviewing the step’s output. By scoping these items to the producing step, teams avoid paying the cost of transferring and indexing them in downstream stages. That reduction is non trivial because pipelines can generate hundreds of megabytes of diagnostics during intense test passes.
The scoping boundary also improves security posture and isolation. Sensitive files like internal reports or ephemeral credentials should not be fetched by later steps unless there is a strong reason to do so. With scoped artifacts, avoiding unintentional exposure becomes easier because the default behavior enforces locality. This pairs well with minimal permission strategies and supports compliance goals by ensuring that only designated files are shared. The feature encourages teams to publish only what they truly intend to share, while still retaining step level observability through scope limited outputs that remain easy to inspect where they originate.
Shared and scoped artifacts differ along two axes, accessibility and purpose. Shared artifacts are intended to flow forward across steps. Scoped artifacts are intentionally bound to the producing step and never cross that boundary. From a design standpoint, shared artifacts support reproducible builds and releases because they capture final or intermediate deliverables meant for broad consumption. Scoped artifacts support introspection, root cause analysis, and metrics, without creating unwanted coupling between steps.
The ability to set ignore patterns and search depth further distinguishes how teams can organize each type. Grouping multiple patterns under a single artifact and excluding noise files reduce path sprawl and accelerate discovery for operators. As pipelines grow, these controls translate into better naming hygiene and fewer artifacts overall, which help keep the artifact interface sustainable. The combination of type controls and grouping features leads to a cleaner interface in the artifacts UI and faster interactions in both manual and automated consumption paths. These practices reinforce a separation of concerns while aligning with cost and performance goals at scale.
Shared and scoped artifacts use the same storage window, so teams do not need to memorize different retention values for different types. The current retention period for both is fourteen days, which provides a practical window for investigation and reruns while keeping storage predictable. This period supports common recovery needs without encouraging indefinite retention of transient files. It also aligns with faster iteration cycles where artifacts are regenerated frequently and should not linger beyond their useful life. Teams can rely on that uniform policy as they adapt pipelines to use these new types, which reduces onboarding time for contributors and operators alike.
Another key operational limit is size. Each artifact is limited to one gigabyte, regardless of type. This cap incentivizes the practice of producing right sized artifacts. It also guards against a single artifact causing prolonged transfer times during selective download. Teams that need to move larger payloads should split them into logical bundles rather than a single monolith. The combination of shared limits and type semantics creates a predictable operating model for storage, access, and lifecycle management across projects of varying complexity.
By separating shared and scoped artifacts, the platform now encodes step isolation directly into artifact behavior. Steps can publish internal only diagnostics without risk that later stages will inherit them. Conversely, steps that depend on a published deliverable can confidently request a shared artifact by name, reducing ambiguity in dependencies. This encoded contract makes pipelines easier to reason about, which saves time during onboarding and troubleshooting. It also curtails accidental tight coupling across stages, a common source of fragility in large delivery lines.
Selective download amplifies the isolation benefits by letting each step document its precise needs. Instead of defaulting to fetch everything, a step can express zero or minimal dependencies. Over time, this precision reduces cross step entanglement and fosters incremental refactors to more modular designs. The practical outcome is a pipeline that remains both fast and transparent, with well lit boundaries and intentional communication between steps. That translates into better cost control and fewer incidental regressions in teams that ship frequently under time pressure.
Below is a concise reference that distinguishes the two artifact types and their operational characteristics.
|
Attribute |
Shared artifacts |
Scoped artifacts |
|---|---|---|
|
Cross step accessibility |
Yes |
No |
|
Typical purpose |
Deliverables and assets for subsequent stages |
Logs, test reports, screenshots, diagnostics |
|
Retention policy |
Fourteen days |
Fourteen days |
|
Size limit |
One gigabyte per artifact |
One gigabyte per artifact |
|
Risk of accidental coupling |
Moderate if overused |
Low due to step scoping |
|
Best fit |
Packaging, publish, deploy, multi step workflows |
Local observability, troubleshooting, human review |
All attributes and limits reflect the current behavior described in the official announcement.
Selective download introduces an explicit control for artifact retrieval at the step level. Instead of downloading all artifacts by default, a step can choose a mode that matches its needs. The step can accept all available artifacts from earlier stages, decline to download any, or list the exact names it wants to fetch. This explicit choice makes dependencies self documenting, since anyone reading the configuration can infer what the step requires to run. Over time, this clarity translates to fewer surprises when refactoring or reordering jobs, which prevents outages that arise from implicit assumptions. The practical value becomes more apparent in longer workflows. Many steps do not need the full set of outputs from every preceding job, and downloading them would only consume time and bandwidth. By tailoring downloads to the strict subset that matters, teams reduce the surface area of each step, which helps with cache efficiency and promotes snappier feedback. This pattern encourages pipelines that scale predictably as projects add more tests, more builds, and more publish stages. It also complements the new artifact types by reinforcing that only shared artifacts should be consumed across steps in the first place.
There are three intuitive retrieval choices available to every step. The step can declare that it wants every prior artifact. The step can declare that it wants none of them. Or the step can list particular artifact names that it will download. The named list approach is ideal when a step depends on only a couple of outputs and should ignore everything else from other parts of the workflow. The all or none modes are helpful for steps that either fully validate earlier work or operate entirely in isolation.
Alongside the selection mode, teams can refine how artifacts are shaped and grouped at upload time. Multiple file patterns can be organized into one named artifact, which keeps retrieval decisions simple for later steps that express a dependency on a single name. Teams can also define ignore patterns and search depth on new artifact types, which cuts down noise files and produces cleaner bundles. These tools make it easier to establish a small set of canonical artifact names in a repository. When those names align with domain concepts, readers immediately understand what each bundle represents and why a step would request it by name.
Selective download saves time and build minutes by reducing unnecessary transfers. Even modest pipelines can waste significant time fetching and unpacking artifacts that are not needed. By declaring only the precise items a step needs, teams reduce wall clock time for most runs. The impact compounds at scale because pipelines often execute many times per day across multiple branches. That means small per run savings roll up into meaningful capacity gains and budget relief.
The approach also contributes to better troubleshooting and governance. When a step fails, investigators can quickly inspect the declared artifact dependencies and rule out unrelated inputs. This level of transparency makes it easier to adjust the pipeline safely, because owners can change one step without causing accidental regressions in others. Finally, resource consumption becomes more predictable, which is vital in environments with quotas and multi tenant runners. Teams gain a faster, cleaner, and more resilient artifact flow that remains understandable as the system evolves.
Saves build minutes by reducing unnecessary downloads. Scoped artifacts stop step specific files from traveling to later stages, which prevents wasted time spent transferring logs and screenshots. Selective download ensures that steps only fetch the few shared artifacts they require. Taken together, these behaviors keep pipelines lean and responsive under load. Teams can reallocate the recovered time to higher value jobs and improve throughput during peak activity windows.
Improves artifact organization through flexible grouping. Multiple file patterns can be captured under a single artifact name, cutting down on the clutter that typically accumulates in artifact lists. Ignore patterns and configurable search depth provide additional control to eliminate noise. These options help teams define consistent bundles that map to the domain language of their projects. With fewer, clearer artifacts, both humans and automation can locate the right files faster and with less confusion.
Enhances control over creation and retention. Teams can decide when to publish certain artifacts based on the state of the step, which removes overhead when the results are not needed. Uniform retention across types keeps lifecycle management straightforward, with a fourteen day window to support investigations and reruns. A single size cap per artifact encourages right sized bundles that do not stall downstream consumers. These guardrails support predictable performance and storage utilization in a simple, easy to learn model. The result is a healthier pipeline where artifacts remain a help rather than a hindrance as complexity grows.
Retention period. Shared and scoped artifacts are stored for fourteen days. This aligns with typical investigation windows and routine reruns, and it avoids long term accumulation of transient data that raises costs and complicates compliance. The uniformity of the policy removes cognitive overhead for teams working across many repositories. It also contributes to a consistent operational rhythm for maintenance and cleanup activities.
Size limits. Each artifact is limited to one gigabyte. This limit reinforces the practice of composing logical bundles that match the needs of consumers. It prevents single artifacts from overwhelming network and storage resources during high frequency runs. When larger payloads are unavoidable, teams should split them into separate artifacts that reflect clear boundaries. This approach simplifies governance and improves the chances of successful retries when errors occur.
UI changes. Artifacts created using the legacy syntax appear in the User section of the artifacts interface. This separation helps teams identify which artifacts are produced through the new model and which come from earlier definitions. The distinction reduces confusion when browsing and supports incremental migration strategies. Teams can validate the new approach step by step while preserving visibility into previously published outputs. Over time, this clarity encourages standardization on the improved artifact model at scale across teams and projects.
Self hosted runner requirements. To use the new artifact types on self hosted runners, teams should run a version later than v3.31.0. Adopting an appropriate runner version ensures full compatibility with selective download and artifact type semantics. This also reduces friction during rollout because step behavior will match what is documented and expected. Administrators should include this check in their upgrade plans to avoid silent mismatches that create hard to trace failures. Keeping runners current is a simple and effective way to guarantee that the new features work as designed across the fleet.
Steps to adopt the new features in your pipelines. Start by identifying the outputs in your current pipeline that are meant to be shared and those that are meant only for local inspection. Define shared artifacts for the deliverables that downstream steps must consume and define scoped artifacts for logs and diagnostic files that should not cross steps. Next, review each step and declare a selective download policy. For many steps, downloading nothing or only one or two named artifacts will be sufficient and will reduce unnecessary transfers. Finally, document the canonical artifact names so that teams can reference them consistently during step creation and review.
Engage with the community and share feedback. Once the new patterns are in place, monitor pipeline duration, artifact sizes, and the number of artifacts consumed per step. Use these insights to refine grouping strategies and prune any bundles that no longer serve a clear purpose. If questions arise, consult the Pipelines community space to learn how others are applying the model and what practices are working. Collaboration accelerates learning and helps avoid pitfalls that others have already solved. Atlas Bench can also assist with reviews, migrations, and coaching to make the transition smooth across teams and repositories at any scale pipelines.
The introduction of shared and scoped artifact types, along with selective download, gives teams precise control over how files move through their pipelines. Shared artifacts support clean handoffs across stages while scoped artifacts protect step isolation and minimize unnecessary transfers. Selective download cements the practice of explicit dependencies, which leads to faster runs, clearer governance, and simpler troubleshooting. Storage and size policies remain straightforward, which lowers cognitive load during rollout. With these upgrades in place, pipelines become leaner, more maintainable, and better aligned to the way modern teams ship software every day.