Code Storage

Connect a Code Storage organization

Connecting a Code Storage organization requires Buildkite organization administrator access. Pipeline maintainer access alone does not grant permission to connect a repository provider.

Create a private API key in Code Storage

1. Sign in to your Code Storage dashboard.
2. Select Developers > Keys.
3. Create a new key for Buildkite, then copy its contents. Code Storage issues an ECDSA P-256 private key.

Connect Code Storage to Buildkite

1. Select Settings in the global navigation, then select Repository Providers.
2. Select Code Storage.
3. In Organization identifier, enter the organization name from your Code Storage dashboard URL. For example, enter acme for https://code.storage/acme/repositories.
4. In Private API key, paste the key you created in Code Storage.
5. Select Connect Code Storage.

Buildkite validates the key by listing the organization's repositories before saving the connection. If validation fails, check the organization identifier and key, then try again.

Only one connection can exist per Code Storage organization within a Buildkite organization.

Configure the webhook

A Code Storage connection needs a webhook to trigger builds from repository pushes. Configuring or replacing the webhook also requires organization administrator access.

1. From the connection settings page, select Configure webhook, or Replace webhook if a webhook is already configured.
2. Copy the Webhook URL shown in the dialog.
3. Follow the Code Storage webhooks link in the dialog. Create a webhook for the organization using the copied URL, with push events enabled.
4. Copy the signing secret that Code Storage generates for the webhook.
5. In Buildkite, paste the secret into Webhook secret, then select Save webhook.

Saving activates the new webhook URL and secret together. If you're replacing an existing webhook, the previous URL stops working as soon as you save, so remove it from Code Storage afterward.

Connecting Code Storage or replacing its private key does not affect an existing webhook.

Webhook status

The connection settings page shows the webhook status:

• Waiting for events: The webhook is configured but hasn't received a verified push yet.
• Active: The connection has verified a push with the current secret. Replacing the webhook resets the status to Waiting for events.

To inspect delivery history, select View deliveries in Code Storage on the connection settings page.

Replace the private key

To replace the private key:

1. Create a new key in your Code Storage dashboard, under Developers > Keys.
2. On the Code Storage connection settings page, select Replace Private Key.
3. Paste the new key, then select Replace Private Key.
4. Remove the previous key from your Code Storage dashboard.

Create a pipeline

After connecting Code Storage, create a pipeline from one of its repositories:

1. Select Pipelines > New Pipeline.
2. From Git scope, select the Code Storage connection. It appears as Code Storage (organization identifier).
3. From Repository, search for and select the repository.
4. Complete the remaining pipeline settings, then select Create pipeline.

Buildkite Pipelines saves the repository's canonical HTTPS checkout URL, for example https://acme.code.storage/team/app.git.

Change a pipeline repository

To associate an existing pipeline with a different Code Storage repository:

1. Select Pipelines > your pipeline > Settings > Code Storage.
2. In Repository Settings, select the Code Storage connection and repository.
3. Select Save Repository.

If the pipeline's Code Storage connection is disconnected or unavailable, reconnect the Code Storage organization to restore push builds, hosted-agent checkout, and Git notes delivery.

Buildkite organization administrators also see a Repository Provider panel below Repository Settings. Select Code Storage (organization identifier) to manage the matching organization connection. Pipeline editors who aren't organization administrators don't see this panel.

Configure build triggers

Select Pipelines > your pipeline > Settings > Code Storage. In Code Storage Settings, configure which events create builds:

• Build branches: Creates builds when commits are pushed to branches. This setting is enabled by default.
• Build tags: Creates builds when tags are pushed. This setting is disabled by default.

Select Save Code Storage Settings to apply your changes. You can also use a conditional expression or branch filter to limit which pushes create builds.

Deleted branches and tags don't create builds.

Code Storage triggers builds through the organization's webhook, so there's no per-pipeline webhook to configure.

Publish build status as Git notes

By default, Buildkite Pipelines publishes build status as a Git note on the build's commit. The note is a single line that links back to the build, for example:

[Build #3](https://buildkite.com/acme-inc/example-pipeline/builds/3) passed (1m 32s)

Is this Git notes format useful for your workflow? Would adding a JSON format option help? Share your feedback.

Buildkite Pipelines maintains one note for the latest build of each commit and pipeline, rather than a history of notifications. The note is updated when a build is created, starts, starts failing, finishes, or is skipped. Status text includes scheduled, started, is failing, passed, failed, canceled, skipped, and blocked states. Passed, failed, and blocked builds include the run time when it's available.

Notes can be temporarily absent while an update is retried. Use the build page in Buildkite Pipelines to check its current status.

For builds triggered from an annotated tag, the note is attached to the tag's underlying commit rather than the immutable tag object. The pipeline's checkout is unaffected and still uses the original tag.

Notes are published to refs/notes/buildkite/<org-slug>/<pipeline-slug> on the connected repository, using your Buildkite organization and pipeline slugs. Renaming either starts a new ref for future notes rather than moving existing ones. See the Code Storage Git notes documentation for how to read notes.

To stop a pipeline from publishing Git notes:

1. Select Pipelines > your pipeline > Settings > Code Storage.
2. In Code Storage Settings, clear Publish Git notes.
3. Select Save Code Storage Settings.

Disabling this setting stops future notes but doesn't remove existing notes or disable push builds and checkout.

Check out private repositories on hosted agents

Command jobs running on Buildkite hosted agents automatically receive a short-lived, read-only credential to check out a connected Code Storage repository. No SSH key or additional pipeline configuration is required.

Buildkite issues a credential scoped to the exact repository configured on the pipeline, valid for five minutes. Native authentication applies only to jobs running on Buildkite hosted agents.

Disconnect Code Storage

To disconnect a Code Storage organization:

1. Select Settings > Repository Providers > the Code Storage connection.
2. In Disconnect, select Disconnect.

Disconnecting stops webhook-triggered builds, hosted-agent checkout, and Git notes delivery for pipelines using that connection. Existing notes remain in the repositories. Disconnecting doesn't remove the private key or webhook from Code Storage. Remove those separately in your Code Storage dashboard if you no longer need them.