Repositories
Add GitLab or GitHub repositories so Bilbis has a codebase to work on.
What this means
A repository is a codebase Bilbis can work in. Each pipeline targets one repository, even when the product contains many repositories.
Repositories belong to products. The product stores shared defaults, while each repository stores provider-specific details like path, default branch, commands, and structure hints.
When to use it
Add or edit repositories when:
- You are completing the setup checklist.
- A new codebase should be available for pipelines.
- The default branch, commands, or repo path changed.
- You want to give Bilbis better hints about how the codebase is organized.
Before you start
You need:
- Owner or admin access.
- A product.
- A GitLab or GitHub credential for the provider where the repo lives.
- Provider-side access to the repo.
Field reference
| Field | What it means | Default |
|---|---|---|
| Repo path | Full path on GitLab or GitHub, such as acme/api or acme-org/acme-api. | Required |
| Repo id | Stable lowercase identifier users see in Bilbis. It cannot be changed after creation. | Derived from repo path |
| Provider | GitLab or GitHub. | GitLab |
| Default branch | Base branch Bilbis starts from and usually targets. | master or discovered provider default |
| Stack hints | Comma-separated language and framework tags. | Empty |
| Description | Short explanation of what the repository does. | Empty |
| Structure hints | Notes about where routes, tests, modules, or conventions live. | Empty |
| Test command | Command Bilbis should run after changes. | Empty |
| Lint command | Command Bilbis should run for linting. | Empty |
| Build command | Command Bilbis should run to build the project. | Empty |
| Skip CI | Tells Bilbis not to rely on CI for this repo. | Off |
Steps
- Open Products.
- Choose the product that should contain the repository.
- Select Add repo.
- Pick a discovered repository if available, or enter the repo details manually.
- Confirm the provider and default branch.
- Add stack, command, or structure hints if they will help Bilbis work safely.
- Save the repository.
What happens next
The repository becomes available in pipeline creation. Users can choose it directly, or use auto-route workflows where Bilbis chooses from multiple candidate repositories.
Better repository hints usually make pipelines easier to interpret and recover. They tell Bilbis what the service does, where important files live, and which commands prove that the change works.
Languages
Each repository row on the product detail page shows a language breakdown when one is available. Bilbis fetches the breakdown from the Git provider's languages API using the org's BYOK token.
| Element | What it means |
|---|---|
| Stacked bar | Horizontal bar (GitHub style) where each segment's width matches the language's percentage. Hover a segment for the exact percent. |
| Legend | Each language with a colored dot and percent, sorted by percent descending. |
| Updated time | Relative timestamp showing when the breakdown was last fetched, for example Updated 3 days ago. |
| Stale badge | Amber badge that appears when the breakdown is older than 30 days. Refresh to clear it. |
| Refresh languages button | Admin or owner only. Re-fetches the breakdown from the provider. |
If the repository has no breakdown yet, the section shows a small prompt instead. Click Refresh languages to populate it.
Refresh languages
The button calls the provider's languages API with the BYOK token for that provider and writes the result to the repository row.
| Outcome | What it means |
|---|---|
| Languages refreshed | Provider returned a breakdown and Bilbis stored it. The bar updates immediately. |
| Couldn't fetch — check BYOK token has repo read scope | Provider rejected the call. Open Settings -> Integrations and confirm the GitLab or GitHub credential has read access to the repo. Validating the credential there can help isolate the cause. |
Refresh is admin or owner only. Developers and viewers see the breakdown but no button.
When to refresh
- After a major language migration in the repo.
- After fixing or rotating the BYOK Git credential.
- When the Stale badge has been showing for a while and you want a current value.
Bilbis does not auto-refresh the breakdown. It updates only when an admin clicks the button.
Problems and fixes
| Problem | What to check |
|---|---|
| Provider option is disabled | Add the matching GitLab or GitHub credential in Settings -> Integrations. |
| Repo path already exists | The same provider/path is already connected in this organization. |
| Repo id already exists | Choose a different repo id. It must be unique inside the organization. |
| Pipeline cannot find the default branch | Check the default branch field and provider-side branch name. |
| Pipeline changes the wrong area | Add description and structure hints so Bilbis has more context. |
| Tests are not running | Add or fix the test, lint, and build commands for the repository. |
| Refresh languages returned an error | The BYOK Git credential lacks repo read scope, or the token is invalid. Re-check the credential in Settings -> Integrations. |
| Languages section shows a stale badge | Click Refresh languages to fetch the current breakdown. The badge clears once the fetch succeeds. |
| Refresh languages button is missing | Refresh is admin or owner only. Developers and viewers see the breakdown but cannot refresh. |