Argo CD GitHub SSO with Dex | GitHub Enterprise login

How Argo CD sign-in with GitHub works through Dex

Your engineers already belong to GitHub organizations and teams, and the platform team usually wants those memberships to decide who can use Argo CD without creating a second set of accounts. The supported method is Argo CD's bundled Dex with its GitHub OAuth2 connector, and the Argo CD user management guide includes an example for a GitHub Enterprise instance. This is not direct OIDC, because Argo CD does not treat GitHub as a generic OpenID Connect provider in this setup. Dex sits between Argo CD and GitHub: Argo CD redirects the user to Dex, Dex sends the user to GitHub for authentication and authorization, and Dex returns the user's identity and team membership to Argo CD as claims.

Dex needs a GitHub OAuth app registered for your organization, with a client ID and client secret stored in the Argo CD configuration rather than in the ConfigMap as plain text. The OAuth app's callback URL must point to the Dex callback on your Argo CD hostname, and the scope must include the organization and team read permissions so that team membership is returned. For GitHub Enterprise Server, the OAuth app and the hostname must both point to your own instance, and the Dex connector must be configured with that host. Confirm the exact connector keys and callback path against the version of Argo CD you run, because Dex configuration has changed between Argo CD releases.

Team membership is then mapped to Argo CD roles through the RBAC policy. Each GitHub team is referenced by its group identifier in the form the connector returns, and that identifier is bound to project or global roles in the policy. Before rollout, confirm that a test user in a single team receives exactly the expected access, and check how a user who belongs to several teams is treated, since their effective permissions are the combination of all matching roles. Decide who owns the GitHub organization and team structure, because changes in GitHub will change Argo CD access without any change in Argo CD itself.

What you need before connecting GitHub to Argo CD

Before you touch the Dex configuration, settle which Argo CD version you run, which GitHub edition hosts your organization and teams, and who owns the OAuth app. Each card below is a decision or check that, if skipped, usually surfaces later as a failed login or a role that never applies.

Argo CD version and patch line

Confirm the Argo CD minor version you run and whether it is on a current patch release. The project supplies patches only for the three most recent minor versions, and the latest patch releases published on October 12, 2026 were v3.5.5, v3.4.11 and v3.3.16. If you are below 3.0, plan the upgrade first, because Dex-based RBAC changed to use the federated_claims.user_id claim in 3.0.

GitHub organization and team structure

Map each Argo CD role to a GitHub team that already exists, such as platform admins, application owners or read-only auditors. Dex reads organization and team membership, so teams must belong to the organization you configure. Decide whether nested teams and outside collaborators are in scope, because they may not carry the membership you expect.

GitHub Enterprise Cloud or Server

Choose where the identity source lives. GitHub Enterprise Cloud with data residency runs on a dedicated GHE.com subdomain in selected regions, and that subdomain does not offer public repositories. Self-hosted GitHub Enterprise Server means you operate the appliance, its upgrades and its certificates. Confirm with your GitHub account team which edition your organization uses, and confirm the GHES release line and its support end dates on GitHub's release page before you configure anything.

OAuth app owned by an organization admin

Register the OAuth app under an organization owner account, not a personal account, so the client ID and secret survive staff changes. Store the client secret in your secrets manager and rotate it under a documented process. Confirm that the organization permits OAuth app registration and any third-party app restrictions, because a blocked app fails silently from the user's point of view.

Callback URL reachable from users and cluster

Dex sends the browser to GitHub and then receives the callback, so the Argo CD external URL and the callback path must resolve from employee laptops and must match the OAuth app setting exactly. The Argo CD server must also reach GitHub or your GHES host for the token exchange. Test both directions from a network segment that matches your users, including any proxy or split DNS.

TLS trust for self-hosted GHES

If you use GitHub Enterprise Server, Dex must trust the certificate chain of your GHES hostname. Obtain the internal certificate authority bundle from your PKI team and plan how it reaches Dex, since a private CA not in the trust store causes connection failures that look like login errors. Confirm the same chain works from the Argo CD pods, not just from your workstation.

Configure the GitHub connector in Dex, step by step

This sequence takes you from a GitHub OAuth app to a working Argo CD login through the bundled Dex GitHub connector, with organization and team restrictions, optional GitHub Enterprise Server settings, and checks at each stage. The result is a sign-in path that admits only the people you intend and records their team membership for RBAC.

