Workspaces
Keep a workspace in git
What to commit, why secrets stay out of the repository, how to review a workflow in a pull request and what a teammate does after cloning.
A workspace is a folder of text files, so you can keep it in git like code. Your team can then review a change to a workflow in a pull request, see its history and share one source of truth. Luvin does not run git for you: use your usual git client, or the terminal of the desktop app (see Terminal).
Example: a workflow change in a pull request
Section titled “Example: a workflow change in a pull request”A change to a workflow is a change to a text file, so the pull request shows it line by line. For example, adding a header to a step appears as:
- stepId: createOrder operationId: $sourceDescriptions.shop.createOrder parameters: - name: Idempotency-Key in: header value: $inputs.requestIdWhat a reviewer reads, and where:
| Change | File that shows it |
|---|---|
| A new step, a new wiring between steps, a different success criterion | The *.arazzo.yaml file. |
| New starting inputs or a new custom case | The file with the same name inside scenarios/. |
| A different base URL or variable in an environment | environments/<name>.yaml. |
| A contract change that can break a workflow | The *.openapi.yaml or *.asyncapi.yaml file. |
| A new request saved for debugging | requests/*.request.yaml. |
The reviewer can also open the branch in Luvin, run the cases and read the results. Keep the generated documentation in the repository so the pull request shows how the summary of the workflows changes.
What to commit
Section titled “What to commit”Commit the whole workspace folder: luvin.yaml, the optional README.md and every collection folder. Luvin writes nothing in it that you need to ignore. What is on disk lists each file.
You can also commit a single collection, if each collection has its own repository. A folder with collection.yaml and Arazzo files opens as a workspace.
Why secrets are safe
Section titled “Why secrets are safe”Luvin keeps secret values out of the files:
- An environment file lists only the names of its secrets. The values are stored encrypted on each computer.
- Credentials, such as a token or an API key, are not written to the files.
- The workflow authorization (
flow-auth.yaml) points to variables, for exampleclientSecret: '{{clientSecret}}', instead of holding the value. - The generated documentation says it too: credentials and secrets are not in the repository.
An environment file in the repository looks like this:
name: Stagingservers: shop: https://staging.api.shop.testvariables: clientId: shop-staging-clientsecrets: - clientSecretAfter cloning: add your secrets
Section titled “After cloning: add your secrets”The files hold names and no values, so a teammate who clones the repository has to enter their own.
- Clone the repository with git.
- In Luvin, choose Open a workspace and pick the cloned folder (the one with
luvin.yaml). - In the sidebar, under Environments, open the environment you will use.
- In Secrets, type the Value of each secret. The names are already listed.
- Fill in Credentials if the contracts ask for them, and any variable with an empty value.
If you run against the real API and something is missing, a notice above the workflow says Credentials are missing in “name” and Fill in opens the environment. See Base URLs, variables and secrets.
The values stay on that computer, encrypted. They are never added to the repository, so everyone uses their own.
Which environment is active in each collection is also remembered per computer, not in the files.