Connect GitHub or GitLab
Connect your organisation to GitHub through the SpecsGraph App or to GitLab with an access token, then point each project at a repository, branch and folder.
Why a Git connection
Publishing a task writes the spec as YAML files into your repository, as a commit or a pull request, so the spec and the code share one history. A project without a repository still publishes, to Main only: the task is Published without git.
Connections belong to the organisation. Each project then picks one repository from them.
GitHub: install the App
SpecsGraph writes to GitHub through a GitHub App, not through a person's account or a deploy key. You choose the repositories it can reach, GitHub issues it installation tokens that expire after an hour, and spec commits come from the App's own bot account, specsgraph[bot]. SpecsGraph runs the App for you, so there is nothing to register.
Start from SpecsGraph
An Admin opens Settings > Integrations and chooses Connect GitHub. SpecsGraph sends you to GitHub.
Pick the account and repositories
Choose the organisation or account, then Only select repositories and pick the ones SpecsGraph should publish to, such as
northwind/shop. If you are not an owner there, GitHub sends the installation to an owner as a request.Install and return
Confirm the permissions below. GitHub returns you to SpecsGraph with the connection active.
Note
GitHub's own documentation is the authority on its screens and on installation requests. The steps here describe GitHub at the time of writing.
GitHub permissions
Contents access covers the whole repository, because GitHub offers no folder scope. SpecsGraph writes only inside each project's spec folder.
SpecsGraph detects merges from the App's pull request events, and by asking GitHub about the pull requests waiting to merge, every five minutes and whenever someone chooses Check now on the task. Branches and pull requests explains what happens next.
The same events let a merged code pull request that names a work item, such as T-12.1, complete it. Add the code repositories to the installation, and list them in the project's execution settings; see Work items and delivery.
GitLab: add a token
An Admin chooses Connect GitLab in Settings > Integrations and pastes a GitLab access token that can read and write the repositories: a group or project access token. For a self-managed GitLab, add its base URL as well. SpecsGraph lists the projects the token reaches.
On GitLab a merge request plays the part of a pull request. Everything these pages say about pull requests applies to merge requests too.
For merge requests to complete work items, an Admin generates a webhook secret on the GitLab connection and adds a webhook in GitLab with Merge request events; see Work items and delivery.
Connect a project to a repository
An Admin or Owner sets these in the project's Settings > Git. Organisations and projects covers the rest of a project's settings.
- Connecting writes nothing. No branch, commit or pull request appears until the first publish.
- Monorepos. Several projects can share a repository with different spec folders. Branch names carry the project key, so they never collide.
- Disconnecting. A project whose repository is disconnected publishes without git from then on. Disconnecting is refused while a publication is in flight.
Change or remove access
Manage repository access in GitHub, on the App's Configure page, or by replacing the GitLab token.
- Losing access. When SpecsGraph can no longer reach a project's repository, the project shows a warning and its publishes are blocked (no access) until access returns or the project points elsewhere.
- Nothing is deleted in Git. Removing a connection leaves the files in
.specsgraph/and any open pull requests where they are.
Next steps
- Spec files in your repository: what a publish writes into the spec folder.
- Branches and pull requests: how a task reaches your base branch.
- Security and your data: what SpecsGraph stores about a connection.