Confirm the GitHub target and access model
Before touching the cluster, decide whether you are connecting to GitHub Enterprise Cloud or a self-hosted GitHub Enterprise Server instance, and confirm which organization and teams will be allowed to sign in. Ask the GitHub organization owner to confirm that the people who need Argo CD access are members of those teams, and that a suitable owner can register an OAuth app. If you use GHE.com data residency, confirm the dedicated subdomain with GitHub before you copy any URLs. You are done when you have a written list of the organization name, the team slugs for each Argo CD role, and the exact base URL of the GitHub instance.
Register the OAuth app in GitHub
In the GitHub organization settings, register a new OAuth app for Argo CD. Set the homepage URL to your Argo CD address and the authorization callback URL to the Dex callback path under your Argo CD URL, using the same host name you will set as the url value in argocd-cm. Generate a client secret and copy it once, because GitHub will not show it again. Record the client ID. You are done when the OAuth app appears under the organization with the expected callback URL and you hold both the client ID and a newly generated client secret.
Store the client secret in a Kubernetes Secret
Create or edit the Argo CD secret in the Argo CD namespace and add the GitHub client secret under a dedicated key, for example dex.github.clientSecret. Do not place the value in argocd-cm or in any file committed to Git. Argo CD's Dex configuration can read the value from this secret when the connector references it by key. Restart the Dex deployment after the secret changes so the new value loads. You are done when kubectl get secret shows the new key and the Dex pod has restarted without errors in its logs.
Add the GitHub connector to Dex in argocd-cm
Edit the dex.config entry in the argocd-cm ConfigMap and add a GitHub connector with a stable id and name, the client ID, a client secret reference to the Kubernetes Secret key, and the orgs list. Under orgs, list the organization name and, where you restrict by team, the team names allowed to sign in. Keep the connector definition in your version-controlled Argo CD configuration so changes go through review. Apply the change and let Dex reload. You are done when the Argo CD login page shows a GitHub option and the Dex logs show the connector initialized without validation errors.
Set GitHub Enterprise base URL and root CA when needed
If you use GitHub Enterprise Server, add the hostName for your instance to the connector and confirm that Argo CD's Dex pod can reach it over the network. If the instance uses an internal certificate authority, add that root CA to the connector's rootCA setting, mounted from a ConfigMap or Secret so Dex trusts the certificate. Argo CD's user management guide includes an example for a GitHub Enterprise instance, so compare your fields against that example. You are done when a test sign-in reaches the GitHub authorization page of your Enterprise Server and the Dex logs show no TLS or name-resolution errors.
Set the Argo CD URL and confirm the Dex callback
Confirm that the url value in argocd-cm matches the public address users type in their browser, including the scheme and host name. Check that the callback URL registered in the GitHub OAuth app matches the Dex callback under that address exactly, including the path. A mismatch is the most common cause of redirect errors at this step. You are done when the browser completes the redirect from GitHub back to Argo CD without a callback mismatch error and lands on the Argo CD interface.
Restrict the admin account and verify login
Sign in with an organization member who belongs to an allowed team and confirm the session works. Then check that the local admin account is used only for initial setup, and set admin.enabled to false in argocd-cm once SSO works for the platform team, following the user management guidance. Next, sign in as a GitHub user outside the organization or outside the permitted teams and confirm the login is denied. Record the group or team values seen in the session so you can map them to RBAC roles in the next step. You are done when an allowed user signs in, an outside user is refused, and the admin account is disabled or documented as a break-glass procedure.

GitHub Enterprise Cloud or GitHub Enterprise Server: which path changes the work

Enterprise Cloud without data residency keeps the work closest to a standard GitHub.com setup. The Dex GitHub connector sends sign-in requests to GitHub's public endpoints, so the only host you configure on the GitHub side is the Argo CD address that Dex returns users to after login. Most of the effort moves to the GitHub OAuth application, the organization and team settings that feed group membership, and the Argo CD RBAC mapping that follows from them.

Hostname: Dex uses github.com, so no custom GitHub host goes into the connector configuration.
Callback address: the OAuth application must list the exact external URL of your Argo CD instance, including the path Dex uses for its callback. A mismatch produces a redirect error at login.
Network reachability: the Argo CD API and Dex must be reachable from engineers' browsers, and the cluster needs outbound access to GitHub. Confirm the egress rules with your network team, because proxies often filter these paths.
Certificate trust: GitHub's public certificates are normally trusted by the default certificate store, so a private CA bundle is usually not needed for the GitHub side. Verify this against your proxy configuration.
Organization approval: an organization owner may need to approve the OAuth application before team membership is returned to Dex.

