# GitHub

> Explain source, engineering work and deployment evidence beside the component in your diagram.

Link the repository behind a component to its Stratum. Choose the branch,
workflow, issue labels, deployment environment and source path that explain that
component. Your diagram stays the starting point; GitHub provides dated evidence
and links for further investigation.

## Connect repository reads

1. In the owning organisation or team, open **Settings → Continuum → Operational
   integrations → New integration**, and select **GitHub**. Continuum Link needs
   an Enterprise plan and `continuum_integrations.manage` on the connection
   owner. Linking a repository later also requires blueprint edit access.
2. Create a [fine-grained personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
   for the intended resource owner and selected repositories. Obtain any required
   organisation approval. Use a dedicated integration credential with an expiry
   you can maintain. GitHub sign-in does not grant repository access to Link.
3. Enter a **Repository to verify**, as `owner/repository` or its GitHub HTTPS
   link. This is a verification sample; other linked repositories are checked
   when selected. An optional **Organization** restricts discovery and
   linking to that owner. Without one, the suggestion index keeps the names of
   every repository the token can list. Set an organization, or limit a
   fine-grained token to selected repositories, to narrow it.
4. Choose the reads to enable and grant their corresponding permissions below.
   Keep **Blueprint editors only** and **Summary** unless the wider content and
   audience are appropriate. Paste the token and choose **Connect & verify**.

| Read | Fine-grained repository permission | Default |
| --- | --- | --- |
| Repository identity and visibility | Metadata: read | Always |
| Open issues | Issues: read | Enabled |
| Workflow runs | Actions: read | Enabled |
| Open pull requests | Pull requests: read | Off |
| Deployment attempts and reported statuses | Deployments: read | Off |
| Latest branch/path commit and latest stable release | Contents: read | Off |

Contents permission also grants access to code, so turn it on only for the
commit and release rows. Link does not create issues, run workflows or change
the repository. Verification checks each enabled read, not only that the token
is valid. Empty accessible lists
are valid. This path supports **GitHub.com**; GitHub Enterprise Server and
GHE.com are not supported. See GitHub's
[permission reference](https://docs.github.com/en/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens).

## Choose the context for a component

Save the blueprint and open **Continuum Link** from the Stratum's **+ Add tab**
menu. Search a repository name, paste `owner/repository`, or paste its GitHub.com
URL. A child URL such as an issue or pull request selects its containing
repository, not an individual work item. Scan and Suggest also propose
repository links for you to review.

Open **Choose the context for this component** before linking:

| Selection | What it means |
| --- | --- |
| Branch | Filters workflow runs and PR base branches. A known default branch is prefilled. Clearing it includes all workflow branches and PR bases; commit reads then use the default branch. |
| Workflow ID or filename | Selects the workflow whose result matters, for example `deploy.yml`. Without it, recent runs from different workflows are neutral repository context. |
| Deployment environment | Shows recorded deployment attempts for an exact environment such as `production`. Blank includes all environments. |
| Issue and PR labels | Every comma-separated label must match. Counts describe the retrieved matching scope. |
| Source directory or file | Links to the component's code and scopes the optional latest commit. It does not filter PRs, workflows or deployments. |

One connection can bind one repository/context to a Stratum. Re-select and link
it to change the context. The repository's numeric ID protects against an old
name being reused for a different repository. An old link without sufficient
identity evidence asks you to re-select before it can refresh.

## Read the evidence

| Task | How the tab helps |
| --- | --- |
| Explain a service | Shows its source path and branch, scoped open work and the selected workflow beside the service's architecture. Open GitHub for code, reviews, checks, comments and logs. |
| Review a release | Compares branch commit, CI result, recorded deployment attempts and GitHub's latest stable release. These are separate facts. A successful workflow or published release does not prove what is serving production or that the runtime is healthy. |
| Act on a diagram review | Create a GitHub follow-up from the Stratum, review the destination and text, and keep a link to the created issue beside it. |

Issues and pull requests appear separately. GitHub's repository-wide open count
is explicitly labelled **issues + PRs**. Open-work lists retrieve up to 300
records per section and display at most ten; coverage distinguishes exact
matching counts, bounded samples and unavailable reads. Run history shows up
to ten entries; deployment evidence shows up to three attempts and their latest
reported statuses. GitHub's issue-list retrieval limit includes PR records that
are removed from the issue section. PR label counts are exact only when the
queried PR list was retrieved in full. Missing information is not a healthy zero.

Opening the tab shows a saved snapshot. Use the circular-arrows button to fetch
again. After fifteen minutes the snapshot asks for a refresh; it does not poll.
If repository identity or metadata cannot be read safely, the previous snapshot
is preserved. If an enabled issue, workflow or optional section fails, the new
snapshot marks that section partial or unavailable; it does not present old
section values with a new timestamp.

Summary retains identity, visibility, states, scope and links but omits work
titles and descriptions. Detailed adds repository descriptions, issue/PR titles
and workflow names. Neither mode imports issue bodies, comments, commit
messages, personal identities, workflow logs, deployment payloads or release notes.

## Create and recover a follow-up

An organisation administrator with `webhook.manage` configures a separate
**GitHub Issues** destination by choosing its card in **Settings → Continuum**.
Choose the owner and repository and supply a separate fine-grained token with
**Metadata: read** and **Issues: read and write**. Optional existing labels need
repository push access. **Verify without creating an issue** checks access and
configuration; only a real creation can prove that GitHub accepts the write.

An editor who also has the organisation's `webhook.manage` permission can choose
**GitHub follow-up** on a saved Stratum, review
the issue title, description, repository visibility and source link, and create
the issue. Repository readers may differ from blueprint readers. Only the
reviewed issue text, source title/link and delivery reference are sent. The outcome and issue link
remain available from that Stratum.

GitHub Issues belongs to the **Webhooks & workflow** family advertised for Team.
Its organisation permissions are separate from the Enterprise plan required for
Link reads.

New destinations are manual-only. Optional subscriptions cover blueprint
publication and review submission, approval and rejection. They send a minimal
event summary, not arbitrary blueprint content or review comments. Existing
destinations must verify and save once to establish repository identity.

Delivery history distinguishes queued, retrying, failed, successful and unknown
outcomes. Safe retries are scheduled. An interrupted create with an unknown
outcome is not blindly repeated: find the issue in GitHub and reconcile it by
issue number in delivery history. Older one-shot deliveries are not replayed
automatically.

## Sharing, recovery and other GitHub paths

Newly fetched Link data defaults to blueprint editors, including when an older
connection has no audience setting. Choosing **All Blueprint readers** makes
approved snapshots available to everyone who can read the blueprint, including
anonymous public readers, embeds, exports and configured search/AI features.
GitHub does not re-authorise each Blueprintr reader. A source link still requires
that person's own GitHub access.

Settings apply on the next fetch. They do not rewrite earlier snapshots,
versions, templates, exports or distributed copies. Unlinking or revoking a
token cannot recall those copies. Review content before sharing it.

Use **Configure** to adjust permissions/content and **Verify & replace** to
rotate a token. A replacement must retain access to existing linked repository
IDs and enabled reads before it replaces the working token. For access errors,
check repository selection, token expiry, organisation approval and SSO. For
rate limits, wait before retrying. **Suspend** stops new searches and refreshes;
unlink tabs before deleting a Link connection.

[Folium repository sync](/foliums/blueprintr-user-guide/foliums/repo-sync) is a
separate docs-as-code path, configured on an individual Folium. Review the exact
destination and selected pages before pushing; draft and hidden pages start
unselected. GitHub sign-in is another independent path and grants no Link,
issue-creation or Folium-sync permissions.