Introducing: Final Steps in Bitbucket Pipelines

If you’ve ever run a pipeline, you’ve certainly encountered the following situation: The pipeline fails halfway through, and the cleanup script you needed at the end to tear down test infrastructure or archive the logs never gets to run.

Until now, there was no built-in way in Bitbucket Pipelines to guarantee that a step always executes at the end of your pipeline, regardless of what happened before it. Today, we’re fixing that. We’re introducing final steps: a new step in Bitbucket Pipelines that lets you define “always-run” logic directly in your bitbucket-pipelines.yml. Cleanup, telemetry, notifications, audit events — the final step always runs, ensuring whatever you needed to happen at the end, always happens.

---

How to use the Final Step

The final step is a special construct in Bitbucket Pipelines that:

• Runs after all other steps in a pipeline.
• Executes regardless of the outcome of previous steps (failed, passed, skipped, or stopped).
• Runs again on re-runs, resumes, and redeploys.
• Is clearly marked in the Pipelines UI as the final step.
• Behaves like a regular step, with a few targeted restrictions to keep pipelines predictable.

To use it, just add a final: section as the last entry in your pipeline definition:

pipelines:
  default:
    - step:
        name: Build & Test
        script:
          - echo "This is the build step"
    - step:
        name: Deploy
        script:
          - echo "This is the deployment step"
    - final:
        name: Cleanup
        script:
          - echo "This is the final step"

What happens?

• The final step always runs last, even if earlier steps fail or are skipped.
• In the UI, it’s visually identified as the final step for quick visibility.

---

Real word examples

• In this example, the final step runs regardless of whether the build or deploy steps pass or fail:

pipelines:
  default:
    - step:
        name: Build & Test
        script:
          - echo "This is the build step"
          - exit 1      # simulate a failure
    - step:
        name: Deploy
        script:
          - echo "This is the deployment step"
    - final:
        name: Cleanup
        script:
          - echo "This is the final step"

• You can also define final steps in custom pipelines, for example to centralize notifications or cleanup in a reusable workflow:

pipelines:
  custom:
    release:
      - step:
          name: Build & Test
          script:
            - ./scripts/build-and-test.sh
      - step:
          name: Package
          script:
            - ./scripts/package.sh
      - final:
          name: Post-release tasks
          script:
            - ./scripts/publish-metrics.sh
            - ./scripts/notify-release-channel.sh

Whenever you run the release custom pipeline, Post-release tasks will run at the end, including on re-runs, resumes, and redeploys.

---

Supported features

The final step for all practical purposes is similar to any other step in the pipelines. More about the pipeline steps – Step options | Bitbucket Cloud | Atlassian Support However, there are some additional checks and restrictions specific to the final step to ensure proper usage and consistent behavior. If any of these validation checks fail, the pipeline trigger will fail with a relevant error message.

Validation Check
Only One Final Step, Always at the End	You can define just one final section in your pipeline, and it must always be the very last step.
Minimum Step Requirement	There must be at least one non-final step in the pipeline.
No Grouping or Parallelization	The final step cannot be included in any group (stage) or run in parallel with other steps.
No Child Pipeline Triggering	The final step cannot trigger a child pipeline but can be used within one.
No Manual, Deployment, or Fail-Fast Options	The final step does not support the manual trigger, deployment property, or fail-fast option.

---

Get started today

The final step is available now in Bitbucket Pipelines. Add a final:section to any pipeline definition in your bitbucket-pipelines.ymland start simplifying your post-pipeline workflows today.

To learn more about step options and configuration details, visit our documentation.

We’d love to hear how you’re using the final step — whether it’s for cleanup, notifications, compliance, or something we haven’t thought of yet. Share your use cases, ask questions, and let us know what you’d like to see next in our community forum post.

Happy building!