Before testing, compare the OAuth application's callback address with the external Argo CD URL character by character.

Mapping GitHub organizations and teams to Argo CD roles

This table compares how GitHub organization membership, team names, team slugs and team IDs behave when they feed Argo CD groups through Dex, and what each one needs in policy.csv. Read each row as a decision point: the identifier you choose determines whether a mapping survives a team rename, and the default policy determines what anyone gets before you have mapped anything.

Element	What it is in this setup	What to decide or verify
Organization membership	Confirms that a GitHub user belongs to the organization that the Dex GitHub connector is allowed to read. It is a gate, not a role.	Confirm which organizations the connector can read and whether members outside them can sign in at all.
Team name	The display name shown in GitHub. It can contain spaces and capitals and it changes when someone edits the team.	Avoid it as the policy key. A rename silently breaks every group line that references the old name.
Team slug	The URL-safe identifier GitHub derives from the team name, such as the lowercase form used in team URLs.	Use the slug as the group value in policy.csv after checking it in the GitHub API or team settings. Record the owning organization with it.
Team ID	A numeric identifier that stays the same when a team is renamed.	Ask whether your Dex version and connector configuration can map on IDs. If not, document that renames require a policy update in the same change.
Nested or child teams	Membership in a child team does not automatically confirm membership in its parent for Argo CD purposes.	Map each team that should grant access explicitly, and test a user who sits only in a child team.
Default policy	Argo CD's built-in default role controls what an authenticated user without a mapping can do.	Set the default to no access, then add only the group lines you have tested. Review the default after every upgrade.
Project roles	Project-scoped roles bind a team to specific Argo CD projects and actions, such as sync or get on applications.	Grant the narrowest project role per team, and keep global admin rights out of team mappings.
Dex-based RBAC claim	Since Argo CD 3.0, Dex-based RBAC uses the federated_claims.user_id claim to identify the user in policy lines.	Check the claim value in a test login before writing user-level lines, and confirm the claim appears in the token you expect.
Service accounts and automation	CI jobs and scripts should not sign in through a person's GitHub account. Their access belongs in a separate, machine-scoped path such as local accounts with API keys or project tokens.	Keep bot users out of human team groups. Ask who owns each automation identity, how its credentials rotate, and how its access is reviewed.

Security controls for GitHub sign-in

Once engineers sign in to Argo CD with GitHub, the login path itself becomes a control point. The cards below cover the account, secret, scope, configuration and transport decisions that determine who can reach Argo CD and how long that access lasts.

Disable the built-in admin account

The local admin user exists for first-time setup. Once GitHub login and at least one mapped team role work, set admin.enabled to false so that a shared password cannot bypass GitHub membership. Before you disable it, confirm that a platform owner can still reach Argo CD through an SSO-mapped admin role, because a broken Dex configuration with no admin path can lock everyone out. Keep a documented break-glass procedure for that case.

Keep the OAuth client secret out of Git

The GitHub OAuth App client secret is referenced by Dex configuration, and it must not appear in manifests committed to a repository, including the repository that holds your Argo CD configuration. Store it in a Kubernetes Secret or an external secrets operator, and reference it by key from the Dex configuration. Rotate the secret on a schedule you can name, and confirm that rotation does not require editing committed files.

Request only organization and team read

Limit the OAuth App to the read scopes needed to confirm organization and team membership. Broader scopes let Dex act on repositories and other data that Argo CD does not need. Review the requested scopes on the OAuth App and in the Dex connector settings, then confirm the grant screen shows the same list. Repeat this review after any change to the connector.

Restrict edits to argocd-cm and argocd-rbac-cm

The argocd-cm ConfigMap holds the Dex connector and the OAuth settings, and argocd-rbac-cm holds the policy that maps teams to roles. Whoever can edit either object can grant themselves admin rights. Limit write access to a small platform group through Kubernetes RBAC, and route changes through Git review so that every mapping change has an approver and a history.

Encrypt traffic to Argo CD and GHES

Serve Argo CD only over TLS, and confirm that the callback URL registered with the GitHub OAuth App uses HTTPS. If you run GitHub Enterprise Server, confirm that the hostname Dex calls is served with a certificate that Dex trusts, because a mismatched or private certificate authority is a common cause of failed logins. Check that the connector uses the GHES hostname you intend, not a placeholder.

Plan for removed members keeping access

