Repository integration

The Repository tab links a project to one git repository — on GitHub or on Azure DevOps — and pushes the project's generated documentation tree into it once the Tasks step is done. A new-system (greenfield) project gets a fresh repository that Alara Code creates for you; an existing-system (brownfield) project connects a repository that already holds code, and Alara Code never writes to its branches directly.

Where you connect a repository

You meet the same repository step in two places:

• The new-project wizard. Its last step, Repository, appears after the project is created. A greenfield project can press Skip for now and connect later; a brownfield project cannot skip — the wizard says "Connect its repository to finish setting it up."
• The Repository tab of any project. If nothing is connected yet, it shows the same chooser.

The chooser asks "Where should this project's repository live?" (greenfield) or "Where does the existing repository live?" (brownfield) and offers two cards, GitHub and Azure DevOps. Once a provider is connected, the tab opens straight on that provider's view and the chooser no longer appears. Choose a different provider takes you back to the chooser while you are still setting up.

Whether a project is greenfield or brownfield is chosen when you create it (New system or Existing system) and is shown under Settings › General › Project type.

Drawing diagram…

Greenfield: create a new repository

GitHub

GitHub uses the Alara GitHub App. The connection is yours — it is recorded against your account in your organization — and the repository belongs to the GitHub account or GitHub organization you install the app on.

1. Open GitHub. If you have not installed the app yet, you see Connect GitHub: "You'll be taken to GitHub to install the app, then returned here." Press Connect GitHub; the page redirects to GitHub.
2. On GitHub, install the app and choose All repositories. GitHub sends you back to the project's Repository tab with a GitHub connected toast: "Finish setting up the repository below."
3. Fill in Repository details:
   • Repository name — defaults to a slug of the project name (lowercase letters, digits, ., _, -). The hint shows the full name it will be created as, <account>/<name>.
   • Visibility — Private (the default) or Public.
4. Press Create repository. Alara Code creates the repository on the account the app is installed on, commits an initial README.md to its default branch, and links it to the project. A Repository created toast names it.

Azure DevOps

Azure DevOps uses a Personal Access Token (PAT) — there is no app to install.

1. Open Azure DevOps and fill in Azure DevOps location:
   • Organization — your Azure DevOps organization name. Organizations you have saved a credential for appear under the field as Saved: chips; click one to fill it in.
   • Project — the Azure DevOps project the repository goes in.
   • Repository name — defaults to a slug of the project name; the hint shows <organization>/<project>/<name>.
2. Under Credential, enter a Personal Access Token with the Code: Full scope. Creating a repository needs Code: Full — Code: Read & Write can read the project but cannot create repositories.
3. Press Create repository. Alara Code checks the token against the project, saves it, creates the repository, commits an initial README.md, and links it.

While the repository is being created the tab shows Setting up… and refreshes on its own. If it does not finish, submit the form again with the same details and it resumes where it stopped.

How the PAT is stored. The token is checked against Azure DevOps first, then encrypted on the server and saved for you and that Azure DevOps organization. It is never shown again or returned by the API. Next time you connect a project in the same organization you can leave the field empty — the form says "Saved credential found for this organization" — and entering a new token replaces the saved one.

Brownfield: connect an existing repository

For an existing system you connect a repository that is already there. Both providers promise the same thing, and the code holds to it: nothing is written to the repository's branches when you connect, and documents later go to an alara/sdlc-docs branch as a pull request.

GitHub

