GitHub Organizations

OutcomeDev supports deploying and managing repositories within GitHub Organizations. This guide explains how to connect your organization and ensure OutcomeDev has the necessary permissions to access your repositories.

For a deeper dive into why organizations are used and the strategy behind this separation, read the blog post: Why Organizations Matter.

Connecting an Organization

To see repositories from an organization in OutcomeDev, you must use the Owner dropdown in the repository selector to switch contexts. If your organization appears in the list but shows no repositories, you likely need to grant access.

How you grant access depends on whether you are signing up for the first time or are already a user.

Scenario A: First-Time Sign Up

When you first sign in to OutcomeDev with GitHub, you will see an authorization screen from GitHub asking for permission to access your account.

1. Look for the Organization access section at the bottom of the list.
2. You will see a list of your organizations.
3. Click the Grant button next to any organization you want to use with OutcomeDev.
4. If you are not an admin, you may see a Request button instead. Clicking this sends an email to your organization owners asking for approval.

Scenario B: Already Signed Up

If you skipped the "Grant" step during sign-up or joined an organization later, you must manually grant access in your GitHub settings.

Quick Tip: You can jump directly to these settings from within OutcomeDev by clicking the ... menu next to the repository selector and choosing Manage Access.

Alternatively, you can go through GitHub:

1. Go to GitHub Settings > Applications > Authorized OAuth Apps.
2. Click on OutcomeDev in the list of applications.
3. Scroll down to the Organization access section.
4. Click the Grant button next to the organization you want to connect.

Once granted, the repositories will appear in OutcomeDev immediately (you may need to refresh the page).

Roles and Team Access

Understanding how GitHub permissions work with OutcomeDev is crucial for teams.

1. The "Grant" is for the Application, Not the User

When an organization owner clicks Grant, they are essentially opening the door for the application (OutcomeDev) to enter the organization. This "unblocks" the app for all members of that organization.

However, "unblocking" the app does not give every user access to every repository. OutcomeDev still respects individual user permissions.

2. Who Can Push Code?

OutcomeDev performs actions (like creating branches, committing code, and opening Pull Requests) on behalf of the currently signed-in user.

• If you have "Write" access: OutcomeDev can push code and create branches.
• If you have "Read" access: OutcomeDev can see the code but cannot push changes. You will encounter errors if you try to deploy or modify code.

3. Organization Roles

• Owners: Have full administrative access. They are the only ones who can initially Grant the application access to the organization.
• Members: Can use OutcomeDev to interact with the organization's repositories once an Owner has granted access. They are limited to the repositories they have been given access to in GitHub.
• Outside Collaborators: If you invite a contractor to a single repository, they can use OutcomeDev for that repository only, provided the organization has granted access to the app.

Managing and Revoking Access

You maintain full control over what OutcomeDev can access. You can revoke access to an organization or the entire application at any time.

To Revoke Organization Access

1. Navigate to Authorized OAuth Apps in GitHub (or use the Manage Access shortcut in the app).
2. Select OutcomeDev.
3. In the Organization access section, click Revoke next to the specific organization.

To Revoke All Access

1. Navigate to Authorized OAuth Apps in GitHub.
2. Find OutcomeDev and click the ... menu (or Revoke access button depending on your view).
3. Confirm revocation.

Note: If you revoke access, your running agents and deployments for that organization may stop working until you reconnect.

Why Organizations?

Using a GitHub Organization allows you to:

1. Manage Permissions: Control who has read/write access to specific repositories.
2. Separate Contexts: Keep personal projects separate from work or client projects.
3. Centralize Management: Manage team access and permissions across multiple repositories.

OutcomeDev respects these boundaries by requiring you to explicitly switch contexts in the UI. Personal and organization repositories are never mixed in the same view.