Removing someone from a GitHub team does not end an Argo CD session that is already issued. Argo CD authenticates API requests only with JSON Web Tokens, and Dex-issued tokens remain valid until they expire. Ask your team which token lifetime applies in your build, and document how you revoke access for a departing engineer ahead of expiry. Also confirm that Argo CD redacts cluster, Git and OAuth2 credentials from API responses and logs, which limits what a token holder can read.

Why GitHub login to Argo CD fails and how to fix it

This table lists the failures teams most often hit when wiring GitHub or GitHub Enterprise Server login into Argo CD through Dex, with the likely cause and the fix for each. Work down the rows in order, because the callback and hostname checks catch most problems before group mapping is reached. Confirm any behavior specific to your Argo CD and Dex versions against the release notes before changing production settings.

Symptom	Likely cause	Fix to check first
Redirect fails with a callback URL mismatch	The OAuth app callback URL in GitHub does not match the Argo CD URL plus the Dex callback path, often because the scheme, host or trailing slash differs.	Set the callback URL on the GitHub OAuth app to the exact address Argo CD uses for Dex, then confirm the url key in argocd-cm matches it.
Login page loads but GitHub Enterprise sign-in errors	The GitHub Enterprise Server hostname in the Dex connector is wrong, or the instance uses a private root CA that Dex does not trust.	Confirm the hostName value matches the server, add the internal root CA to Dex's trusted certificates, then retry the browser login.
User signs in but gets no permissions	The user is not a member of the organization or the team listed in the connector, so no group claim is returned.	Check the user's organization and team membership in GitHub, then confirm the teams entry in the connector uses the team name Dex expects.
Group mapping stops working after a team rename	Team slugs change when a team is renamed, so the old slug in policy.csv no longer matches the group Dex returns.	Look up the current team slug in GitHub, update the g lines in argocd-rbac-cm, and test with a user from that team.
Groups are missing from the token or RBAC does not apply	The token carries no groups claim because the scopes setting does not request the groups scope, or RBAC keys on the wrong claim.	Add the groups scope to the Dex connector configuration and confirm RBAC matches the claim name your version uses, since the 3.0 upgrade notes changed Dex-based RBAC to federated_claims.user_id.
Local admin account still works	The built-in admin user was left enabled after SSO was configured, which leaves a password-based path that bypasses SSO controls.	After confirming SSO administrator access works, set admin.enabled to false, and keep a tested break-glass path outside the cluster.
Web login works but argocd login --sso fails	The CLI client, its localhost callback or PKCE settings are not configured for the CLI, so the redirect is rejected.	Check the CLI client settings and redirect handling for your release, since CLI SSO behavior has changed across versions, and confirm against the current user management documentation.
Users see fewer applications than expected	Project roles or RBAC rules are bound to groups that do not match the team names or slugs users belong to.	Test one account per team with argocd account can-i or the UI, and compare the returned group names with the policy lines one by one.

Questions teams ask before connecting GitHub to Argo CD

Can our team set up GitHub login for Argo CD without outside help?

Yes, many teams can, provided someone on the team understands Argo CD's Dex configuration, GitHub OAuth applications and Argo CD RBAC. The Argo CD user management guide documents a GitHub connector and an example for GitHub Enterprise, so the configuration itself is well documented. Effort rises with the number of GitHub organizations, the number of teams that need roles, whether you run GitHub Enterprise Server (GHES) and how much RBAC design is needed across Argo CD projects. A single organization with a few teams and one GitHub.com tenant is a small task. Multiple organizations, a self-hosted GHES instance and a role model that spans many projects are larger, and a fixed-scope partner engagement is one way to get that work agreed in writing before it starts.

What does GitHub login for Argo CD cost in licensing?

The Argo CD connector itself is open source under Apache-2.0, so the cost is in the GitHub side and in people's time. GitHub's pricing page lists Team at $4 and Enterprise at $21 per user per month, and Enterprise is available either as GitHub Enterprise Cloud or as self-hosted GitHub Enterprise Server. Which plan you already hold determines whether sign-in needs a new license at all, so confirm your current GitHub plan with your account team before assuming any change. Recurring costs are the seats you already pay for and the time spent maintaining the Dex configuration and team mappings. Ask a partner for a quote that lists who does each task and what is recurring after handover.

What infrastructure does a self-hosted GitHub Enterprise Server need?

