Automate Repository Setup

Add a repository and assign its team, routine, branches, and Policy Groups with the BIMP API.

Use this workflow when you need to add repositories repeatedly without opening the BIMP repository picker. Each run discovers the provider repository, adds it to BIMP with an owning team and routine, and assigns Policy Groups to its tracked branches.

The API adds one repository per request. For bulk onboarding, repeat the create and Policy Group assignment requests for each approved repository.

Before you begin

You need:

an active GitHub or GitLab connection in the BIMP organization;
the team, routine, and Policy Groups that you want to assign;
an API key for that organization; and
curl and jq in the environment running the automation.

The API key needs read access to VCS connections, teams, routines, Policy Groups, and repositories. It also needs permission to manage repositories and repository Policy Group assignments. See Access the BIMP API for API key setup and error guidance.

Set the values shared by the examples:

export BIMP_API_URL="https://<your-bimp-host>"
export BIMP_ORGANIZATION_ID="<organization-id>"
# Load BIMP_API_KEY from your secret manager.

Do not put the API key in a script, repository, or build log. Load it from your secret manager in production automation.

1. Find the code provider connection

List the active GitHub and GitLab connections in the organization:

curl --fail-with-body --silent --show-error \
  --header "x-api-key: $BIMP_API_KEY" \
  --header "accept: application/json" \
  "$BIMP_API_URL/api/v1/org/$BIMP_ORGANIZATION_ID/vcs-connections" \
  | jq '.items[] | {id, provider, account: .externalAccountName, status}'

Choose the active connection for the account that owns the repository, then store its id:

export BIMP_VCS_CONNECTION_ID="<vcs-connection-id>"

If the connection is missing, connect GitHub or GitLab in BIMP before continuing. The repository API does not create a provider connection.

2. Find the repository and branches

List repositories available through the selected connection:

curl --fail-with-body --silent --show-error \
  --header "x-api-key: $BIMP_API_KEY" \
  --header "accept: application/json" \
  "$BIMP_API_URL/api/v1/org/$BIMP_ORGANIZATION_ID/vcs-connections/"\
"$BIMP_VCS_CONNECTION_ID/available-repos" \
  | jq '.items[] | {externalRepoId, fullName, defaultBranch, tracked}'

Find the repository by its complete provider name, such as acme/payments. Store the returned values:

export BIMP_EXTERNAL_REPOSITORY_ID="<external-repository-id>"
export BIMP_REPOSITORY_FULL_NAME="acme/payments"
export BIMP_DEFAULT_BRANCH="main"

The external repository ID comes from GitHub or GitLab. Do not substitute a BIMP repository ID or derive the value from the repository name.

If a recently granted repository is absent, repeat the list request once with ?refresh=1. Refreshing contacts the provider and uses its API quota, so do not add it to every polling request.

List the repository’s available branches:

curl --fail-with-body --silent --show-error --get \
  --header "x-api-key: $BIMP_API_KEY" \
  --header "accept: application/json" \
  --data-urlencode "repositoryFullName=$BIMP_REPOSITORY_FULL_NAME" \
  --data-urlencode "defaultBranch=$BIMP_DEFAULT_BRANCH" \
  "$BIMP_API_URL/api/v1/org/$BIMP_ORGANIZATION_ID/vcs-connections/"\
"$BIMP_VCS_CONNECTION_ID/available-branches" \
  | jq '.items[] | {name, isDefault}'

Choose every branch that BIMP should track. You must include the provider’s default branch.

3. Find the team and routine

List the organization’s teams:

curl --fail-with-body --silent --show-error \
  --header "x-api-key: $BIMP_API_KEY" \
  --header "accept: application/json" \
  "$BIMP_API_URL/api/v1/org/$BIMP_ORGANIZATION_ID/teams" \
  | jq '.items[] | {id, name}'

Store the ID of the team that will own the repository:

export BIMP_TEAM_ID="<team-id>"

Routines belong to teams. List the selected team’s routines:

curl --fail-with-body --silent --show-error \
  --header "x-api-key: $BIMP_API_KEY" \
  --header "accept: application/json" \
  "$BIMP_API_URL/api/v1/org/$BIMP_ORGANIZATION_ID/teams/$BIMP_TEAM_ID/routines" \
  | jq '.items[] | {id, name, active, intervalDays}'

Choose the routine that should set the repository’s operating cadence, then store its ID:

export BIMP_ROUTINE_ID="<routine-id>"

The routine must belong to BIMP_TEAM_ID. BIMP rejects a routine from another team, or a routine assignment without a team assignment.

4. Find the Policy Groups

List the Policy Groups in the organization:

curl --fail-with-body --silent --show-error \
  --header "x-api-key: $BIMP_API_KEY" \
  --header "accept: application/json" \
  "$BIMP_API_URL/api/v1/org/$BIMP_ORGANIZATION_ID/policy-groups" \
  | jq '.items[] | {id, name, applyToAllRepos}'

Store the IDs of the repository-specific Policy Groups you want to assign:

export BIMP_BASE_POLICY_GROUP_ID="<policy-group-id>"
export BIMP_RELEASE_POLICY_GROUP_ID="<policy-group-id>"

