Skip to main content

Getting Started with Bosun

This guide walks through the minimum steps to connect a repository and run your first automated task.

What You'll Learn​

In this guide, you will:

  • Understand the core components of a Bosun task.
  • Learn how to set up your Bosun account and connect a repository.
  • Create and run your first automated task involving a coding agent and a pull request.

Core Concepts​

Before diving in, it's helpful to understand a few key Bosun concepts:

  • Tasks: The central unit of automation in Bosun. Each task encapsulates a repeatable workflow that performs a specific job.
  • Agents: AI-powered entities that perform intelligent actions within a task, such as writing code, refactoring, or analyzing.
  • Steps: Individual actions within a task, which can be executed by agents (agent step) or as shell commands (run step).
  • Task graphs: The way steps connect. Bosun lets you define branches and merges between steps—see Task Graphs and Branching for details.

For a deeper dive into these concepts, refer to the Concepts section.

Setup and Repository Connection​

Bosun's onboarding run walks you through identity, provider installation, repository sync, and secrets. The checklist updates in real time so you always know whether you're waiting on a GitHub App installation, a GitLab PAT, or the initial index job.

Save your progress

Leaving the onboarding flow halfway through is safe—the checklist resumes exactly where you stopped when you sign back in. You can open it any time from the top right menu.

  1. Sign in or create your account: Visit app.bosun.ai/login and pick the organization you want to administer. The login page remembers the onboarding state you left off in, so closing the tab mid-setup is safe—when you return, the checklist resumes exactly where you stopped.

  2. Choose your source control provider:

    • GitHub: Install the Bosun GitHub App when prompted. The onboarding flow verifies the installation, shows which repositories are enabled, and highlights any missing webhook permissions so you can fix them before running a task.
    • GitLab: Gitlab support is available for larger organizations on custom plans. Contact us for more information.

  3. Let the sync finish: Repository scans keep running after the first import, so you can leave the onboarding screen while Bosun walks the branch list, forks, and open pull requests/merge requests. Progress bars show which repositories are still indexing and which ones are ready to run manifests.

  4. Review Billing (Optional at Sign-Up): Organizations start with a 14-day trial. If you need to manage payment methods or check credit balances immediately, open the Billing screen in the app. Only members with billing access can view it; see Billing and Credits for details.

Your First Bosun task​

Let's create a simple task that uses a coding agent to create a file and then opens a draft pull request for it.

  1. Create your first task: In the app, click on Create New Task and add the following YAML configuration to define your task:
# This is your first Bosun task!
# It creates a new file and opens a draft pull request.

name: create-file-and-pr
description: A task to demonstrate a coding agent and pull request creation.

steps:
  - name: Create a new file
    agent:
      extends: Coding
      instructions: "Create a new file named 'hello-bosun.txt' in the root directory with the content 'Hello from Bosun! This file was created by an AI agent.'"
      role: "You are a helpful assistant that creates files."

  - name: Create a draft pull request
    agent:
      extends: Default
      role: "You create pull requests to prepare for automated work."
      instructions: "Create a draft pull request for the changes made by the previous step."
      toolboxes: [repository_read]
      tools:
        - name: create_pull_request
          extends: create_or_update_pull_request
          with:
            draft: true
  1. Run your task: Once the task is added, select it and use Start Task. The run produces hello-bosun.txt, a draft pull request, and the manifest metadata shown across the UI so teammates instantly recognise its purpose.

Next Steps​

With the basics covered, explore these sections to deepen your knowledge:

  • Concepts: Dive into the fundamental ideas behind Bosun, including Code Environments, Templating, and Variables.
  • Steps Reference: Learn about all available steps like agent, for-each, and run in detail.
  • Examples: Discover practical ways to automate recurring fixes.