Repository: argoproj-labs/hera
Pull request #1383: Streamline quick start guide
Author: login: elliotgunton
Labels: name: semver:patch
description: A change requiring a patch version bump
name: type:documentation
description: A documentation update
Created: 2025-05-14T10:58:42Z | Merged: 2025-05-22T09:05:41Z

**Description of PR**
* Reorder sections so that pip install is first, then describe local and cloud installations of Argo Workflows more clearly
* Move instructions for installing Argo Workflows in GitHub Codespaces to CONTRIBUTING.md
* Related to #965 but mainly comes from developer survey feedback
* Part of #1385 


Diff:
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c2e5746d5..bcf9ac571 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -79,6 +79,38 @@ workflows-models               Generate the Workflows models portion of Argo Wor
 workflows-service              Generate the Workflows service option of Hera
 ```
 
+#### Installing Argo Workflows in GitHub Codespaces
+
+You can install Argo and try running Hera code in GitHub Codespaces. First, open the Hera repository in Codespaces using the link below:
+
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new/argoproj-labs/hera)
+
+Then, you can run the `make` commands to install k3d (a lightweight Kubernetes CLI), and then install the Argo Workflows controller on the cluster:
+
+```
+make install-k3d run-argo
+```
+
+You can [take a look at `test_submission.py`](https://github.com/argoproj-labs/hera/blob/ec06876f1abc0d3309b000f3cd2e0eca64891da9/tests/test_submission.py) to see how to submit a Workflow using Hera and write your own. You can run the test Workflow using:
+
+```
+make test-on-cluster
+```
+
+See the [Viewing the Argo UI from a Codespace](#viewing-the-argo-ui-from-a-codespace) guide to see the Workflow in the UI.
+
+Otherwise you can install the Argo CLI with
+
+```
+make install-argo
+```
+
+which will then let you do things like listing the Workflows in the `argo` namespace with
+
+```
+argo list --namespace argo
+```
+
 #### Working in VSCode
 
 If your preferred IDE is VSCode, you may have an issue using the integrated Testing extension where breakpoints are not
diff --git a/docs/walk-through/quick-start.md b/docs/walk-through/quick-start.md
index c39978881..6d496377c 100644
--- a/docs/walk-through/quick-start.md
+++ b/docs/walk-through/quick-start.md
@@ -1,60 +1,50 @@
 # Quick Start
 
-## Install in GitHub Codespaces
+## Install Hera
 
-You can install Argo and try running Hera code in GitHub Codespaces. First, open the Hera repository in Codespaces using the link below:
-
-[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/argoproj-labs/hera)
+[![Pypi](https://img.shields.io/pypi/v/hera.svg)](https://pypi.python.org/pypi/hera)
 
-Then, you can run the `make` commands to install k3d (a lightweight Kubernetes CLI), and then install the Argo Workflows controller on the cluster:
+Hera is available on PyPi as the `hera` package. Add this dependency to your project with your favourite package
+manager, e.g. [poetry](https://python-poetry.org/), or install directly with
+[pip](https://packaging.python.org/en/latest/guides/tool-recommendations/#installing-packages):
 
 ```
-make install-k3d run-argo
+pip install hera
 ```
 
-You can [take a look at `test_submission.py`](https://github.com/argoproj-labs/hera/blob/ec06876f1abc0d3309b000f3cd2e0eca64891da9/tests/test_submission.py) to see how to submit a Workflow using Hera and write your own. You can run the test Workflow using:
+## Install Argo Workflows
 
-```
-make test-on-cluster
-```
+Hera is a Python SDK built for Argo Workflows, which runs on Kubernetes, therefore you will need a Kubernetes
+environment to run Argo Workflows and test out Hera. If you already have an existing Argo Workflows installation, you
+can go straight to [Running Workflows from Hera](#running-workflows-from-hera) below.
 
-See the [Viewing the Argo UI from a Codespace](../CONTRIBUTING.md#viewing-the-argo-ui-from-a-codespace) guide to see the Workflow in the UI.
+### Install Locally
 
-Otherwise you can install the Argo CLI with
+If you want to run on a local Kubernetes cluster (e.g. Docker Desktop), follow the
+[Argo Workflows Quick Start guide](https://argoproj.github.io/argo-workflows/quick-start/).
 
-```
-make install-argo
-```
-
-which will then let you do things like listing the Workflows in the `argo` namespace with
+Ensure you are able to submit a workflow to Argo as in the example:
 
+```console
+argo submit -n argo --watch https://raw.githubusercontent.com/argoproj/argo-workflows/master/examples/hello-world.yaml
 ```
-argo list --namespace argo
-```
-
-## Install locally
 