1. Open GitHub and press Connect GitHub. You are sent to GitHub to install the Alara app on the account that owns the repository.
2. When you come back:
   • If the installation can reach exactly one repository, it is connected straight away.
   • If it can reach several, you see Choose a repository. Pick one, optionally set a Base branch (leave it blank for the repository's default), and press Connect repository. A Repository connected toast confirms it with the base branch.
3. The selection link GitHub returns you with is short-lived (and the install link itself is valid for 10 minutes). If it has expired, the tab says "The GitHub selection link has expired — connect GitHub again."

Azure DevOps

1. Open Azure DevOps, fill in Organization and Project, and enter a Personal Access Token (the field suggests Code: Read & Write) — or rely on a saved credential for the organization.
2. Press List repositories. You see Choose a repository, with each repository's default branch and badges for empty and disabled repositories. A disabled repository cannot be picked.
3. For a repository with content, choose a Base branch from the list (the default branch is marked "(default)").
4. Press Connect repository.

If the repository is empty, the tab tells you that a README will be committed to main so it can be cloned — this is the only write a brownfield connect ever makes, and it needs a token with write access.

Push the documentation

Once a repository is linked, the Repository tab shows it — the repository name and its default branch — in a success callout. The Push documentation section appears below it only after the Tasks step has completed, because the pushed tree includes the epics and tickets that step generates.

Press Push docs to GitHub or Push docs to Azure DevOps. The button reads Pushing… while the push runs, and the push keeps going if you switch tabs — the button stays disabled until it finishes, so you cannot start a second push by accident.

What gets pushed

The implementation tree is regenerated every time the Tasks step runs, so a new Tasks version followed by another push brings the repository up to date. Everything goes in one commit with the message docs: add SDLC documentation and CLAUDE.md project brief.

Where it goes

Greenfield repository. The commit lands on the repository's default branch (main when none is recorded). A development branch is created alongside it if it does not exist yet, and development becomes the project's working branch. The toast says Docs pushed to GitHub (or Azure DevOps) with the file count and branch, and adds "development branch created" the first time.

Brownfield repository. The customer's branches are never written to. The commit goes to the alara/sdlc-docs branch, created from the base branch you chose at connect time (or the default branch), and a pull request titled docs: Alara SDLC documentation is opened from alara/sdlc-docs into the base branch. Its description says only docs/ and CLAUDE.md were added. Pushing again adds to the same branch and reuses the open pull request. No development branch is created and the base branch stays the working branch. Review and merge the pull request on GitHub or Azure DevOps.

Repository structure (when enabled)

A deployment can turn on an optional step that designs a folder structure for a greenfield repository and commits it with the docs. It only runs on a repository that still contains nothing but what Alara Code put there; a repository that already has code is left alone. When it is on, the toast Repository structure ready tells you it was committed. If a build fails the tab shows Repository structure build failed. with a Retry button, which pushes again.

Permissions

Who may see a project is decided by project membership (see Members and permissions). What a person may do on the Repository tab is decided by the Integrations module in their PolyX organization role — creating a project does not grant it.

Without read, the tab shows Repository settings are not available to you and the sentence naming the missing right. Without create or update, the buttons are disabled; hover them to see the reason, for example "Needs Integrations › update", and the full message "Your role does not include Integrations › update. Ask an organization administrator to add it to your role in PolyX."

Projects are loaded inside your organization only — a project from another organization, or one you cannot see, answers as "not found" to every repository call.

Disconnecting

The Repository tab has no disconnect button. Disconnecting is available through the API — POST /api/projects/:id/github/disconnect and POST /api/projects/:id/azure/disconnect, both needing Integrations › delete. A disconnect marks the project's link as disconnected; it does not delete or change anything in the repository. For Azure DevOps your saved PAT is kept, because it belongs to you and the organization and may back other projects.

Things also change from the GitHub side:

• Uninstalling the app on GitHub disconnects every project linked through that installation.
• Suspending the app suspends those links; unsuspending restores them (a link someone disconnected on purpose stays disconnected).
• If a GitHub link was disconnected and the project creator's app installation can still reach the same repository — for example after reinstalling the app — the link is restored automatically the next time the tab loads.

Once a project has no active link, the Repository tab offers the provider chooser again.

Deleting a project (Settings › Danger zone › Delete this project) removes the project, its documents, board and run history, but the connected repository is not touched.

Errors and what to do

For other errors, see Troubleshooting.

Under the hood

• Connection records are per project and per organization: one GitHub link or one Azure DevOps link. GitHub app installations are recorded per person per organization; Azure DevOps credentials per person per Azure DevOps organization, encrypted with AES-256-GCM.
• GitHub reaches the bridge through a signed install callback (/api/github/install-callback) and an HMAC-verified webhook (/api/webhooks/github), which is how uninstall and suspend events arrive.
• Both providers share one push implementation, so GitHub and Azure DevOps projects behave the same way. The endpoints and their permissions are listed in the API reference.