Installation

Prerequisites

• An environment with Python 3.10 or later installed.
• Blocks account and API key.
• Blocks Github App.

If you’d like to use Blocks with other providers such as Gitlab or Bitbucket, please reach out: [e-mail].

1

Install Blocks

bash

pip install blocks-sdk

2

Initialize Blocks

bash

blocks init --key <your-api-key>

We’ll verify your API key and create a .blocks directory in the current working directory.

3

Create an automation

The easiest way to create an automation is to use the create command.

bash

blocks create hello-world

This will create a new automation in the .blocks directory with the following structure:

.blocks/
    hello-world/
        main.py
        requirements.txt

Below are two example automations you can copy to get started. The first one is a simple hello world, and the second one is a more complex automation that leverages the litellm library to summarize a pull request in a single sentence.

./blocks/hello-world/main.py

from blocks import task, on, repo

@task(name="hello-world")
@on("github.pull_request")
def hello_world(event):
    pull_request_number = event.get("pull_request").get("number")
    # Comment 'Hello, World!' on the pull request
    repo.comment_on_pull_request(event, pull_request_number, "Hello, World!")

For the second automation, we’ve added the litellm library as a dependency to requirements.txt. To use gpt-4o, litellm expects an environment variable called OPENAI_API_KEY. You would need to get your own OpenAI API key and add it to the environment variables dashboard.

4

Register an automation

Automations are registered with the push command; specify the filename relative to your current working directory. All automations defined the file will be registered, however you can only register one file at a time.

bash

blocks push .blocks/hello_world/main.py

5

Install Github App

Ensure you have the Blocks Github App installed on your repository so Blocks can trigger your automation.

Project Structure

The .blocks directory is where automation source code is defined. A typical project structure looks like the following:

.blocks/
    automation-1/
        main.py
        requirements.txt
    automation-2/
        main.py
        requirements.txt
    automation-3.py

Dependencies are isolated to each automation, and there are no restrictions for supported pip packages.

Version Control

Ideally, your automations will be checked into some git provider for version control and storage, just like any other source code. We do preserve the state of registered automations, but do not implement git for version control. However, this is something we can add if requested.

Where do I get an API key?

API keys are created and managed in the dashboard.