Only teams that run GHES need to plan this, because Argo CD itself does not require it. GitHub's VMware installation guide lists minimum recommended resources of 8 vCPUs, 48 GB memory, 400 GB root storage and 500 GB data storage for up to 1,000 user licenses. For 8,000 to 10,000 or more licenses, the same guide recommends 64 vCPUs, 512 GB memory and 5,000 GB data storage. GitHub advises increasing CPU and memory by at least 25% when GitHub Actions or GitHub Code Security is enabled. GitHub Actions on GHES also needs external blob storage and at least 8 vCPU and 64 GB memory, and it supports only self-hosted runners. Confirm the hypervisor versions and sizing against the current GitHub documentation before you buy hardware.

What do we need to provide before the work starts?

The work depends on access that only your organization can grant. You need a GitHub organization owner or an admin who can create and manage an OAuth application for Argo CD, and someone who can confirm which organization and team names will map to Argo CD roles. The Argo CD cluster must reach GitHub.com or your GHES hostname over HTTPS, and the OAuth callback URL must resolve from your users' networks. If you use GHES, you also need a named owner for the GHES instance, its certificates and its upgrade calendar. Administrative access to the Argo CD namespace and the Dex configuration is required, and a test group of engineers should be available to verify sign-in before rollout.

How long does a GitHub login project take?

The duration depends on scope, and no fixed timeline applies to every organization. The main drivers are the number of GitHub organizations, how many teams need distinct Argo CD roles, whether GHES is involved and how quickly your team confirms the role design and test results. Work usually starts with agreeing scope, then the OAuth application and Dex configuration, then a test group, then the role mapping, then rollout. Ask any provider for a written schedule tied to the agreed deliverables, and check which steps depend on your organization's approvals, such as GitHub organization owner sign-off or change windows for the Argo CD namespace.

What happens to GitHub Enterprise Server sign-in during an upgrade?

Patch releases usually cause very little interruption. GitHub's upgrade overview says GHES patch releases typically require less than five minutes of downtime, while feature releases that include data migrations may cause a few hours of downtime, depending on storage performance and data volume. Sign-in to Argo CD depends on GHES being reachable, so a GHES outage blocks new logins to Argo CD, though existing deployments continue to run. Plan the GHES upgrade window together with the Argo CD team, confirm the GHES release line you are on is still supported, and verify the Argo CD GitHub login after each GHES upgrade. Also check the OAuth application settings, because the GHES hostname or certificate changes can break the callback.

Should we map GitHub teams to Argo CD roles or use individual accounts?

Map GitHub teams to Argo CD roles, because team membership in GitHub is the source of truth for who should deploy where. Individual role grants become hard to audit once more than a few people need access. Each Argo CD project should have roles bound to teams, and the mapping should be tested with a small group before rollout. Automation accounts should not depend on a person's GitHub team membership, so plan them separately as local accounts or project tokens. Ask for a documented mapping table that lists each GitHub organization, team, Argo CD project and permission level.

How DeployOpen scopes and delivers Argo CD GitHub sign-in

DeployOpen plans, builds and hands over Argo CD sign-in with GitHub or GitHub Enterprise through the bundled Dex connector, inside infrastructure you control. Engagements are fixed-scope, so the organization, team mappings, testing and handover are agreed in writing before any configuration changes.

How we scope

We confirm whether you use github.com, GitHub Enterprise Cloud or a self-hosted GitHub Enterprise Server instance, and who administers it.
We map which GitHub organizations and teams should receive Argo CD admin, project and read-only roles.
We agree in writing which clusters, Argo CD projects and automation accounts fall inside the engagement.

How we build

We configure the bundled Dex GitHub connector with an OAuth application and store its client secret outside Git.
We map GitHub team membership to Argo CD RBAC policy and test each role with real test accounts before rollout.
We disable the built-in admin user with admin.enabled set to false once SSO sign-in has been verified.

How we hand over

We document the OAuth app settings, callback URL, Dex configuration and team-to-role mapping for your administrators.
We record the test cases and results that show each GitHub team lands in the intended Argo CD permissions.
We walk your engineers through how to add a team, revoke access and confirm a change in the RBAC policy.

How we support

Ongoing support, Argo CD upgrades and continuous testing are available as retainers agreed separately from the initial scope.
We can plan Argo CD version updates against the supported patch releases so Dex and RBAC changes are re-tested each cycle.
Support scope, response expectations and fees are confirmed in a written quote that follows from the agreed scope.

Argo CD login with GitHub or GitHub Enterprise through Dex