Connect GitHub

Waltz reads how your software is built and how it evolved, and writes a Brief for each level of engineering. Everything starts with GitHub. For a mid-size org, setup takes 30 to 60 minutes, and most of that is analysis running on its own.

Before you start

• You can install GitHub Apps on your GitHub organization.
• You have a work email address. Waltz signs you in with a link by email; there is no password.

Create an org

1. Sign in at waltz.run with your work email, then open the link Waltz sends you.
2. Create an org. You are its owner.

The org's overview shows a setup checklist. Each step completes when Waltz sees it done, in any order, and the header shows the time since you started.

Install the GitHub App

1. In the console, open Integrations and choose Connect GitHub.
2. On GitHub, choose the organization to install Waltz on.
3. Choose All repositories, or select the ones Waltz may read.
4. Authorize Waltz. GitHub returns you to Integrations, with the connection and its repos.

The App asks for read access to repository contents, metadata and pull requests, and nothing else. It never writes to GitHub. Waltz confirms that you can reach the installation before it links it to your org.

Choose repos

Every repo the App reaches is included by default. To leave one out, switch it off under Repos. To change which repos the App reaches at all, change the installation on GitHub; Waltz follows.

What happens next

1. First analysis. Each included repo is cloned into a short-lived sandbox, analysed over its last 12 weeks, and deleted. Waltz keeps the facts it derived, never the source (Privacy and data). The checklist counts repos analysed against repos included.
2. Staying current. Pushes to a default branch and pull requests reach Waltz as they happen, and a weekly pass catches anything missed.
3. Your Briefs. Under Briefs, choose New subscription: a Brief type, what it covers and who receives it. Once your org chart is in, Give each lead their Brief on the checklist does this for every lead at once (Invite your leads).
4. The first Brief. Start with a Baseline Brief: your system as it is today, the reference every later Brief compares against. A new subscription waits for its scheduled time (EM Briefs: Monday 07:00 UTC, for the week that just closed). Choose Send Brief to have one now.

The target is your first Brief within an hour of creating the org.

Without GitHub

GitLab connects with a read-only group access token instead of an app. The rest of this guide is the same.

On the Free plan

Free is a trial: GitHub only, a limited number of repos, and Baseline and EM Briefs for a limited period. The limits are still being set with our design partners. Repos past the limit are recorded but not analysed, and Briefs already written stay readable after the period ends.

Disconnecting

Disconnecting in Waltz stops all processing for that connection. To remove the App itself, uninstall it on GitHub.

Next: Invite your leads.