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. When you connect more than one repository—whether for fundamentals runs or bespoke manifests—each repo indexes independently. The onboarding checklist and the Repositories page both show per-repo progress so you always know which ones are still syncing and which ones are ready to run manifests. Sync jobs continue even if you close the browser, so fundamentals workflows stay up to date as new branches land.

  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.

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.'"

  - name: Create a draft pull request
    agent:
      extends: pull_request
      instructions: "Create a draft pull request for the changes made by the previous step."

  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. The file surfaces in the session log and the Artifacts tab so you can reuse it later—see Producing Artifacts for the broader workflow.

  2. Keep the task list tidy: When the project grows beyond a few workflows, archive completed or experimental tasks straight from the task list. Archived tasks disappear from the default view so teammates focus on active automations, but they remain available under Show archived if you need to restore them. The list is always ordered by each task’s most recent update, so fresh edits and newly restored tasks float to the top automatically.

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.