Windmill Community Integrations Guide

Windmill is an Open-source developer infrastructure for internal tools (APIs, background jobs, workflows and UIs). Self-hostable alternative to Airplane, Pipedream, Superblocks and a simplified Temporal with autogenerated UIsm and custom UIs to trigger workflows and scripts as internal apps.

Windmill Hub is a platform that provides Windmill's users with reusable scripts, flows, apps which interact with a variety of integrations. They were created by the community and the Windmill team itself.

Contributing guide

We provide you with a list of desired integrations and, for each integration, a list of script descriptions to help you contribute. In addition, we provide a CLI to generate all the boilerplate code for a given integration.

Check issues for the desired integration we currently need.

You can find below the guide to contributing all the scripts for a specific integration

Credentials and environment variables setup

• Fork this repository, clone it, create a new branch and install the dependencies using bun install
• Run bun run setup {integration_name} to create and setup the integration folder along with the resource, resource type, README, scripts, and tests templates.
• Create an account on the integration's platform if you don't have one (can be your private account)
• Put the credentials in the integrations/{integration_name}/.env file. You can also add other variables that you may need and are user specific but aren't needed for authentication (e.g. OWNER and REPO for GitHub).
• Update the resource object in integrations/{integration_name}/resource.ts with the credentials from the environment variables using Bun.env.VARIABLE_NAME! (these are gitinore'd, so they won't be pushed to the repository)
• Adjust the resource type definition in integrations/{integration_name}/resource_type.json to resource object. You have to follow the json schema format.
• Write down the steps to get the credentials for the integration as well as a description of all environment variables needed in the integrations/{integration_name}/README.md file
• Install any packages you may need (e.g. the integration SDK) using bun add {package_name} inside the integrations/{integration_name} folder.

Note: resource types are object definitions that represent credentials for a specific integration. You can learn more about them here.

Special case for OAUTH: if the integration uses OAuth, do not include the OAuth flow in the script. Just define a property named token on the resource type that you can set to the access token during your tests.

Creating the scripts

• Adjust each script template to achieve the desired functionality. You will need to specify the parameters of the resource type in each script. They have to be the same in all the scripts and match the resource type definition in integrations/{integration_name}/resource_type.json. For function parameters, define the types inline (e.g. "repositories: { owner: string, repo: string }[]") rather than defining a type for each parameter and avoid nested types when possible.
• Update the test file with appropriate testing arguments. Include any preliminary and clean-up steps. Here's a general guide for the tests:
  • GET: Before calling the script, create the object that you will retrieve. After calling the script, just check that what the script returned matches the object you created. Delete the object.
  • POST/PUT: Create the object, call the script to update it, check that the object was updated as expected using the SDK/API. Delete the object.
  • DELETE: Create the object, call the script to delete it, check that the object was deleted using the SDK/API.
• You can also write into the integrations/{integration_name}/setup.ts file any setup code that you may need before and after all tests of all scripts (e.g. creating a new project before running the tests and deleting it after).
• Please make sure to format the code using prettier before creating the PR.
• Inside the integrations/{integration_name} folder, run bun test --preload ./setup.ts to check the tests.

Tip: You can find a complete example for GitHub in the integrations/github folder

Validating the contribution

Once you're done, create a PR with all the files apart from .env (which should be gitignore'd by default). We will follow your steps to get credentials, check the tests, and validate the PR.