`github_org`¶

Manage a GitHub organization: members, teams and organization rulesets.

Added in version 1.1.0.

Unlike the legacy functions in the github module, the functions in this module raise errors (usually subclasses of CommandExecutionError) instead of logging them and returning False.

Collections with a unique natural key (teams, team repositories) are returned as mappings keyed by it, id-addressed collections (rulesets) as lists.

Note

This module is organization-scoped: all functions target an organization, defaulting to the profile’s owner (which hence must be an organization) and accepting an owner argument to manage another organization. Repository listing and creation live in the github_repo module since they also apply to user accounts.

depends:: PyGithub python module

Configuration¶

This module reads its configuration from profiles, which are described in the configuration guide. The profile’s owner must be set to the managed organization.

saltext.github.modules.github_org.info(name=None, profile='github')[source]¶

Return the public profile of an organization account. Fails when the account is a user. Use github.account_info to look up accounts of either type.

CLI Example:

salt-call github_org.info github-org
salt-call github_org.info  # the profile's owner

name: Login of the organization to look up. Defaults to the organization specified in the profile’s owner.
profile: Profile configuration name to use. Defaults to github.

saltext.github.modules.github_org.list_members(owner=None, ignore_cache=False, profile='github')[source]¶

List the logins of all members of the organization.

CLI Example:

salt-call github_org.list_members

owner: Organization to target. Defaults to the profile’s owner.
ignore_cache: Bypass the use of cached members.
profile: Profile configuration name to use. Defaults to github.

saltext.github.modules.github_org.get_member(name, owner=None, profile='github')[source]¶

Return information about a user, including their organization membership state (in_org and membership_state).

CLI Example:

salt-call github_org.get_member github-handle

name: Login of the user.
owner: Organization to target. Defaults to the profile’s owner.
profile: Profile configuration name to use. Defaults to github.

saltext.github.modules.github_org.add_member(name, owner=None, profile='github')[source]¶

Invite a user into the organization. Returns whether the resulting membership is pending (i.e. an invitation that needs to be accepted first).

CLI Example:

salt-call github_org.add_member github-handle

name: Login of the user to invite.
owner: Organization to target. Defaults to the profile’s owner.
profile: Profile configuration name to use. Defaults to github.

saltext.github.modules.github_org.remove_member(name, owner=None, profile='github')[source]¶

Remove a user from the organization.

CLI Example:

salt-call github_org.remove_member github-handle

name: Login of the user to remove.
owner: Organization to target. Defaults to the profile’s owner.
profile: Profile configuration name to use. Defaults to github.

saltext.github.modules.github_org.list_teams(owner=None, fields=None, ignore_cache=False, profile='github')[source]¶

List all teams of the organization, as a mapping of team name to team details.

CLI Example:

salt-call github_org.list_teams

owner: Organization owning the team. Defaults to the profile’s owner.
fields: Only include these fields in the output. A single field name reduces each entry to the field’s value.
ignore_cache: Bypass the use of cached teams.
profile: Profile configuration name to use. Defaults to github.

saltext.github.modules.github_org.get_team(name, owner=None, profile='github')[source]¶

Return the details of a single team.

CLI Example:

salt-call github_org.get_team 'team_name'

name: Name of the team.
owner: Organization owning the team. Defaults to the profile’s owner.
profile: Profile configuration name to use. Defaults to github.

saltext.github.modules.github_org.add_team(name, description=None, repo_names=None, privacy=None, permission=None, owner=None, profile='github')[source]¶

Create a new team within the organization. Returns the details of the created team.

CLI Example:

salt-call github_org.add_team 'team_name'

name: Name of the team to create.
description: Team description.
repo_names: Names of repositories to add the team to.
privacy: Privacy level for the team, either secret or closed.
permission: Default permission for new repositories added to the team, either pull, push or admin.
owner: Organization owning the team. Defaults to the profile’s owner.
profile: Profile configuration name to use. Defaults to github.

saltext.github.modules.github_org.edit_team(name, description=None, privacy=None, permission=None, owner=None, profile='github')[source]¶

Update an existing team. Returns the refreshed team details.

CLI Example:

salt-call github_org.edit_team 'team_name' description='Team description'

name: Name of the team to edit.
description: Team description.
privacy: Privacy level for the team, either secret or closed.
permission: Default permission for new repositories added to the team, either pull, push or admin.
owner: Organization owning the team. Defaults to the profile’s owner.
profile: Profile configuration name to use. Defaults to github.

saltext.github.modules.github_org.remove_team(name, owner=None, profile='github')[source]¶

Remove a team from the organization.

CLI Example:

salt-call github_org.remove_team 'team_name'

name: Name of the team to remove.
owner: Organization owning the team. Defaults to the profile’s owner.
profile: Profile configuration name to use. Defaults to github.

saltext.github.modules.github_org.list_team_repos(team_name, owner=None, fields=None, ignore_cache=False, profile='github')[source]¶

Return the repositories of a team, as a mapping of repository name to team-specific details (permission).

CLI Example:

salt-call github_org.list_team_repos 'team_name'