-### Install Argo tools
-
-Ensure you have a Kubernetes cluster, kubectl and Argo Workflows installed by following the
-[Argo Workflows Quick Start](https://argoproj.github.io/argo-workflows/quick-start/).
-
-Ensure you are able to submit a workflow to Argo as in the example:
+Use the following command to port-forward the Argo Server; this allows you to access the UI and submit Workflows from
+Hera:
 
 ```console
-argo submit -n argo --watch https://raw.githubusercontent.com/argoproj/argo-workflows/master/examples/hello-world.yaml
+kubectl -n argo port-forward service/argo-server 2746:2746
 ```
 
-### Install Hera
+Check that you can see the UI at <https://localhost:2746>.
 
-[![Pypi](https://img.shields.io/pypi/v/hera.svg)](https://pypi.python.org/pypi/hera)
+Then go to [Running Workflows from Hera](#running-workflows-from-hera) below.
 
-Hera is available on PyPi as the `hera` package. Add this dependency to your project in your usual way, e.g. pip or
-poetry, or install directly with `pip install hera`.
+## Running Workflows from Hera
 
-### Hello World
+### Local Argo Workflows Installation
 
-If you were able to run the `argo submit` command above, copy the following Workflow definition into a local file
+Copy the following Workflow definition into a local file
 `hello_world.py`.
 
 ```py
@@ -75,7 +65,8 @@ with Workflow(
     with Steps(name="steps"):
         echo(arguments={"message": "Hello world!"})
 
-w.create()
+submitted_workflow = w.create()
+print(f"Workflow at https://localhost:2746/workflows/argo/{submitted_workflow.metadata.name}")
 ```
 
 Run the file
@@ -84,20 +75,20 @@ Run the file
 python -m hello_world
 ```
 
-You will then see the Workflow at <https://localhost:2746/>
+You will then see the Workflow at the specified link.
 
-## Using an existing Argo installation
+### Existing Cloud Installation of Argo Workflows
 
 If you or your organization are already running on Argo and you're interested in using Hera to write your Workflow
-definitions, you will need to set up some config variables in `hera.shared.global_config`. Copy the following as a basis
-and fill in the blanks.
+definitions, you will need to set up some config variables in `hera.shared.global_config`. Copy the following into a
+local file as a basis and fill in the blanks.
 
 ```py
 from hera.workflows import Steps, Workflow, script
 from hera.shared import global_config
 
 global_config.host = "https://<your-host-name>"
-global_config.token = ""  # Copy token value after "Bearer" from the `argo auth token` command
+global_config.token = ""  # Copy token value after "Bearer" from the CLI command `argo auth token`
 global_config.image = "<your-image-repository>/python:3.9"  # Set the image if you cannot access "python:3.9" via Docker Hub
 
 
@@ -123,4 +114,4 @@ Run the file
 python -m hello_world
 ```
 
-You will then see the Workflow at https://your-host-name
+You will then see the Workflow at `https://<your-host-name>`


Reviews:
user: login: alicederyn
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-05-16T09:04:06Z
user: login: elliotgunton
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-05-20T09:34:32Z
user: login: alicederyn
body: Not a fan of Poetry myself but it is popular 😅 
state: APPROVED
author_association: COLLABORATOR
submitted_at: 2025-05-22T09:05:40Z
user: login: elliotgunton
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-05-22T09:17:11Z

Review comments:
diff_hunk: @@ -79,6 +79,38 @@ workflows-models               Generate the Workflows models portion of Argo Wor
 workflows-service              Generate the Workflows service option of Hera
 ```
 
+#### Installing Argo Workflows in GitHub Codespaces
+
+You can install Argo and try running Hera code in GitHub Codespaces. First, open the Hera repository in Codespaces using the link below:
+
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/argoproj-labs/hera)
path: CONTRIBUTING.md
user: login: alicederyn
body: It's a cool URL, but could we use https://github.com/codespaces/new/argoproj-labs/hera so people who hover over it can be more confident it's going to github?
created_at: 2025-05-16T08:55:32Z
author_association: COLLABORATOR
diff_hunk: @@ -79,6 +79,38 @@ workflows-models               Generate the Workflows models portion of Argo Wor
 workflows-service              Generate the Workflows service option of Hera
 ```
 
+#### Installing Argo Workflows in GitHub Codespaces
+
+You can install Argo and try running Hera code in GitHub Codespaces. First, open the Hera repository in Codespaces using the link below:
+
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/argoproj-labs/hera)
+
+Then, you can run the `make` commands to install k3d (a lightweight Kubernetes CLI), and then install the Argo Workflows controller on the cluster:
+
+```
+make install-k3d run-argo
+```
+
+You can [take a look at `test_submission.py`](https://github.com/argoproj-labs/hera/blob/ec06876f1abc0d3309b000f3cd2e0eca64891da9/tests/test_submission.py) to see how to submit a Workflow using Hera and write your own. You can run the test Workflow using:
+
+```
+make test-on-cluster
+```
+
+See the [Viewing the Argo UI from a Codespace](../CONTRIBUTING.md#viewing-the-argo-ui-from-a-codespace) guide to see the Workflow in the UI.
path: CONTRIBUTING.md
user: login: alicederyn
body: ```suggestion
See the [Viewing the Argo UI from a Codespace](#viewing-the-argo-ui-from-a-codespace) guide to see the Workflow in the UI.
```
created_at: 2025-05-16T08:57:03Z
author_association: COLLABORATOR
diff_hunk: @@ -1,60 +1,47 @@
 # Quick Start
 
-## Install in GitHub Codespaces
+## Install Hera
 
-You can install Argo and try running Hera code in GitHub Codespaces. First, open the Hera repository in Codespaces using the link below:
-
-[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/argoproj-labs/hera)
+[![Pypi](https://img.shields.io/pypi/v/hera.svg)](https://pypi.python.org/pypi/hera)
 
-Then, you can run the `make` commands to install k3d (a lightweight Kubernetes CLI), and then install the Argo Workflows controller on the cluster:
+Hera is available on PyPi as the `hera` package. Add this dependency to your project with your favourite package
+manager, e.g. [pip](https://packaging.python.org/en/latest/guides/tool-recommendations/#installing-packages) or [poetry](https://python-poetry.org/), or install directly with
path: docs/walk-through/quick-start.md
user: login: alicederyn
body: I'm not sure the intent here -- pip is listed as a package manager, which I don't think it is, and then it's listed again under "or install directly". Perhaps this instead?

```suggestion
Hera is available on PyPi as the `hera` package. Add this dependency to your project with your favourite package
manager, e.g. [setuptools](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#dependencies-and-requirements), [uv](https://docs.astral.sh/uv/concepts/projects/dependencies/) or [poetry](https://python-poetry.org/), or install directly with
```
created_at: 2025-05-16T09:01:00Z
author_association: COLLABORATOR
diff_hunk: @@ -1,60 +1,47 @@
 # Quick Start
 
-## Install in GitHub Codespaces
+## Install Hera
 
-You can install Argo and try running Hera code in GitHub Codespaces. First, open the Hera repository in Codespaces using the link below:
-
-[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/argoproj-labs/hera)
+[![Pypi](https://img.shields.io/pypi/v/hera.svg)](https://pypi.python.org/pypi/hera)
 
-Then, you can run the `make` commands to install k3d (a lightweight Kubernetes CLI), and then install the Argo Workflows controller on the cluster:
+Hera is available on PyPi as the `hera` package. Add this dependency to your project with your favourite package
+manager, e.g. [pip](https://packaging.python.org/en/latest/guides/tool-recommendations/#installing-packages) or [poetry](https://python-poetry.org/), or install directly with
 
 ```
-make install-k3d run-argo
+pip install hera
 ```
 
-You can [take a look at `test_submission.py`](https://github.com/argoproj-labs/hera/blob/ec06876f1abc0d3309b000f3cd2e0eca64891da9/tests/test_submission.py) to see how to submit a Workflow using Hera and write your own. You can run the test Workflow using:
+## Install Argo Workflows
 
-```
-make test-on-cluster
-```
+Hera is a Python SDK built for Argo Workflows, which runs on Kubernetes, therefore you will need a Kubernetes
+environment to run Argo Workflows and test out Hera. If you already have an existing Argo Workflows installation, you
+can go straight to [Running Workflows from Hera](#running-workflows-from-hera) below.
 
-See the [Viewing the Argo UI from a Codespace](../CONTRIBUTING.md#viewing-the-argo-ui-from-a-codespace) guide to see the Workflow in the UI.
+### Install Locally
 
-Otherwise you can install the Argo CLI with
+If you want to run on a local Kubernetes cluster (e.g. Docker Desktop), follow the Argo Workflows [Quick Start guide](https://argoproj.github.io/argo-workflows/quick-start/).
path: docs/walk-through/quick-start.md
user: login: alicederyn
body: ```suggestion
If you want to run on a local Kubernetes cluster (e.g. Docker Desktop), follow the [Argo Workflows Quick Start guide](https://argoproj.github.io/argo-workflows/quick-start/).
```
created_at: 2025-05-16T09:03:07Z
author_association: COLLABORATOR
diff_hunk: @@ -1,60 +1,47 @@
 # Quick Start
 
-## Install in GitHub Codespaces
+## Install Hera
 
-You can install Argo and try running Hera code in GitHub Codespaces. First, open the Hera repository in Codespaces using the link below:
-
-[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/argoproj-labs/hera)
+[![Pypi](https://img.shields.io/pypi/v/hera.svg)](https://pypi.python.org/pypi/hera)
 
-Then, you can run the `make` commands to install k3d (a lightweight Kubernetes CLI), and then install the Argo Workflows controller on the cluster:
+Hera is available on PyPi as the `hera` package. Add this dependency to your project with your favourite package
+manager, e.g. [pip](https://packaging.python.org/en/latest/guides/tool-recommendations/#installing-packages) or [poetry](https://python-poetry.org/), or install directly with
 
 ```
-make install-k3d run-argo
+pip install hera
 ```
 
-You can [take a look at `test_submission.py`](https://github.com/argoproj-labs/hera/blob/ec06876f1abc0d3309b000f3cd2e0eca64891da9/tests/test_submission.py) to see how to submit a Workflow using Hera and write your own. You can run the test Workflow using:
+## Install Argo Workflows
 
-```
-make test-on-cluster
-```
+Hera is a Python SDK built for Argo Workflows, which runs on Kubernetes, therefore you will need a Kubernetes
+environment to run Argo Workflows and test out Hera. If you already have an existing Argo Workflows installation, you
+can go straight to [Running Workflows from Hera](#running-workflows-from-hera) below.
 
-See the [Viewing the Argo UI from a Codespace](../CONTRIBUTING.md#viewing-the-argo-ui-from-a-codespace) guide to see the Workflow in the UI.
+### Install Locally
 
-Otherwise you can install the Argo CLI with
+If you want to run on a local Kubernetes cluster (e.g. Docker Desktop), follow the Argo Workflows [Quick Start guide](https://argoproj.github.io/argo-workflows/quick-start/).
 
-```
-make install-argo
-```
-
-which will then let you do things like listing the Workflows in the `argo` namespace with
+Ensure you are able to submit a workflow to Argo as in the example:
 
+```console
+argo submit -n argo --watch https://raw.githubusercontent.com/argoproj/argo-workflows/master/examples/hello-world.yaml
 ```
-argo list --namespace argo
-```
-
-## Install locally
 
-### Install Argo tools
-
-Ensure you have a Kubernetes cluster, kubectl and Argo Workflows installed by following the
-[Argo Workflows Quick Start](https://argoproj.github.io/argo-workflows/quick-start/).
-
-Ensure you are able to submit a workflow to Argo as in the example:
+Use the following command to port-forward the Argo Server to access the UI and so you can submit Workflows from Hera:
path: docs/walk-through/quick-start.md
user: login: alicederyn
body: ```suggestion
Use the following command to port-forward the Argo Server; this will allow you to access the UI, and submit Workflows from Hera:
```
created_at: 2025-05-16T09:03:35Z
author_association: COLLABORATOR
diff_hunk: @@ -1,60 +1,47 @@
 # Quick Start
 
-## Install in GitHub Codespaces
+## Install Hera
 
-You can install Argo and try running Hera code in GitHub Codespaces. First, open the Hera repository in Codespaces using the link below:
-
-[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/argoproj-labs/hera)
+[![Pypi](https://img.shields.io/pypi/v/hera.svg)](https://pypi.python.org/pypi/hera)
 
-Then, you can run the `make` commands to install k3d (a lightweight Kubernetes CLI), and then install the Argo Workflows controller on the cluster:
+Hera is available on PyPi as the `hera` package. Add this dependency to your project with your favourite package
+manager, e.g. [pip](https://packaging.python.org/en/latest/guides/tool-recommendations/#installing-packages) or [poetry](https://python-poetry.org/), or install directly with
path: docs/walk-through/quick-start.md
user: login: elliotgunton
body: Yeah I tried to simplify it and not overexplain here (but failed)
created_at: 2025-05-20T09:34:32Z
author_association: COLLABORATOR
diff_hunk: @@ -79,6 +79,38 @@ workflows-models               Generate the Workflows models portion of Argo Wor
 workflows-service              Generate the Workflows service option of Hera
 ```
 
+#### Installing Argo Workflows in GitHub Codespaces
+
+You can install Argo and try running Hera code in GitHub Codespaces. First, open the Hera repository in Codespaces using the link below:
+
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new/argoproj-labs/hera)
+
+Then, you can run the `make` commands to install k3d (a lightweight Kubernetes CLI), and then install the Argo Workflows controller on the cluster:
+
+```
+make install-k3d run-argo
+```
+
+You can [take a look at `test_submission.py`](https://github.com/argoproj-labs/hera/blob/ec06876f1abc0d3309b000f3cd2e0eca64891da9/tests/test_submission.py) to see how to submit a Workflow using Hera and write your own. You can run the test Workflow using:
path: CONTRIBUTING.md
user: login: alicederyn
body: I just spotted this is pinned to a specific commit, don't we want this to show the latest version in case it's updated?
created_at: 2025-05-22T08:59:28Z
author_association: COLLABORATOR
diff_hunk: @@ -79,6 +79,38 @@ workflows-models               Generate the Workflows models portion of Argo Wor
 workflows-service              Generate the Workflows service option of Hera
 ```
 
+#### Installing Argo Workflows in GitHub Codespaces
+
+You can install Argo and try running Hera code in GitHub Codespaces. First, open the Hera repository in Codespaces using the link below:
+
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new/argoproj-labs/hera)
+
+Then, you can run the `make` commands to install k3d (a lightweight Kubernetes CLI), and then install the Argo Workflows controller on the cluster:
+
+```
+make install-k3d run-argo
+```
+
+You can [take a look at `test_submission.py`](https://github.com/argoproj-labs/hera/blob/ec06876f1abc0d3309b000f3cd2e0eca64891da9/tests/test_submission.py) to see how to submit a Workflow using Hera and write your own. You can run the test Workflow using:
path: CONTRIBUTING.md
user: login: elliotgunton
body: This was supposed to be a specific commit yes, which is good as the file doesn't exist anymore 😆 We could update this to https://github.com/argoproj-labs/hera/blob/main/tests/submissions/test_hello_world.py but with the latest commit. I'm not majorly fussed though, it serves its purpose to show the submission code
created_at: 2025-05-22T09:17:10Z
author_association: COLLABORATOR

PR comments:
user: login: codecov[bot]
created_at: 2025-05-14T14:13:45Z
body: ## [Codecov](https://app.codecov.io/gh/argoproj-labs/hera/pull/1383?dropdown=coverage&src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=argoproj-labs) Report
:white_check_mark: All modified and coverable lines are covered by tests.
:white_check_mark: Project coverage is 87.0%. Comparing base ([`86e25ee`](https://app.codecov.io/gh/argoproj-labs/hera/commit/86e25eef3211d5faffd848828a903d9947113429?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=argoproj-labs)) to head ([`c947dd8`](https://app.codecov.io/gh/argoproj-labs/hera/commit/c947dd883b1bc43c116f1e5cad04037fc9ec93a8?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=argoproj-labs)).
:warning: Report is 58 commits behind head on main.

<details><summary>Additional details and impacted files</summary>



```diff
@@          Coverage Diff          @@
##            main   #1383   +/-   ##
=====================================
  Coverage   87.0%   87.0%           
=====================================
  Files         60      60           
  Lines       4177    4177           
  Branches     673     673           
=====================================
  Hits        3638    3638           
  Misses       378     378           
  Partials     161     161           
```
</details>

[:umbrella: View full report in Codecov by Sentry](https://app.codecov.io/gh/argoproj-labs/hera/pull/1383?dropdown=coverage&src=pr&el=continue&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=argoproj-labs).   
:loudspeaker: Have feedback on the report? [Share it here](https://about.codecov.io/codecov-pr-comment-feedback/?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=argoproj-labs).
<details><summary> :rocket: New features to boost your workflow: </summary>

- :snowflake: [Test Analytics](https://docs.codecov.com/docs/test-analytics): Detect flaky tests, report on failures, and find test suite problems.
</details>
author_association: NONE
user: login: elliotgunton
created_at: 2025-05-15T17:20:24Z
body: This one is mostly a rearranging of existing content (and just one page), hence not part of the [revamp PR](https://github.com/argoproj-labs/hera/pull/1386), so should be easier to review/approve 🚀 
author_association: COLLABORATOR