1.2.2.2 GitHub auth

A Concourse server can authenticate against GitHub to leverage their permission model and other security improvements in their infrastructure.

Authentication

First, you'll need to create an OAuth application on GitHub.

The "Authorization callback URL" must be the URL of your Concourse server with /sky/issuer/callback appended. This address must be reachable by GitHub - it can't be localhost.

For example, Concourse's own CI server's callback URL would be:

https://ci.concourse-ci.org/sky/issuer/callback

You will be given a Client ID and a Client Secret for your new application. The client ID and secret must then be configured on the web node by setting the following env:

CONCOURSE_GITHUB_CLIENT_ID=myclientid
CONCOURSE_GITHUB_CLIENT_SECRET=myclientsecret

Note that the client must be created under an organization if you want to authorize users based on organization/team membership. If the client is created under a personal account, only individual users can be authorized.

If you're configuring GitHub Enterprise, you'll also need to set the following env:

CONCOURSE_GITHUB_HOST=github.example.com
CONCOURSE_GITHUB_CA_CERT=/path/to/ca_cert

The GitHub Enterprise host must not contain a scheme, or a trailing slash.

Authorization

Users, teams, and entire organizations can be authorized for a team by passing the following flags to fly set-team:

--github-user=LOGIN

Authorize an individual user.

--github-org=ORG_NAME

Authorize an entire organization's members.

--github-team=ORG_NAME:TEAM_NAME

Authorize a team's members within an organization.

For example:

$ fly set-team -n my-team \
    --github-user my-github-login \
    --github-org my-org \
    --github-team my-other-org:my-team

...or via --config for setting user roles:

roles:
- name: member
  github:
    users: ["my-github-login"]
    orgs: ["my-org"]
    teams: ["my-other-org:my-team"]

Configuring main Team Authorization

GitHub users, teams, and organizations can be added to the main team authorization config by setting the following env on the web node:

CONCOURSE_MAIN_TEAM_GITHUB_ORG=org-name
CONCOURSE_MAIN_TEAM_GITHUB_TEAM=org-name:team-name
CONCOURSE_MAIN_TEAM_GITHUB_USER=some-user

Multiple orgs, teams, and users may be specified by comma-separating them.