---
title: "GitHub and GitLab"
description: "Connect a project to its repositories, so MySpec moves its tasks as work lands and briefs each new pull request."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.myspec.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub and GitLab

> **Pre-Release**
>
> This feature is still rolling out, so it may not be available in your
> organization yet. It can change before general release.

Connect your organization's GitHub or GitLab account, add a project's
repositories, and switch on what MySpec does with them:

| Feature | What it does |
|---|---|
| **Track tasks automatically** | Moves the project's tasks as work lands. It links pull requests, commits and branches to their tasks, marks a task done when its work is merged, and keeps the review and CI labels up to date. |
| **Brief pull requests** | Posts one comment on each new pull request: what it does, the tasks it moves, and the spec text it touches, quoted word for word. |

Both features are switched on per repository and start off. Their AI usage is
billed to your organization.

## Who can do what

| Action | Who |
|---|---|
| Connect or disconnect a GitHub or GitLab account | Organization owners and admins |
| Add or remove a project's repositories, switch a feature off, run a failed run again | Anyone with **Admin** on the project |
| Switch a feature on, choose its AI model, write its agent instructions | Organization owners and admins |
| See the project's repositories and their switches, the run history and its transcripts | Everyone who can open the project's settings |

## Connect an account

An account is connected once for the whole organization. Every project in the
organization can then add the repositories it reaches.

1. **Open the Repositories settings**

   Open a project, then **Settings** → **Repositories**. Under **Connected
   accounts**, select **Connect GitHub** or **Connect GitLab**.
2. **Read what MySpec asks for**

   A dialog lists what MySpec asks the provider for and what it sends to the
   AI model. Select **Continue**.
3. **Approve on GitHub or GitLab**

   - **GitHub**: install the MySpec GitHub App on your account or
     organization and choose its repositories, then approve the
     authorization. You must own the GitHub organization you install it on.
     If you do not, the page says an owner must approve the installation:
     connect again once they have.
   - **GitLab** (gitlab.com): approve MySpec's access. MySpec acts as the
     account you connect with, so a dedicated bot or service account is
     recommended.
4. **Back in MySpec**

   You return to the **Repositories** settings, and the account is listed
   under **Connected accounts**.

Changes you make on GitHub itself, such as which repositories the App can
reach, also come back to MySpec. The page says what changed.

## Add a repository

In the **Repositories** card, select **Add repository**, pick the account,
search for the repository and add it. The card shows how many repositories the
project has against its maximum.

- On GitLab, the connected account must be a **Maintainer** of the project,
  because MySpec adds a webhook to it.
- A repository can be added to several projects, and several organizations can
  connect the same repository through their own accounts. Each one only sees
  the events that reach it through its own account.

## Switch a feature on

Each repository has its two switches. Select one to switch it on. A dialog
asks first, and says:

- what the agent does, and that it reads the repository's code (diffs and
  files) and sends it to the AI model;
- that the AI usage is billed to your organization;
- for briefs, who can read them, and who they are posted as.

Select **Switch on** to confirm. Switching a feature off is immediate.

### Briefs and who can read them

A brief quotes your spec, and everyone who can read the pull request can read
the brief.

- On a **private** repository, that can include collaborators and contractors
  with no access to the MySpec project.
- On a **public** or **internal** repository, you must tick an extra
  confirmation: anyone (public), everyone in your GitHub enterprise, or anyone
  signed in to GitLab (internal) can read the briefs.

On GitHub, briefs are posted by the MySpec GitHub App. On GitLab, they are
posted as the account that connected. If that is a person's account, the
dialog warns you: comments show as theirs, and stop if they leave.

## Choose the AI model

The **AI models** card sets the model each feature runs on, for all of the
project's repositories. An organization owner or admin picks a model for
**Track tasks automatically** or **Brief pull requests**, or **MySpec default**,
and selects **Save** next to it. You can choose before or after switching a
feature on, and the choice applies from the next run.

Runs are billed at the chosen model's price. If a model chosen earlier is no
longer offered, the card says so, and runs use MySpec's default until you
choose another.

## Give the agent instructions

The **Agent instructions** card tells each feature's agent what this project
needs, for example:

- **Brief pull requests**: "Write the summary in Japanese."
- **Track tasks automatically**: "Never mark a task done from a push to a
  release branch."

An organization owner or admin types the instructions for a feature and
selects **Save**. They apply from the next run. Everyone else sees them
read-only.

- Instructions are added after MySpec's own rules and cannot change them: the
  agent still only moves tasks forward, quotes your spec word for word, and so
  on.
- They can be up to 2,000 characters. The card counts them as you type.
- To remove them, empty the box and select **Save**.

## Run history

The **Run history** card lists what each feature's agent did, newest first:
each task tracking run and each pull request brief, with when it ran, its
result, the model, the tokens used and how many times the agent read code.
A run that failed before its agent started (for example, a brief that could
not be prepared) is listed too, with its error.
Select **Refresh** to see new runs, and **Show older runs** to go back.

Select **View transcript** on a run to see:

- the instructions the agent was given, the project's included;
- the context it was given: the events and tasks for a tracking run, the
  pull request and spec excerpts for a brief;
- each time it read code: what it asked for (a pull request, a commit or a
  file) and how much came back, never the code itself;
- its notes after reading, and its answer.

A brief that ran again (after an edit or a reopen) lists its earlier runs: pick one in the
**Run** list. Transcripts are kept for 30 days; an older run shows its result
without one.

