# Quick Start: Platform & Security

This guide sets Bumpkit up for a whole organization. You set one release policy for every repository, connect your identity provider, give people the right roles, and hand evidence to your SIEM and your auditor.

Most of these steps are Beta, and each one has its own flag. Beta features are in early access: the feature's dashboard page or tab offers **Sign me up for early access**, and we email you when it's on. Run `bumpkit features` to see which are on for your workspace. SSO, SCIM, SIEM, signed evidence and auditor access are part of the Enterprise contract. While they're Beta, Bumpkit turns each one on per workspace through early access.

You need:

- The `bumpkit` CLI, signed in as a workspace owner. See [Getting Started](/docs/).
- The Bumpkit GitHub App on your repositories, so the gate runs on every pull request. See [Quick Start: Engineering Leads](/docs/quickstart-engineering).
- Access to your identity provider and your DNS, for SSO.

## 1. Set an org policy and lock keys

> **Beta, early access.** A workspace without access gets `403 FEATURE_EARLY_ACCESS` and a link to request it. Flag: `org_policies`.

An org policy is one `bumpkit.yml` for the whole workspace. Each repository's own `bumpkit.yml` is merged with it. A locked key can only be made stricter by a repository, never looser.

Owners can change the org policy. With roles on, admins and policy admins can too.

1. Write the policy in a file, for example `org-policy.yml`:

   ```yaml
   locked:
     - block_on
     - require_checks
     - on_error
   gate:
     block_on: [secret, data_loss]
     require_checks: [ci/test]
     on_error: fail
   ```

   Replace `ci/test` with the name of a CI check every repository runs.

2. Save it:

   ```bash
   bumpkit policy set org-policy.yml --message "Block secrets and require CI everywhere"
   ```

   Bumpkit checks the file, shows the diff and asks you to confirm. Each save is a new version, kept with your message and in the audit log.

3. In any repository, see the policy the gate will apply there:

   ```bash
   bumpkit policy show --effective
   ```

   The `FROM` column shows where each value came from: `default`, `org`, `repo` or `org+repo`. If a repository tries to loosen a locked key, the line explains why it was ignored.

