Skip to main content

Set up a project's pipeline

A project's work moves through stages: by default Ideas, Building, Dev and Production. The step between two stages moves work on: Start builds a task, Merge merges it, Release deploys what is on one branch to the next. Every stage is set up the same way, and so is every step. A project you never set up runs on the four defaults.

Who can do this: anyone who may edit the project. Others see the settings but can't change them. The stages and steps show in the project's Settings › CI Pipeline, under the Custom pipeline box, once a custom pipeline is saved (Choose a basic pipeline).

Open the settings​

  1. In the sidebar, select Directory, then the Projects tab, and select the project's name.
  2. Settings opens. In its list of sections, select CI Pipeline.

On the Tasks page, with the project picked in the sidebar, its Settings tab opens the same sections.

Under the Custom pipeline box, the stages are a row of cards, left to right (one under another on a phone). Below them, Steps lists every step, then Freezes, then Save. Nothing is saved until you select Save; Discard drops your changes. Start from… beside Stages fills the stages from a preset or another project (Start a pipeline from a preset or another project). Link to template… keeps the pipeline in step with an org template (Link a project to a template); while linked, locked fields can't be changed.

Add, rename, move and remove stages​

  • Add: select + on the arrow where the stage goes, or Add stage after the last card. It is added as Stage.
  • Rename: select the name on a card and type.
  • Move: point at a card and select ‹ or ›. Its step moves with it.
  • Remove: point at a card and select ✕. Any stage can go; one must stay.

Each card has the same two fields, and a badge for what its branch means: Queue (no branch), Work branches (a pattern) or Branch (a branch name). A problem the page can see, such as two stages with the same name or a pattern after a branch, shows in red on the card as you type, and Save waits until it is fixed.

FieldWhat it does
BranchEmpty: work just moves to this stage. A pattern such as fleet/*: work is built here, on its own branch. A branch name such as develop: work is merged into it. The first stage with a branch name is the project's integration branch; the pattern is its branch prefix.
AddressWhere the stage runs, such as its web address.

A merge step runs in the merge lane: when the project has one, Merge lane under the step opens its tab.

What a step does follows from the branches of the stages it joins: none to a pattern is Start, a pattern to a branch is Merge, a branch to another branch is Release, and into a stage with no branch is Move.

Set each step​

Steps lists every step by its action and the stages it joins, with a short summary of its rules, such as By hand · 2 approvals · Wait 1h. Select a step to open its settings; select it again to close them. Every step has Who, Approvals and Timing; a merge or release step also has Gates, a release step Concurrency, and a paused one Paused.

Who​

SettingWhat it does
Can pressThe roles and people who may do the step. Select it to tick roles (Org Owner, Org Admin, Maintainer, Developer) and add members. Until you change it, it is whoever may do it today.
RunsBy hand: someone presses it. By itself: it runs as soon as work arrives.

Gates​

The checks a merge or release step runs first, in order, one at a time. A required gate that fails stops the step; an advisory one only warns. Adding one is in Add a gate to a pipeline step.

Approvals​

SettingWhat it does
NeededHow many approvals, 0 to 5, the step needs before it runs. The rest of this group shows once it is 1 or more.
ApproversWho may approve. Same as who can press is ticked by default. Untick it to pick roles and members of their own. Save refuses a count that the approvers can't reach, such as 2 approvals with one named person and no role, and says so under Approvers.
Requester can't approveOn by default: whoever asked for the step can't approve it. Untick it to let their approval count.
Approval timeoutHow long a request waits for its approvals, in minutes, hours or days (15 minutes to 30 days). Empty: it waits for ever.
On timeoutCancel the request, or Keep waiting and remind the approvers. Shows once a timeout is set.
Instructions for approversUp to 1,000 characters shown to approvers beside Approve, such as what to check first.

Timing​

SettingWhat it does
Wait after arrivalHow long work stays in the stage before this step may run (a soak), in minutes, hours or days, up to 30 days. Empty: no wait.
Allowed hoursTick it to run the step only on the chosen Days, between From and To, in a Time zone (your browser's at first). A To before From runs overnight. Outside them the step waits for the next allowed hour.

Concurrency​

On a Release step only. One release runs at a time, and a release never deploys an older version over a newer one. Order picks what happens to a release still waiting when a newer one is asked for: Newest wins (the default) replaces it; In order runs each in turn.

Paused​

A Release step that runs by itself pauses after a release pressed by hand off the usual path, such as a pick of some changes, until the stage before it has every change the stage after it has. The step's summary then says Paused, and Paused in its settings names the release, who started it and when. It lifts by itself; select Resume to run the step again sooner.

A refusal that names one setting, such as an unknown time zone, shows under that setting in the step it names, and that step opens.

Freeze releases​

Freeze now, at the top of Freezes, stops every release after the integration stage at once, until you untick it. It needs no Save. While it is on, a banner on this tab names who switched it on and when. Each switch is recorded on the Audit page.

To freeze for a planned time:

  1. Under Freezes, select Add freeze.
  2. Give it a Name, then pick when it Starts and Ends.
  3. Pick when it Repeats: Never, Daily, Weekly or Monthly (on the same day of each month; a shorter month uses its last day). A repeating freeze must be shorter than its period.
  4. Pick the Stages it holds: every stage after the integration stage (the default), or Picked stages, then tick each. Only stages with a branch name can be frozen.
  5. Under Let through, tick Hand-pressed steps to let a step someone presses run during the freeze, and keep Releases already queued ticked to let a release queued before the freeze began finish.
  6. Select Save. It stays greyed out until every freeze has a name, a start, an end and, with Picked stages, at least one stage.

No release starts during a freeze; a scheduled one waits for its end. To end a freeze early, select Remove on its row, then Save.

When an org rule applies​

Your organization may set rules for the step into production (Pipeline rules). A rule set to Block refuses Save and names the fix on the stage's card: Fix a pipeline an org rule blocks.

While a release runs​

You can save at any time. While a release runs, a note beside Save says so: the running release finishes on the settings it started with, and the next one uses yours.