### Run a failed run again

A run can fail, for example when the AI model is briefly unavailable. Anyone
with **Admin** on the project sees **Run again** on a failed run.

- A task tracking run runs again on the same events. Events that a later run
  already read stay with that run.
- A pull request brief runs again on the same commit, and edits the same
  comment.
- The failed attempt's error and transcript are removed. The run shows as
  **Running** (a brief as **Queued**, then **Running**) until it ends. While it
  runs, it cannot run again.
- The new run uses the AI model and is billed like any other run, and counts
  toward the project's daily limit. If the project already reached its daily
  limit or your organization's AI quota, the run is skipped, and its events
  wait for a later run.

**Run again** is refused when another task tracking run of the project is in
progress, when the feature is switched off, or when later runs already read all
of the run's events (or they were removed, or tracking is off for their
repository). Task tracking runs that failed
before this was available can't run again.

## What task tracking does

MySpec collects the repository's events as they happen: pushes, pull requests,
reviews and CI results. A few minutes later, the agent reads the new ones
together and decides which tasks they are about.

- It only moves tasks forward: from **Pending** to **In progress**, and to
  **Done** once the work is merged into, or pushed to, the default branch. It
  never touches a task that is already done.
- A task key such as `T012` in a branch name, a pull request title or a commit
  message helps it match the work to the task.
- It assigns a task only when it is unassigned, and only to a member of your
  organization who can open the project and signs in to MySpec with the
  author's GitHub or GitLab account.
- It only counts activity from members of the repository. Pull requests from
  forks, from people outside it and from bots are ignored.
- **People win.** It never overwrites a change a person made, and never redoes a
  change a person reverted.

### On the task board

- A card shows its open pull or merge request, for example **#42** or **!12**,
  colored by its state.
- The agent manages three labels and never touches any other:

| Label | Means |
|---|---|
| `in-review` | The linked pull request is open and ready for review (not a draft). |
| `changes-requested` | A reviewer's latest review asks for changes. |
| `ci-failing` | A CI check failed on the pull request's latest commit. |

All three go once the pull request is merged or closed.

- A task's details list its **Links**: pull requests, commits and branches.
  Anyone who can edit the task can remove a link; the agent never adds it back.
- **Activity**, in a task's details, lists what the agent changed and why, with
  links to the evidence. Select **Revert** to undo a change. A revert is
  refused when someone changed that field since: a person's later edit is never
  undone.

## What a brief contains

A brief is posted when a pull request is opened (not as a draft), marked ready
for review, or reopened, and written again when someone edits its title or
description while it is open (an edit by a bot does not count). It is not rewritten on every push. Each pull request keeps a single
brief comment: a later run edits it. An edit made while a brief is being
written is not lost: the brief is written again once the current run ends.

- What the pull request does.
- The tasks it moves, linked to the project's task board.
- The requirements and acceptance criteria it touches, quoted word for word
  from your spec files.

No brief is posted for pull requests from forks, from people outside the
repository's members, or from bots, or while the project is archived. Briefs
are rate limited per project.

## Your code and data

While a feature is on, MySpec sends repository text to the AI model: pull
request titles and descriptions, commit messages, file paths, and the code its
agent reads.

What MySpec keeps:

- **Not kept**: the code its agent reads (file contents and diffs), apart from
  short parts the agent may quote in its notes (see the run's transcript).
- **Kept for up to 30 days**: the events it receives, including pull request
  titles and descriptions, commit messages, branch names, file paths, authors
  and links.
- **Kept for 30 days**: each run's transcript: the instructions and context
  the agent was given, what it read (the file paths and commits it asked for,
  not their content), its notes and its answer. Everyone who can open the
  project's settings can read them.
- **Kept until changed or the project is deleted**: each feature's agent
  instructions.
- **Kept as long as the task exists**: the changes it made to your tasks, with
  their **Links** (including pull request titles) and **Activity** (what
  changed, why, and the links to the evidence).

## Remove a repository or disconnect

- **Remove a repository** from a project: select **Remove** next to it. MySpec
  stops reading its events and writing briefs for it. Its tasks keep the links
  they have.
- **Disconnect an account**: under **Connected accounts**, select
  **Disconnect**. Every project in the organization loses the repositories it
  added through that account, with their switches. This cannot be undone. On
  GitHub, the MySpec GitHub App stays installed: uninstall it on GitHub if you
  no longer use it.

## Troubleshooting

| You see | What to do |
|---|---|
| **Suspended** next to a GitHub account | The MySpec App is suspended on GitHub. Unsuspend it there, then connect again. |
| **Uninstalled** next to a GitHub account | The App was uninstalled on GitHub. Select **Connect again** to install it again. |
| **Needs connecting again** next to a GitLab account | GitLab refused MySpec's access. An organization owner or admin selects **Connect again**. |
| **Access lost** next to a repository | MySpec can no longer reach the repository through its account. Give the account access again on GitHub or GitLab. |
| The connected GitLab account must be a Maintainer | Give the account the Maintainer role on the GitLab project, then add it again. |
| This connect link expired or was already used | Start connecting again from **Settings** → **Repositories**. |
| This model is not offered for repository features | Choose another model in the **AI models** card. |
| The instructions are too long, or hold characters that cannot be saved | Shorten the instructions to 2,000 characters, and remove any control characters pasted with them. |

Source: https://docs.myspec.dev/guides/github-and-gitlab/index.mdx