team_name: Name of the team from which to list repos.
owner: Organization owning the team. Defaults to the profile’s owner.
fields: Only include these fields in the output. A single field name reduces each entry to the field’s value.
ignore_cache: Bypass the use of cached team repos.
profile: Profile configuration name to use. Defaults to github.

saltext.github.modules.github_org.add_team_repo(repo_name, team_name, permission=None, owner=None, profile='github')[source]¶

Add a repository to a team, or update the permission the team has on it.

CLI Example:

salt-call github_org.add_team_repo 'my_repo' 'team_name'

repo_name: Name of the repository to add.
team_name: Name of the team to add the repository to.
permission: Permission for team members within the repository, either pull, push or admin. If not specified, the team’s default permission is used.
owner: Organization owning the team. Defaults to the profile’s owner.
profile: Profile configuration name to use. Defaults to github.

saltext.github.modules.github_org.remove_team_repo(repo_name, team_name, owner=None, profile='github')[source]¶

Remove a repository from a team.

CLI Example:

salt-call github_org.remove_team_repo 'my_repo' 'team_name'

repo_name: Name of the repository to remove.
team_name: Name of the team to remove the repository from.
owner: Organization owning the team. Defaults to the profile’s owner.
profile: Profile configuration name to use. Defaults to github.

saltext.github.modules.github_org.list_team_members(team_name, owner=None, ignore_cache=False, profile='github')[source]¶

Return the logins of a team’s members, in lower case.

CLI Example:

salt-call github_org.list_team_members 'team_name'

team_name: Name of the team from which to list members.
owner: Organization owning the team. Defaults to the profile’s owner.
ignore_cache: Bypass the use of cached team members.
profile: Profile configuration name to use. Defaults to github.

saltext.github.modules.github_org.is_team_member(name, team_name, owner=None, profile='github')[source]¶

Return whether a user is a member of a team.

CLI Example:

salt-call github_org.is_team_member 'user_name' 'team_name'

name: Login of the user whose membership to check.
team_name: Name of the team to check membership in.
owner: Organization owning the team. Defaults to the profile’s owner.
profile: Profile configuration name to use. Defaults to github.

saltext.github.modules.github_org.add_team_member(name, team_name, owner=None, profile='github')[source]¶

Add an organization member to a team.

CLI Example:

salt-call github_org.add_team_member 'user_name' 'team_name'

name: Login of the user to add.
team_name: Name of the team to add the user to.
owner: Organization owning the team. Defaults to the profile’s owner.
profile: Profile configuration name to use. Defaults to github.

saltext.github.modules.github_org.remove_team_member(name, team_name, owner=None, profile='github')[source]¶

Remove a member from a team.

CLI Example:

salt-call github_org.remove_team_member 'user_name' 'team_name'

name: Login of the user to remove.
team_name: Name of the team to remove the user from.
owner: Organization owning the team. Defaults to the profile’s owner.
profile: Profile configuration name to use. Defaults to github.

saltext.github.modules.github_org.list_rulesets(owner=None, per_page=None, fields=None, profile='github')[source]¶

List all rulesets of the organization.

CLI Example:

salt-call github_org.list_rulesets

owner: Organization to target. Defaults to the profile’s owner.
per_page: Pagination size, maximum 100.
fields: Only include these fields in the output. A single field name reduces each entry to the field’s value.
profile: Profile configuration name to use. Defaults to github.

saltext.github.modules.github_org.get_ruleset(ruleset_id, owner=None, profile='github')[source]¶

Return the data of a single organization ruleset.

CLI Example:

salt-call github_org.get_ruleset 1234

ruleset_id: ID of the ruleset.
owner: Organization to target. Defaults to the profile’s owner.
profile: Profile configuration name to use. Defaults to github.

saltext.github.modules.github_org.add_ruleset(ruleset_params, owner=None, profile='github')[source]¶

Create a new organization ruleset. Returns the data of the created ruleset.

CLI Example:

salt-call github_org.add_ruleset '{name: test, enforcement: active}'

ruleset_params: Ruleset definition. Must contain at least name and enforcement.
owner: Organization to target. Defaults to the profile’s owner.
profile: Profile configuration name to use. Defaults to github.

saltext.github.modules.github_org.update_ruleset(ruleset_id, ruleset_params, owner=None, profile='github')[source]¶

Update an existing organization ruleset. Returns the data of the updated ruleset.

CLI Example:

salt-call github_org.update_ruleset 1234 '{enforcement: disabled}'

ruleset_id: ID of the ruleset.
ruleset_params: Updated ruleset definition.
owner: Organization to target. Defaults to the profile’s owner.
profile: Profile configuration name to use. Defaults to github.

saltext.github.modules.github_org.delete_ruleset(ruleset_id, owner=None, profile='github')[source]¶

Delete an organization ruleset.

CLI Example:

salt-call github_org.delete_ruleset 1234

ruleset_id: ID of the ruleset.
owner: Organization to target. Defaults to the profile’s owner.
profile: Profile configuration name to use. Defaults to github.

github_org¶

Configuration¶

`github_org`¶