memberships

Creates, updates, deletes, gets or lists a memberships resource.

Overview

Name	memberships
Type	Resource
Id	github.orgs.memberships

Fields

The following fields are returned by SELECT queries:

get_membership_for_user

Response

Name	Datatype	Description
direct_membership	boolean	Whether the user has direct membership in the organization.
enterprise_teams_providing_indirect_membership	array	The slugs of the enterprise teams providing the user with indirect membership in the organization. A limit of 100 enterprise team slugs is returned.
organization	object	A GitHub organization. (title: Organization Simple)
organization_url	string (uri)	(example: https://api.github.com/orgs/octocat)
permissions	object
role	string	The user's membership type in the organization. (admin, member, billing_manager) (example: admin)
state	string	The state of the member in the organization. The pending state indicates the user has not yet accepted an invitation. (active, pending) (example: active)
url	string (uri)	(example: https://api.github.com/orgs/octocat/memberships/defunkt)
user	object	A GitHub user. (title: Simple User)

get_membership_for_authenticated_user

Response

Name	Datatype	Description
direct_membership	boolean	Whether the user has direct membership in the organization.
enterprise_teams_providing_indirect_membership	array	The slugs of the enterprise teams providing the user with indirect membership in the organization. A limit of 100 enterprise team slugs is returned.
organization	object	A GitHub organization. (title: Organization Simple)
organization_url	string (uri)	(example: https://api.github.com/orgs/octocat)
permissions	object
role	string	The user's membership type in the organization. (admin, member, billing_manager) (example: admin)
state	string	The state of the member in the organization. The pending state indicates the user has not yet accepted an invitation. (active, pending) (example: active)
url	string (uri)	(example: https://api.github.com/orgs/octocat/memberships/defunkt)
user	object	A GitHub user. (title: Simple User)

list_memberships_for_authenticated_user

Response

Name	Datatype	Description
direct_membership	boolean	Whether the user has direct membership in the organization.
enterprise_teams_providing_indirect_membership	array	The slugs of the enterprise teams providing the user with indirect membership in the organization. A limit of 100 enterprise team slugs is returned.
organization	object	A GitHub organization. (title: Organization Simple)
organization_url	string (uri)	(example: https://api.github.com/orgs/octocat)
permissions	object
role	string	The user's membership type in the organization. (admin, member, billing_manager) (example: admin)
state	string	The state of the member in the organization. The pending state indicates the user has not yet accepted an invitation. (active, pending) (example: active)
url	string (uri)	(example: https://api.github.com/orgs/octocat/memberships/defunkt)
user	object	A GitHub user. (title: Simple User)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_membership_for_user	select	org, username		In order to get a user's membership with an organization, the authenticated user must be an organization member. The state parameter in the response can be used to identify the user's membership status.
get_membership_for_authenticated_user	select	org		If the authenticated user is an active or pending member of the organization, this endpoint will return the user's membership. If the authenticated user is not affiliated with the organization, a 404 is returned. This endpoint will return a 403 if the request is made by a GitHub App that is blocked by the organization.
list_memberships_for_authenticated_user	select		state, per_page, page	Lists all of the authenticated user's organization memberships.
update_membership_for_authenticated_user	update	org, state		Converts the authenticated user to an active member of the organization, if that user has a pending invitation from the organization.
set_membership_for_user	replace	org, username		Only authenticated organization owners can add a member to the organization or update the member's role. * If the authenticated user is adding a member to the organization, the invited user will receive an email inviting them to the organization. The user's membership status will be pending until they accept the invitation. * Authenticated users can update a user's membership by passing the role parameter. If the authenticated user changes a member's role to admin, the affected user will receive an email notifying them that they've been made an organization owner. If the authenticated user changes an owner's role to member, no email will be sent. Rate limits To prevent abuse, organization owners are limited to creating 50 organization invitations for an organization within a 24 hour period. If the organization is more than one month old or on a paid plan, the limit is 500 invitations per 24 hour period.
remove_membership_for_user	delete	org, username		In order to remove a user's membership with an organization, the authenticated user must be an organization owner. If the specified user is an active member of the organization, this will remove them from the organization. If the specified user has been invited to the organization, this will cancel their invitation. The specified user will receive an email notification in both cases. > [!NOTE] > If a user has both direct membership in the organization as well as indirect membership via an enterprise team, only their direct membership will be removed. Their indirect membership via an enterprise team remains until the user is removed from the enterprise team.
check_membership_for_user	exec	org, username		Check if a user is, publicly or privately, a member of the organization.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
org	string	The organization name. The name is not case sensitive.
username	string	The handle for the GitHub user account.
page	integer	The page number of the results to fetch. For more information, see "Using pagination in the REST API."
per_page	integer	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
state	string	Indicates the state of the memberships to return. If not specified, the API returns both active and pending memberships.

SELECT examples

get_membership_for_user

In order to get a user's membership with an organization, the authenticated user must be an organization member. The state parameter in the response can be used to identify the user's membership status.

SELECT
direct_membership,
enterprise_teams_providing_indirect_membership,
organization,
organization_url,
permissions,
role,
state,
url,
user
FROM github.orgs.memberships
WHERE org = '{{ org }}' -- required
AND username = '{{ username }}' -- required
;

get_membership_for_authenticated_user

If the authenticated user is an active or pending member of the organization, this endpoint will return the user's membership. If the authenticated user is not affiliated with the organization, a 404 is returned. This endpoint will return a 403 if the request is made by a GitHub App that is blocked by the organization.

SELECT
direct_membership,
enterprise_teams_providing_indirect_membership,
organization,
organization_url,
permissions,
role,
state,
url,
user
FROM github.orgs.memberships
WHERE org = '{{ org }}' -- required
;

list_memberships_for_authenticated_user

Lists all of the authenticated user's organization memberships.

SELECT
direct_membership,
enterprise_teams_providing_indirect_membership,
organization,
organization_url,
permissions,
role,
state,
url,
user
FROM github.orgs.memberships
WHERE state = '{{ state }}'
AND per_page = '{{ per_page }}'
AND page = '{{ page }}'
;

UPDATE examples

update_membership_for_authenticated_user

Converts the authenticated user to an active member of the organization, if that user has a pending invitation from the organization.

UPDATE github.orgs.memberships
SET 
state = '{{ state }}'
WHERE 
org = '{{ org }}' --required
AND state = '{{ state }}' --required
RETURNING
direct_membership,
enterprise_teams_providing_indirect_membership,
organization,
organization_url,
permissions,
role,
state,
url,
user;

REPLACE examples

set_membership_for_user

Only authenticated organization owners can add a member to the organization or update the member's role.

* If the authenticated user is adding a member to the organization, the invited user will receive an email inviting them to the organization. The user's membership status will be pending until they accept the invitation.

* Authenticated users can update a user's membership by passing the role parameter. If the authenticated user changes a member's role to admin, the affected user will receive an email notifying them that they've been made an organization owner. If the authenticated user changes an owner's role to member, no email will be sent.

Rate limits

To prevent abuse, organization owners are limited to creating 50 organization invitations for an organization within a 24 hour period. If the organization is more than one month old or on a paid plan, the limit is 500 invitations per 24 hour period.

REPLACE github.orgs.memberships
SET 
role = '{{ role }}'
WHERE 
org = '{{ org }}' --required
AND username = '{{ username }}' --required
RETURNING
direct_membership,
enterprise_teams_providing_indirect_membership,
organization,
organization_url,
permissions,
role,
state,
url,
user;

DELETE examples

remove_membership_for_user

In order to remove a user's membership with an organization, the authenticated user must be an organization owner.

If the specified user is an active member of the organization, this will remove them from the organization. If the specified user has been invited to the organization, this will cancel their invitation. The specified user will receive an email notification in both cases.

> [!NOTE]
> If a user has both direct membership in the organization as well as indirect membership via an enterprise team, only their direct membership will be removed. Their indirect membership via an enterprise team remains until the user is removed from the enterprise team.

DELETE FROM github.orgs.memberships
WHERE org = '{{ org }}' --required
AND username = '{{ username }}' --required
;

Lifecycle Methods

check_membership_for_user

Check if a user is, publicly or privately, a member of the organization.

EXEC github.orgs.memberships.check_membership_for_user 
@org='{{ org }}' --required, 
@username='{{ username }}' --required
;