Skip to content

Document Zulip posting and EC2 instance spawning #808

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Kobzol merged 1 commit into from
Aug 5, 2026
Merged

Document Zulip posting and EC2 instance spawning #808

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 17 additions & 13 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,19 +12,23 @@ The production instance of the bot is deployed at https://bors-prod.rust-lang.ne

## Configuration
There are several parameters that can be configured when launching the bot. Parameters without a default value are
required.

| **CLI flag** | **Environment var.** | **Default** | **Description** |
|--------------------|-----------------------|-----------------------|------------------------------------------------------------------------------------------------------------------------|
| `--app-id` | `APP_ID` | | GitHub app ID of the bors bot. |
| `--private-key` | `PRIVATE_KEY` | | Private key of the GitHub app. |
| `--webhook-secret` | `WEBHOOK_SECRET` | | Key used to authenticate GitHub webhooks. |
| `--client-id` | `OAUTH_CLIENT_ID` | | GitHub OAuth client ID for rollup UI (optional). |
| `--client-secret` | `OAUTH_CLIENT_SECRET` | | GitHub OAuth client secret for rollup UI (optional). |
| `--db` | `DATABASE_URL` | | Database connection string. Only PostgreSQL is supported. |
| `--cmd-prefix` | `CMD_PREFIX` | @bors | Prefix used to invoke bors commands in PR comments. |
| `--web_url` | `WEB_URL` | http://localhost:8080 | Web URL where the bot's website is deployed (optional). |
| `--permissions` | `PERMISSIONS` | Rust Team API URL | Either a URL to the team v1 API or a path to a directory containing JSON files with try/review permissions (optional). |
required. Flags marked with `*` are required.

| **CLI flag** | **Environment var.** | **Default** | **Description** |
|------------------------|-----------------------|-----------------------|-------------------------------------------------------------------------------------------------------------|
| `--app-id` (*) | `APP_ID` | | GitHub app ID of the bors bot. |
| `--private-key` (*) | `PRIVATE_KEY` | | Private key of the GitHub app. |
| `--webhook-secret` (*) | `WEBHOOK_SECRET` | | Key used to authenticate GitHub webhooks. |
| `--client-id` | `OAUTH_CLIENT_ID` | | GitHub OAuth client ID for rollup UI. |
| `--client-secret` | `OAUTH_CLIENT_SECRET` | | GitHub OAuth client secret for rollup UI. |
| `--db` | `DATABASE_URL` | | Database connection string. Only PostgreSQL is supported. |
| `--cmd-prefix` | `CMD_PREFIX` | @bors | Prefix used to invoke bors commands in PR comments. |
| `--web_url` | `WEB_URL` | http://localhost:8080 | Web URL where the bot's website is deployed. |
| `--permissions` | `PERMISSIONS` | Rust Team API URL | Either a URL to the team v1 API or a path to a directory containing JSON files with try/review permissions. |
| `--zulip-username` | `ZULIP_USERNAME` | | Zulip account username for posting Zulip messages. |
| `--zulip-token` | `ZULIP_TOKEN` | | Zulip account token for posting Zulip messages. |
| `--zulip-server` | `ZULIP_SERVER` | | Zulip server URL for posting Zulip messages. |
| `--ec2-role` | `CI_EC2_RUNNER_ROLE` | | AWS ARN role used to authenticate `aws` commands. | |

### Special branches
The bot uses the following branch names for its operations.
Expand Down
14 changes: 14 additions & 0 deletions docs/design.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -210,3 +210,17 @@ To make the implementation more robust, it now behaves as follow:
Note that we explicitly do not read the "Check suite was completed" webhook, because it can actually be received *before* a webhook that tells us that the last workflow of that check suite was completed. If that happens, we could mark a build as completed without knowing the final conclusion of its workflows. That is not a big problem, but it would mean that we sometimes cannot post the real status of a workflow in the "build completed" bors comment on GitHub. So instead we just listen for the completed workflows.

In any case, with new bors there is no need to introduce fake conclusion CI jobs.

## Zulip messages

Bors can post certain messages (e.g. tree of a repo being open/closed) to Zulip. You can configure this via three environment variables. See [README.md](../README.md) for more information.

## EC2 instance spawning
Bors can spawn and manage the lifecycle of EC2 instances with self-hosted GitHub runners for executing GitHub Actions jobs.
To enable this functionality, set the `CI_EC2_RUNNER_ROLE` environment variable and configure the `ec2_runners` section in the config file.

Then you can use a special value for the `os` field of GHA jobs, which will tell bors to spawn an EC2 instance to run the job.
This value is documented in `rust-bors.example.toml`.

Bors will start the EC2 instance when the job starts; the instance should end by itself once the job ends. Bors also periodically monitors all spawned instances, and it will terminate instances that have been running for a long time.
It will also observe jobs that have been waiting for an EC2 instance for a long time (this can happen e.g. when the workflow job started webhook doesn't arrive) and backfill EC2 instances for them.
26 changes: 26 additions & 0 deletions rust-bors.example.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,3 +33,29 @@ try_failed = []
auto_build_succeeded = { modifications = ["+foo", "+bar"], unless = ["baz"] }
auto_build_failed = ["+foo", "+bar"]
conflict = ["+conflict"]

# Configuration for launching self-hosted GitHub runners on EC2.
[ec2_runners]
# GitHub self-hosted runner group ID.
# Note that it should be configured to work on the branches for which bors will spawn the EC2
# runners!
runner_group_id = 1
# Prefix of the `os` label of GitHub Actions jobs.
# If the `os` field of a job begins with this prefix, bors will attempt to parse the `os` field
# and use its information to configure the EC2 instance.
# The format of the label should be `<prefix>-<image-name>-<instance-type>-<label>`.
label_prefix = "ec2"
# Region where the EC2 instance will be spawned.
region = "us-east-2"
# Map of image names to AMI IDs.
# If you specify `ubuntu26.04` as the image name with the config below, bors will start an EC2
# instance with the given AMI ID.
images = {
"ubuntu26.04" = "/aws/service/canonical/ubuntu/server/26.04/stable/current/amd64/hvm/ebs-gp3/ami-id"
}
# Whether the self-hosted GitHub runner should be started with a repository or an organization
# JIT config.
# Use organization for production deployments, and repository for local testing.
jit_runner = "organization" # "repository" or "organization"
# Allowed EC2 instance types that can be used in the `<instance-type>` field of the `os` label.
allowed_instances = ["c8a.12xlarge"]
3 changes: 2 additions & 1 deletion src/bin/bors.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,8 @@ struct Opts {
)]
permissions: String,

/// Optional EC2 role that will be used when
/// Set this to an AWS EC2 ARN role to be assumed when executing AWS commands.
/// Setting this variable is required to enable the EC2 instance spawning functionality.
#[arg(long, env = "CI_EC2_RUNNER_ROLE")]
ec2_role: Option<String>,
}
Expand Down