Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

chore(stages): add docs for independent tag #340

Merged
merged 1 commit into from
Dec 19, 2022
Merged

chore(stages): add docs for independent tag #340

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 21 additions & 7 deletions content/reference/yaml/stages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,11 +30,12 @@ stages:

## Tags

| Tag | Required | Type | Description |
|---------|----------|----------|-----------------------------------------------------------|
| `name` | Y | string | Unique identifier for the stage in the pipeline |
| `steps` | Y | []string | Sequential execution instructions for the stage |
| `needs` | N | []string | Stages that must complete before starting the current one |
| Tag | Required | Type | Description |
|---------------|----------|----------|---------------------------------------------------------------------------|
| `name` | Y | string | Unique identifier for the stage in the pipeline |
| `steps` | Y | []string | Sequential execution instructions for the stage |
| `needs` | N | []string | Stages that must complete before starting the current one |
| `independent` | N | bool | Stage will execute its steps and ignore failures from other stages' steps |

### Usage

Expand All @@ -58,12 +59,12 @@ stages:
steps:
```

#### The `steps:` tag

{{% alert title="Tip:" color="info" %}}
For more details on steps tags, see the [step tags documentation](/docs/reference/yaml/steps/#tags)
{{% /alert %}}

#### The `needs:` tag

```yaml
---
stages:
Expand All @@ -74,3 +75,16 @@ stages:
# Stages that must complete before starting the current one.
needs: [ greeting ]
```

#### The `independent:` tag

```yaml
---
stages:
greeting:

# Unique identifier for the stage in the pipeline.
welcome:
# If the greeting stage fails at any point, the welcome stage will continue its execution.
independent: true
```
46 changes: 44 additions & 2 deletions content/tour/stages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ A stages pipelines are designed to parallelize one-to-many sets of step tasks.

By design all of the stages will run at the same time unless the user uses a `needs:` YAML tag to control the flow of stage executions (see example). Note: even if every step within a stage is skipped, the stage still runs. Do not use `needs` as a stage-level equivalent to `rulesets`.

Stages will also stop executing their steps if the build fails as a whole, by default. In other words, if stage 1 fails, the steps that have yet to execute in stage 2 will be skipped. The user can declare `independent: true` for any stage to change this behavior.

These pipelines do not have a minimum defined length and will always execute steps within a stage in the order defined. Stages always run on the same host so it's important to take into consideration the size of the worker running your builds.

In this pipeline both stages trigger at the same time and run independently of the other.
Expand Down Expand Up @@ -56,7 +58,6 @@ stages:
- echo "Goodbye, World"
```


```sh
$ vela exec pipeline
...
Expand All @@ -65,7 +66,48 @@ $ vela exec pipeline
[stage: welcome][step: Welcome] $ echo "Welcome to the Vela docs"
[stage: welcome][step: Welcome] Welcome to the Vela docs
[stage: goodbye][step: Goodbye] $ echo "Goodbye, World"
[stage: goodbye][step: Goodbyte] Goodbye, World
[stage: goodbye][step: Goodbye] Goodbye, World
```

```yaml
version: "1"

# In this pipeline, the behavior is very similar as the previous one. However, the
# `goodbye` stage will continue executing its steps, ignoring the failure in the welcome
# stage. The overall build status will still be a failure.

stages:
greeting:
steps:
- name: Greeting
image: alpine
commands:
- echo "Hello, World"

welcome:
steps:
- name: Welcome
image: alpine
commands:
- echo "Welcome to the Vela docs"
- echo "Uh oh"
- exit 1

goodbye:
# will wait for greeting and welcome to finish
needs: [greeting, welcome]
# will ignore the failures in other stages
independent: true
steps:
- name: Goodbye
image: alpine
commands:
- echo "Goodbye, World"
- sleep 5
- name: Have a nice day
image: alpine
commands:
- echo "Have a nice day!"
```

<!-- section break -->
Expand Down