GitHub
The GitHub connector links the Plotwork GitHub App to your organisation. Once linked, the Drift tab lists your repositories to enable, and the trusted publisher form lists your repositories, their workflow files and their deployment environments, so nothing has to be typed.
TL;DR
| Question | Answer |
|---|---|
| What does it do? | Links the App's installations. Drift then enables repositories with one pull request, and the GitHub Actions trusted publisher form picks the repository, workflow and environment from lists. |
| Which plan? | Pro and Enterprise, the plans with the drift dashboard and trusted publishers. Unlinking works on any plan. |
| Who connects it? | The owner and the admins, signed in, under Connectors, GitHub. |
| What does the App read? | Repository names, ids and default branches, file paths of the default branch, and deployment environment names. |
| What does Plotwork keep? | The installations' and repositories' ids and names, each repository's default branch, the formats a scan found, and its status. No token, no path and no file. |
| Is it needed? | No. Without it, the trusted publisher form takes a typed repository and workflow file as before. |
| Is it recorded? | Yes. Linking and unlinking are in the organisation's audit log, never with a token. |
1. Connect
- Open the organisation in the portal, choose Connectors, and open GitHub.
- Choose Connect GitHub. GitHub asks you to authorise Plotwork and sends you back with the installations of the App your GitHub account can reach.
- Choose the installation and choose Link.
When your GitHub account can reach no installation yet, choose Install on another account. GitHub asks which account to install the App on and which repositories it may reach, then sends you back to link it. The GitHub App guide covers every message the linking page can show.
2. Manage the installations
The GitHub page lists each linked installation:
| Shown | Meaning |
|---|---|
| The account | The GitHub organisation or person the App is installed on. |
| Repositories | How many of its repositories Plotwork holds. |
| All repositories or Chosen repositories | What the installation may reach, set on GitHub. |
| Suspended | Its owner paused the App on GitHub. Nothing can be enabled until it is resumed. |
| Settings on GitHub | Where to change its repositories, suspend it or uninstall it. |
Refresh repositories reads the installation's repositories again, 100 at a time. Unlink asks first, then forgets the installation and its repositories. The App stays installed on GitHub until you remove it there, and trusted publishers it made stay on Keys & CI.
The Drift tab shows the connection in one line, GitHub connected with the number of repositories, and Manage opens this page.
3. Add a trusted publisher from lists
- Choose Add a trusted publisher on the GitHub page, or open Keys & CI, CI/CD, and choose Add trusted publisher.
- Choose GitHub Actions.
- Open Repository and type part of its name. Repositories are grouped by account, with a lock on a private one and the default branch under each name.
- Workflow lists the repository's files under
.github/workflows. Choose one, or type another file name. - Environment suggests the repository's deployment environments. Choose one, type another, or leave it blank.
- Choose what its runs can do, and save.
Type the repository instead switches to the typed fields at any time. Editing an entry keeps its own repository, even when no installation reaches it. With more than 100 repositories, the list asks Plotwork to search as you type, 50 at a time.
4. What the App reads and writes
| Item | Read | Kept |
|---|---|---|
| Repositories of an installation | Names, ids, default branches and whether each is private, on link and refresh | The same |
| File paths of the default branch | When a repository is scanned, or the form lists its workflow files | Only the format names a scan found |
| Deployment environments | Their names, when the form lists them | No |
| Files | Only when Enable opens its pull request | No |
| Tokens | None. Each call gets a token for one repository that lives an hour, in memory. |
The App writes only the branch plotwork/setup (or plotwork/fix-config) and the pull request Enable opens. Nothing reaches your default branch until you merge it. When GitHub does not let the App read a repository's environments, the form offers none and the field stays free text.
5. Troubleshooting
| What the page or form says | What to do |
|---|---|
| The GitHub App is not set up on this server | This Plotwork server has no GitHub App. Type the repository and workflow. |
| No workflow file on the default branch | The repository has none yet. Type the file name the workflow will have. |
| The list may miss a workflow | The repository is too large to read whole. Type the file name if it is not listed. |
| The workflow files could not be read | GitHub did not answer. Type the file name, or try again later. |
| An installation is suspended on GitHub | Resume it in its settings on GitHub. |
Audit events
| Action | When | Details |
|---|---|---|
orgs.github.link | An installation is linked | The account it is on |
orgs.github.unlink | An installation is unlinked | The account it is on |
See also
| Page | Why |
|---|---|
| The Plotwork GitHub App | Linking, scanning and Enable in full |
| Trusted publishers | What a trusted publisher is and what is checked |
| Drift dashboard | What enabled repositories report |
| Connectors | Every connector |