Tutorials
Share a workspace with your team using git
Create a workspace in a folder on disk, commit it, open it on a teammate's computer with their own secrets and review a workflow change in a pull request.
You will create a workspace in a folder, commit it to git, open it as a teammate and review a change to a workflow in a pull request. The result is workflows your team keeps, reviews and runs from one repository, with no secret in it. You need about 30 minutes, the desktop app, git installed, an OpenAPI contract of your own and a Git repository you can push to. A second computer, or a second folder, plays the teammate.
1. Create the workspace in a folder
Section titled “1. Create the workspace in a folder”- On the welcome screen, click Create a workspace. If a workspace is already open, open its Workspace options menu and choose Close and switch workspace first.
- Type
Shop testsin Workspace name. - Read the line Will be created at: it shows the folder. To use another place, click Change location, then Change…, and edit Folder name if you want.
- Click Create workspace.
Luvin creates the folder with a file luvin.yaml inside. Every change you make from now on is saved in files automatically. See Workspaces and collections.
2. Create a collection and add content
Section titled “2. Create a collection and add content”- On Home, click Create your first collection. Type
paymentsin Collection name and click Create. - Under Quick actions, click Import Arazzo or contracts and choose your OpenAPI contract.
- Click + (Create or import) and choose New Arazzo. Drag two operations onto the canvas, as in Build your first workflow.
- In the sidebar, under Environments, click + (New environment), name it
staging, and set its base URL. - In Variables add
clientId, and in Secrets addclientSecretwith its Value.
See Base URLs, variables and secrets.
3. See what is on disk
Section titled “3. See what is on disk”- Open the Workspace options menu and choose Show in Finder (Show in file explorer on Windows and Linux).
The folder looks like this:
shop-tests/├── luvin.yaml└── payments/ ├── collection.yaml ├── payments.openapi.yaml ├── new.arazzo.yaml ├── environments/ │ └── staging.yaml └── scenarios/ └── new.arazzo.yaml| File | What it holds |
|---|---|
luvin.yaml |
The workspace: its name and the list of collections. |
payments.openapi.yaml |
Your contract, as you imported it. |
new.arazzo.yaml |
The workflows. This is the file your team reviews. |
environments/staging.yaml |
Base URLs, variables and the names of the secrets. |
scenarios/new.arazzo.yaml |
The inputs and the custom cases of that Arazzo file. |
Open environments/staging.yaml in an editor:
name: stagingservers: shop: https://staging.api.shop.testvariables: clientId: shop-staging-clientsecrets: - clientSecretThe secret has a name and no value. The value is stored encrypted on your computer, never in the files. See What is on disk.
4. Commit and push
Section titled “4. Commit and push”Use your usual git client, or the Terminal tab of Dev Tools, in the desktop app. In the folder of the workspace:
git initgit add .git commit -m "Add the shop workflows"git remote add origin <your repository>git push -u origin mainThere is nothing to put in .gitignore: Luvin writes nothing in the folder that you must leave out. See Keep a workspace in git.
5. A teammate opens it
Section titled “5. A teammate opens it”On the teammate’s computer:
- Clone the repository:
git clone <your repository>. - Open Luvin and click Open a workspace. Choose the cloned folder, the one with
luvin.yaml. - In the sidebar, under Environments, open
staging. - In Secrets, type the Value of
clientSecret. The name is already listed. - In the run bar, choose Real API and run a case.
If a value is missing, a notice above the workflow says Credentials are missing in “staging”. Click Fill in to open the environment.
The teammate’s secret stays on their computer, encrypted. Each person uses their own. A good habit is to list in the README.md of the workspace which secrets each environment needs and who to ask.
6. Change a workflow and open a pull request
Section titled “6. Change a workflow and open a pull request”- The teammate creates a branch:
git switch -c add-idempotency-header. - In Luvin, they open a workflow, click a step in Design and add a header to it. Luvin saves on its own.
- In the terminal:
git diff.
The change is a few lines of the Arazzo file:
- stepId: createOrder operationId: $sourceDescriptions.shop.createOrder parameters: - name: Idempotency-Key in: header value: $inputs.requestId- They commit, push the branch and open a pull request on your git platform.
The pull request shows what changed, line by line. What the reviewer reads:
| Change | Where it shows |
|---|---|
| A new step, a new connection or a different success criterion | The *.arazzo.yaml file |
| New starting inputs or a new custom case | The same file in scenarios/ |
| A different base URL or variable | environments/<name>.yaml |
The reviewer can also check out the branch and open the workspace in Luvin to run the cases. Luvin reads the files when you open a collection and does not watch the folder: after git pull or a branch switch, open Workspace options, choose Close and switch workspace and open the workspace again.
What you learned
Section titled “What you learned”- A workspace in a folder is plain text files, ready for git.
- Secret values never go into the files: only their names do.
- A teammate adds their own secrets after cloning.
- A pull request shows a workflow change as an Arazzo diff.
- Values typed in Inputs are saved as typed in
scenarios/: use a secret for anything sensitive.