Do not explicitly assign a Policy Group whose applyToAllRepos value is true. It already applies to every repository, and the assignment endpoint rejects it as an individual repository assignment.

5. Add the repository

Create the tracked repository with its team, routine, and branches in the same request. This example tracks the provider’s default branch and release:

BIMP_REPOSITORY_RESPONSE="$(
  curl --fail-with-body --silent --show-error \
    --request POST \
    --header "x-api-key: $BIMP_API_KEY" \
    --header "accept: application/json" \
    --header "content-type: application/json" \
    --data-binary @- \
    "$BIMP_API_URL/api/v1/org/$BIMP_ORGANIZATION_ID/repositories" <<JSON
{
  "vcsConnectionId": "$BIMP_VCS_CONNECTION_ID",
  "externalRepoId": "$BIMP_EXTERNAL_REPOSITORY_ID",
  "assignedTeamId": "$BIMP_TEAM_ID",
  "assignedRoutineId": "$BIMP_ROUTINE_ID",
  "branchNames": ["$BIMP_DEFAULT_BRANCH", "release"]
}
JSON
)"

export BIMP_REPOSITORY_ID="$(
  printf '%s' "$BIMP_REPOSITORY_RESPONSE" | jq -er '.repository.id'
)"

Replace the branch names with the exact names returned by branch discovery. The response returns the new BIMP repository ID and shows each initial branch scan as queued. Keep the BIMP repository ID for the next request; it is different from the provider’s external repository ID.

If the request returns 409 Conflict, the repository is already tracked. Do not create a duplicate. Find its BIMP ID with the repositories endpoint, then continue with the assignment check described below.

6. Assign Policy Groups to tracked branches

Assign repository-specific Policy Groups and identify the tracked branches to which each group applies:

curl --fail-with-body --silent --show-error \
  --request POST \
  --header "x-api-key: $BIMP_API_KEY" \
  --header "accept: application/json" \
  --header "content-type: application/json" \
  --data-binary @- \
  "$BIMP_API_URL/api/v1/org/$BIMP_ORGANIZATION_ID/repositories/"\
"$BIMP_REPOSITORY_ID/policy-groups" <<JSON
{
  "assignments": [
    {
      "policyGroupId": "$BIMP_BASE_POLICY_GROUP_ID",
      "branchNames": ["$BIMP_DEFAULT_BRANCH", "release"]
    },
    {
      "policyGroupId": "$BIMP_RELEASE_POLICY_GROUP_ID",
      "branchNames": ["release"]
    }
  ]
}
JSON

This request sets the complete collection of repository-specific Policy Group assignments for the repository. Include every assignment that should remain. Omitting a previous Policy Group or branch removes that assignment. An empty assignments array removes all repository-specific assignments without changing Policy Groups that apply to all repositories.

Every branchNames value must be a branch already tracked in BIMP. Assigning a provider branch that was not included when the repository was added returns a validation error.

7. Verify the completed setup

Confirm the owning team, routine, and tracked branches:

curl --fail-with-body --silent --show-error \
  --header "x-api-key: $BIMP_API_KEY" \
  --header "accept: application/json" \
  "$BIMP_API_URL/api/v1/org/$BIMP_ORGANIZATION_ID/repositories"\
"?repositoryId=$BIMP_REPOSITORY_ID" \
  | jq '.items[] | {
      id,
      fullName,
      assignedTeamId,
      assignedRoutineId,
      branches: [.branches[] | {branchName, scan: .scan.status}]
    }'

Confirm the effective Policy Group assignments:

curl --fail-with-body --silent --show-error \
  --header "x-api-key: $BIMP_API_KEY" \
  --header "accept: application/json" \
  "$BIMP_API_URL/api/v1/org/$BIMP_ORGANIZATION_ID/repositories/"\
"$BIMP_REPOSITORY_ID/policy-groups" \
  | jq '{trackedBranchNames, policyGroups: [.items[] | {
      id,
      name,
      source,
      branchNames,
      assignmentState
    }]}'

Policy Groups with source: "all_repositories" apply through organization configuration. Groups with source: "repository_assignment" are the explicit branch assignments made by the automation.

Run the workflow in bulk

For multiple repositories, keep the discovery results as the source of each externalRepoId, default branch, and available branch list. Run steps 5–7 once per repository and record the BIMP repository ID returned by each create request.

Treat the create request and the Policy Group assignment request as two separate operations. If creation succeeds but assignment fails, retain the returned repository ID and retry only the assignment. A 409 Conflict on a create retry means the repository is already tracked; it does not confirm that its team, routine, or Policy Groups match the intended configuration.

Before rerunning Policy Group assignment against an existing repository, read its current assignments and merge any settings that must remain into the complete assignments body.

Automate Repository Setup

Before you begin

1. Find the code provider connection

2. Find the repository and branches

3. Find the team and routine

4. Find the Policy Groups

5. Add the repository

6. Assign Policy Groups to tracked branches

7. Verify the completed setup

Run the workflow in bulk

Introduction

Quickstart

Setup BIMP

Operate BIMP

Reference