Connect a repository

What BLOM reads

BLOM uses read access to four things in GitHub: Contents, Metadata, Pull requests, and Checks. From a connected repository, it reads:

Specs and other documents

The Markdown files on the document branch. A file whose header names a BLOM document, such as ID: P-Spec 1-2, is read as that document, at the commit BLOM read it from. See Specs and their revisions.

Pull requests and merges

Each pull request's state and branches, and each merge with its commit.

Direct pushes

Pushes to the branches you watch.

Check results

Each check's status and conclusion.

All of it is a record of what GitHub reported. It approves, verifies, and completes nothing. A merge records integration into a branch, never an approval or a completion.

What BLOM never does in GitHub

• It never writes to the repository. Its requests to GitHub only read, so it makes no commit, branch, comment, review, or check of its own.
• It never uses more than read access. If the App's installation grants more, the connection says Wider than BLOM uses, and BLOM still only reads.
• It never changes GitHub when you disconnect. BLOM's GitHub App stays installed until you remove it in GitHub.

Before you start

• You're an Administrator in BLOM.
• You sign in to BLOM with GitHub. BLOM checks access with that GitHub account.
• Your GitHub account administers the repository.
• BLOM's GitHub App is installed on the repository, or you can install it there. The steps below link to it.

Connect it

1. Open Connected tools

   At the rail's foot, select Organization, then Connected tools, and select Connect a repository.

2. Install BLOM's GitHub App

   If it isn't installed on the repository yet, select Install BLOM's GitHub App and choose repositories. In GitHub, install it on the repository, then come back.

3. Choose the product and the repository

   Choose the Product the repository belongs to, such as Member onboarding. Enter the Repository owner and Repository name, such as harbor-labs and member-onboarding.

4. Select Check access

   BLOM checks that its App can read the repository and that your GitHub account administers it. It shows Access checked, the repository's default branch, and what BLOM will observe. Select Continue.

5. Choose the accountable person, and check the settings

   Choose the Accountable person, the person the connection answers to. Then check the Document branch, Excluded paths, and Watched branches. Both branches start as the default branch, with no excluded paths. Select Review connection.

6. Review it, and connect

   Check what you chose, give a Reason, and select Connect repository. BLOM opens the connection's page and starts reading.

A repository connects to one product. BLOM records what it reads under the connection's own service identity, named for the repository, such as GitHub harbor-labs/member-onboarding, with the accountable person beside it.

The connection's settings

Document branch

The branch BLOM reads specs and other documents from.

Excluded paths

Files or folders BLOM doesn't read documents from, one per line, each with its reason.

Watched branches

The branches BLOM watches for pushes, one per line.

To change them, open the connection and select Edit settings, then Review changes. Give a Reason and select Save settings. BLOM uses the new settings from its next read, and what it read before stays as it was.

Your organization's standards source

One repository can be your organization's standards source: the one BLOM reads organization-wide standards from. An Administrator of the organization ticks The organization's standards source while connecting, or selects Name as standards source on a connection. To connect a repository for standards alone, choose Organization standards only under Product, and tick The organization's standards source. See Standards.

Condition and history

Connected tools lists each repository with its product, its condition, its last successful read, its access, and its accountable person. A product with no repository shows ○ Never connected. Select a repository to open its page.

Condition

Gaps stay visible. Whenever a repository isn't connected, its page names the observations that are unavailable, and says that changes since the last successful read are unknown. When GitHub limits BLOM's requests, the page says its observations are stale. Reload connection reads the condition again.

History

The connection's History lists every change to it, newest first: who made it, a person or the connection's service identity, through which channel, with the reason and the authority used, and each setting before and after. Older history shows more.

On a task's page

A task's page lists what GitHub reported for it under GitHub observations: the pull requests, merges, pushes, and checks on the branches and pull requests linked to it. To link them, add them when you complete a step, under Code references (optional): a repository, a branch, and, if there is one, a pull request number. An observation alone never completes a step.

Disconnect or reconnect

An Administrator can disconnect a repository, and reconnect it later.

• Disconnect. Open the connection, select Disconnect, give a Reason, and select Disconnect repository. BLOM stops reading, and every observation and record it read stays. The service identity reads Inactive, and nothing changes in GitHub.
• Reconnect. Open the connection, select Reconnect, then Check access. Give a Reason and select Reconnect repository. Reconnecting keeps the connection, its service identity, and what BLOM read before. An inaccessible or deleted repository's connection offers Reconnect too.

Related