You can keep the policy in a config repository instead, such as `acme/.github`, with `bumpkit policy set --repository acme/.github`. To stop releases during an incident or a holiday, see [change freezes](/docs/org-policies#release-windows-and-change-freezes). For the full merge rules, see [Org Policies & Freezes](/docs/org-policies).

## 2. Set up single sign-on

> **Beta, early access.** A workspace without access gets `403 FEATURE_EARLY_ACCESS` and a link to request it. Flag: `sso`.

Owners and admins set up SSO in the dashboard under **Settings → Single sign-on** (`/settings/sso`). Bumpkit supports OpenID Connect and SAML 2.0.

1. **Verify your email domain.** Under **Verified domains**, add your domain, such as `example.com`. Publish the TXT record Bumpkit shows:

   ```text
   _bumpkit-challenge.example.com  TXT  "bumpkit-domain-verification=<token>"
   ```

   Click **Verify** once the record resolves.

2. **For OIDC:** register Bumpkit in your identity provider as a web application, with the redirect URI `https://dashboard.bumpkit.dev/auth/sso/oidc/callback` and the scopes `openid email profile`. Then fill in Bumpkit's form with the issuer URL, client ID and client secret.
3. **For SAML:** fill in Bumpkit's form with your identity provider's entity ID, SSO URL and signing certificate, and save. Then copy the entity ID, ACS URL and metadata URL that appear on the settings page into your identity provider. They contain the connection ID, which exists only after the first save.
4. **Choose how accounts are created.** Pick the role for new members, and whether accounts are created on first sign-in.
5. **Turn on single sign-on**, then test it. Open `/login/sso` in a private window and sign in with your work email.
6. **Require SSO** once sign-in works. Members on your verified domains can then only sign in through your identity provider.

If your identity provider is down, owners can still sign in with a password at `/login/break-glass`. Each such sign-in is recorded in the audit log. For every field and attribute, see [Single sign-on](/docs/sso#single-sign-on).

## 3. Connect SCIM

> **Beta, early access.** A workspace without access gets `403 FEATURE_EARLY_ACCESS` and a link to request it. Flag: `scim`.

SCIM lets your identity provider add, update and deactivate members for you.

1. On the same **Single sign-on** page, under SCIM, create a token with a label such as `Okta`. Copy it. It starts with `bk_scim_` and is shown once.
2. In your identity provider, set the base URL to `https://bumpkit.dev/scim/v2`.
3. Set authentication to a bearer token, using the token you copied.
4. Set the unique identifier to `userName`, the person's email.

Only users on your verified domains are accepted. Deactivating a user in your identity provider stops their sign-in and revokes their API keys. See [SCIM provisioning](/docs/sso#scim-provisioning).

## 4. Assign roles

> **Beta, early access.** A workspace without access gets `403 FEATURE_EARLY_ACCESS` and a link to request it. Flag: `roles`.

With roles on, each member has one of seven roles: `owner`, `org_admin`, `policy_admin`, `approver`, `member`, `viewer` or `auditor`. Owners and admins assign them.

Sign in to the dashboard and open the **Team** page to give someone a role, or to invite them with one. A person has to grant a role above `member`, so the CLI, an API key or an agent gets `HUMAN_APPROVAL_REQUIRED` and can only invite as `member` or `viewer`:

```bash
bumpkit team invite sam@example.com
```

With SCIM connected, map your identity provider's groups to roles under **Groups to roles** instead, so roles follow group membership. Moving someone to `viewer` or `auditor` revokes their API keys. See [Roles](/docs/sso#roles) for what each role can do.

## 5. Export evidence

> **Beta, early access.** A workspace without access gets `403 FEATURE_EARLY_ACCESS` and a link to request it. Flag: `compliance_export`.

The evidence export lists every release in a period: who or what wrote it, what Bumpkit found, the gate decision and who approved it. Records are tamper-evident, so any edit or removal shows.

1. Export the last 90 days:

   ```bash
   bumpkit evidence export --days 90 -o evidence.json
   ```

2. Or export a quarter as CSV:

   ```bash
   bumpkit evidence export --from 2026-07-01 --to 2026-09-30 --format csv -o q3.csv
   ```

Owners, admins and auditors can also download it from the **Compliance evidence** card on the dashboard's Settings page. Over the API, the key must belong to one of those roles; other keys, including CI keys, get `403 ROLE_REQUIRED`.

### Signed bundles

> **Beta, early access.** A workspace without access gets `403 FEATURE_EARLY_ACCESS` and a link to request it. Flag: `signed_evidence`.

A signed bundle also proves who produced the evidence:

```bash
bumpkit evidence export --signed --days 365 -o evidence.zip
bumpkit evidence verify evidence.zip --public-key-file bumpkit-key.json
```

`bumpkit evidence verify` works offline. See [Compliance Evidence](/docs/compliance#signed-evidence) for what the bundle holds and how to pin the signer's key.

## 6. Stream audit events to your SIEM

> **Beta, early access.** A workspace without access gets `403 FEATURE_EARLY_ACCESS` and a link to request it. Flag: `siem_streaming`.

Bumpkit sends audit events, gate decisions, approvals and overrides to your SIEM as they happen. Owners and admins set this up.

1. In the dashboard, open **Settings**. On the **Audit log delivery** card, click **Configure**.
2. Pick a type: **Splunk HTTP Event Collector**, **Datadog Logs**, **Webhook (HMAC-signed)** or **S3-compatible storage**.
3. Enter a name, the URL and the token, API key or secret. For S3, also open the options and set the bucket and access key ID.
4. Click **Add destination**.
5. Click **Send test** on the new destination, and check that the event arrives.

Streaming starts from the next event. Failed batches are retried, then kept so you can redeliver them from the same page. See [Audit streaming](/docs/compliance#audit-streaming) for the event format and signatures.

## 7. Give an auditor access

> **Beta, early access.** A workspace without access gets `403 FEATURE_EARLY_ACCESS` and a link to request it. Flag: `auditor_access`.

Give your auditor a read-only link instead of an account.

1. In the dashboard, open **Settings** and find the **Auditor access** card.
2. Enter the auditor or audit firm's name, and how many days the link lasts (1 to 90).
3. Click **Create link**, and copy it. It is shown once.
4. Send the link to your auditor.

The link shows compliance evidence, agent governance and the audit log only. Every visit and download is recorded in your audit log. Revoke the link at any time from the same card.

If your auditor needs to sign in, invite them as a member with the `auditor` role instead (step 4). See [Auditor access](/docs/compliance#auditor-access).

## Next steps

- Decide what happens to data sent to Bumpkit: [Data Handling](/docs/data-handling).
- Connect Jira, ServiceNow, Vanta or Drata: [Change management](/docs/jira).
- Review emergency changes after the fact: [Hotfixes & Break Glass](/docs/hotfixes#post-hoc-review).
- See how all the pieces fit: [How Bumpkit Works](/docs/how-it-works).