`github`¶

General module for interacting with the GitHub v3 API.

Contains functionality that is not tied to a single organization or repository, e.g. generic account lookups, the token’s API rate limit status or direct queries against arbitrary API endpoints.

depends:: PyGithub python module

Important

All organization- and repository-related functions in this module are deprecated in favor of the github_org and github_repo modules, which raise errors instead of logging and returning False. The non-deprecated functions in this module behave like the scoped modules in this regard.

Configuration¶

This module reads its configuration from profiles, which are described in the configuration guide. All functions accept a profile argument, defaulting to the github profile.

saltext.github.modules.github.query(path, params=None, method='GET', headers=None, data=None, per_page=None, profile='github')[source]¶

Make a direct call to the GitHub API, transparently following pagination. Useful for endpoints without a dedicated wrapper function.

Added in version 1.1.0.

CLI Example:

salt-call github.query repos/saltstack/salt
salt-call github.query orgs/my-org/members per_page=100
salt-call github.query repos/my-org/my-repo/labels method=POST data='{name: bug}'

path: URL path to query, either as a string or a list of segments.
params: Mapping of query parameters.
method: HTTP method to use. Defaults to GET.
headers: Mapping of extra headers to send.
data: Request body, either as a mapping or a JSON string.
per_page: Pagination size, maximum 100.
profile: Profile configuration name to use. Defaults to github.

Returns the decoded response data. List results are merged across pages. Raises CommandExecutionError subclasses on error responses.

saltext.github.modules.github.rate_limit(profile='github')[source]¶

Return the API rate limit status of the profile’s token, keyed by resource (core, search, …).

Added in version 1.1.0.

CLI Example:

salt-call github.rate_limit

profile: Profile configuration name to use. Defaults to github.

saltext.github.modules.github.revoke_app_token(profile='github')[source]¶

Revoke the GitHub App installation access token the profile currently authenticates with and drop the associated cached connections, ensuring a subsequent call mints a fresh token. Only valid for GitHub App (app_id) profiles.

Minted tokens are valid for one hour (fixed by GitHub) and are never persisted by this extension, so revocation is optional hygiene – useful e.g. as the last step of an ephemeral CI run.

Added in version 1.1.0.

CLI Example:

salt-call github.revoke_app_token

profile: Profile configuration name to use. Defaults to github.

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

Return the public profile of any user or organization account (distinguished via the returned type field).

The scoped variants of this function — github_user.info and github_org.info — fail when the account is not of the corresponding type.

Added in version 1.1.0.

CLI Example:

salt-call github.account_info github-handle
salt-call github.account_info  # the profile's owner

name: Login of the account to look up. Defaults to the profile’s owner (which itself defaults to the token’s user).
profile: Profile configuration name to use. Defaults to github.

saltext.github.modules.github.get_user(name, profile='github', user_details=False)[source]¶

Get a GitHub user by name.

Deprecated since version 1.1.0: Despite its name, this function looks up the user’s membership in the profile’s organization, not a generic user account. Use github_org.get_member for the same functionality, or github.account_info for looking up arbitrary accounts.

name: The user for which to obtain information.
profile: The name of the profile configuration to use. Defaults to github.
user_details: Prints user information details. Defaults to False. If the user is already in the organization and user_details is set to False, the get_user function returns True. If the user is not already present in the organization, user details will be printed by default.

CLI Example:

salt myminion github.get_user github-handle
salt myminion github.get_user github-handle user_details=true

saltext.github.modules.github.list_users(profile='github', ignore_cache=False)[source]¶

List all users within the organization.

Deprecated since version 1.1.0: Use github_org.list_members instead.

profile: The name of the profile configuration to use. Defaults to github.
ignore_cache: Bypasses the use of cached users.

CLI Example:

salt myminion github.list_users
salt myminion github.list_users profile='my-github-profile'

saltext.github.modules.github.add_user(name, profile='github')[source]¶

Add a GitHub user.

Deprecated since version 1.1.0: Use github_org.add_member instead.

name: The user for which to obtain information.
profile: The name of the profile configuration to use. Defaults to github.

CLI Example:

salt myminion github.add_user github-handle

saltext.github.modules.github.remove_user(name, profile='github')[source]¶

Remove a Github user by name.

Deprecated since version 1.1.0: Use github_org.remove_member instead.

name: The user for which to obtain information.
profile: The name of the profile configuration to use. Defaults to github.

CLI Example:

salt myminion github.remove_user github-handle

saltext.github.modules.github.get_issue(issue_number, repo_name=None, profile='github', output='min')[source]¶

Return information about a single issue in a named repository.

Deprecated since version 1.1.0: Use github_repo.get_issue instead.

issue_number: The number of the issue to retrieve.
repo_name: The name of the repository from which to get the issue. This argument is required, either passed via the CLI, or defined in the configured profile. A repo_name passed as a CLI argument will override the repo_name defined in the configured profile, if provided.
profile: The name of the profile configuration to use. Defaults to github.
output: The amount of data returned by each issue. Defaults to min. Change to full to see all issue output.

CLI Example:

salt myminion github.get_issue 514
salt myminion github.get_issue 514 repo_name=salt

saltext.github.modules.github.get_issue_comments(issue_number, repo_name=None, profile='github', since=None, output='min')[source]¶

Return information about the comments for a given issue in a named repository.

Deprecated since version 1.1.0: Use github_repo.get_issue_comments instead.

issue_number: The number of the issue for which to retrieve comments.
repo_name: The name of the repository to which the issue belongs. This argument is required, either passed via the CLI, or defined in the configured profile. A repo_name passed as a CLI argument will override the repo_name defined in the configured profile, if provided.
profile: The name of the profile configuration to use. Defaults to github.
since: Only comments updated at or after this time are returned. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.
output: The amount of data returned by each issue. Defaults to min. Change to full to see all issue output.

CLI Example:

salt myminion github.get_issue_comments 514
salt myminion github.get_issue 514 repo_name=salt

saltext.github.modules.github.get_issues(repo_name=None, profile='github', milestone=None, state='open', assignee=None, creator=None, mentioned=None, labels=None, sort='created', direction='desc', since=None, output='min', per_page=None)[source]¶

Returns information for all issues in a given repository, based on the search options.

Deprecated since version 1.1.0: Use github_repo.list_issues instead.

repo_name

The name of the repository for which to list issues. This argument is required, either passed via the CLI, or defined in the configured profile. A repo_name passed as a CLI argument will override the repo_name defined in the configured profile, if provided.

profile

The name of the profile configuration to use. Defaults to github.

milestone

The number of a GitHub milestone, or a string of either * or none.

If a number is passed, it should refer to a milestone by its number field. Use the github.get_milestone function to obtain a milestone’s number.

If the string * is passed, issues with any milestone are accepted. If the string none is passed, issues without milestones are returned.

state

Indicates the state of the issues to return. Can be either open, closed, or all. Default is open.

assignee

Can be the name of a user. Pass in none (as a string) for issues with no assigned user or * for issues assigned to any user.

creator

The user that created the issue.

mentioned

A user that’s mentioned in the issue.

labels

A string of comma separated label names. For example, bug,ui,@high.

sort

What to sort results by. Can be either created, updated, or comments. Default is created.

direction

The direction of the sort. Can be either asc or desc. Default is desc.

since

Only issues updated at or after this time are returned. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.

output

The amount of data returned by each issue. Defaults to min. Change to full to see all issue output.

per_page

GitHub paginates data in their API calls. Use this value to increase or decrease the number of issues gathered from GitHub, per page. If not set, GitHub defaults are used. Maximum is 100.

CLI Example:

salt myminion github.get_issues my-github-repo

saltext.github.modules.github.get_milestones(repo_name=None, profile='github', state='open', sort='due_on', direction='asc', output='min', per_page=None)[source]¶

Return information about milestones for a given repository.

Deprecated since version 1.1.0: Use github_repo.list_milestones instead.

repo_name: The name of the repository for which to list issues. This argument is required, either passed via the CLI, or defined in the configured profile. A repo_name passed as a CLI argument will override the repo_name defined in the configured profile, if provided.
profile: The name of the profile configuration to use. Defaults to github.
state: The state of the milestone. Either open, closed, or all. Default is open.
sort: What to sort results by. Either due_on or completeness. Default is due_on.
direction: The direction of the sort. Either asc or desc. Default is asc.
output: The amount of data returned by each issue. Defaults to min. Change to full to see all issue output.
per_page: GitHub paginates data in their API calls. Use this value to increase or decrease the number of issues gathered from GitHub, per page. If not set, GitHub defaults are used.

CLI Example:

salt myminion github.get_milestones

saltext.github.modules.github.get_milestone(number=None, name=None, repo_name=None, profile='github', output='min')[source]¶

Return information about a single milestone in a named repository.

Deprecated since version 1.1.0: Use github_repo.get_milestone instead.

number: The number of the milestone to retrieve. If provided, this option will be favored over name.
name: The name of the milestone to retrieve.
repo_name: The name of the repository for which to list issues. This argument is required, either passed via the CLI, or defined in the configured profile. A repo_name passed as a CLI argument will override the repo_name defined in the configured profile, if provided.
profile: The name of the profile configuration to use. Defaults to github.
output: The amount of data returned by each issue. Defaults to min. Change to full to see all issue output.

CLI Example:

salt myminion github.get_milestone 72
salt myminion github.get_milestone name=my_milestone

saltext.github.modules.github.get_repo_info(repo_name, profile='github', ignore_cache=False)[source]¶

Return information for a given repo.

Deprecated since version 1.1.0: Use github_repo.info instead.

repo_name: The name of the repository.
profile: The name of the profile configuration to use. Defaults to github.

CLI Example:

salt myminion github.get_repo_info salt
salt myminion github.get_repo_info salt profile='my-github-profile'

saltext.github.modules.github.get_repo_teams(repo_name, profile='github')[source]¶

Return teams belonging to a repository.

Deprecated since version 1.1.0: Use github_repo.get_teams instead.

repo_name: The name of the repository from which to retrieve teams.
profile: The name of the profile configuration to use. Defaults to github.

CLI Example:

salt myminion github.get_repo_teams salt
salt myminion github.get_repo_teams salt profile='my-github-profile'

saltext.github.modules.github.list_repos(profile='github')[source]¶

List all repositories within the organization. Includes public and private repositories within the organization Dependent upon the access rights of the profile token.

Deprecated since version 1.1.0: Use github_org.list_repos instead.

profile: The name of the profile configuration to use. Defaults to github.

CLI Example:

salt myminion github.list_repos
salt myminion github.list_repos profile='my-github-profile'

saltext.github.modules.github.list_private_repos(profile='github')[source]¶

List private repositories within the organization. Dependent upon the access rights of the profile token.

Deprecated since version 1.1.0: Use github_org.list_repos instead.

profile: The name of the profile configuration to use. Defaults to github.

CLI Example:

salt myminion github.list_private_repos
salt myminion github.list_private_repos profile='my-github-profile'

saltext.github.modules.github.list_public_repos(profile='github')[source]¶

List public repositories within the organization.

Deprecated since version 1.1.0: Use github_org.list_repos instead.

profile: The name of the profile configuration to use. Defaults to github.

CLI Example:

salt myminion github.list_public_repos
salt myminion github.list_public_repos profile='my-github-profile'

saltext.github.modules.github.add_repo(name, description=None, homepage=None, private=None, has_issues=None, has_wiki=None, has_downloads=None, auto_init=None, gitignore_template=None, license_template=None, profile='github')[source]¶

Create a new github repository.

Deprecated since version 1.1.0: Use github_org.add_repo instead.

name: The name of the team to be created.
description: The description of the repository.
homepage: The URL with more information about the repository.
private: The visiblity of the repository. Note that private repositories require a paid GitHub account.
has_issues: Whether to enable issues for this repository.
has_wiki: Whether to enable the wiki for this repository.
has_downloads: Whether to enable downloads for this repository.
auto_init: Whether to create an initial commit with an empty README.
gitignore_template: The desired language or platform for a .gitignore, e.g “Haskell”.
license_template: The desired LICENSE template to apply, e.g “mit” or “mozilla”.
profile: The name of the profile configuration to use. Defaults to github.

CLI Example:

salt myminion github.add_repo 'repo_name'

saltext.github.modules.github.edit_repo(name, description=None, homepage=None, private=None, has_issues=None, has_wiki=None, has_downloads=None, profile='github')[source]¶

Updates an existing Github repository.

Deprecated since version 1.1.0: Use github_repo.update instead.

name: The name of the team to be created.
description: The description of the repository.
homepage: The URL with more information about the repository.
private: The visiblity of the repository. Note that private repositories require a paid GitHub account.
has_issues: Whether to enable issues for this repository.
has_wiki: Whether to enable the wiki for this repository.
has_downloads: Whether to enable downloads for this repository.
profile: The name of the profile configuration to use. Defaults to github.

CLI Example:

salt myminion github.add_repo 'repo_name'

saltext.github.modules.github.remove_repo(name, profile='github')[source]¶

Remove a Github repository.

Deprecated since version 1.1.0: Use github_repo.delete instead.

name: The name of the repository to be removed.
profile: The name of the profile configuration to use. Defaults to github.

CLI Example:

salt myminion github.remove_repo 'my-repo'

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

Returns the team details if a team with the given name exists, or None otherwise.

Deprecated since version 1.1.0: Use github_org.get_team instead.

name: The team name for which to obtain information.
profile: The name of the profile configuration to use. Defaults to github.

CLI Example:

salt myminion github.get_team 'team_name'

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

Create a new Github team within an organization.

Deprecated since version 1.1.0: Use github_org.add_team instead.

name: The name of the team to be created.
description: The description of the team.
repo_names: The names of repositories to add the team to.
privacy: The level of privacy for the team, can be secret or closed.
permission: The default permission for new repositories added to the team, can be pull, push or admin.
profile: The name of the profile configuration to use. Defaults to github.

CLI Example:

salt myminion github.add_team 'team_name'

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

Updates an existing Github team.

Deprecated since version 1.1.0: Use github_org.edit_team instead.

name: The name of the team to be edited.
description: The description of the team.
privacy: The level of privacy for the team, can be secret or closed.
permission: The default permission for new repositories added to the team, can be pull, push or admin.
profile: The name of the profile configuration to use. Defaults to github.

CLI Example:

salt myminion github.edit_team 'team_name' description='Team description'

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

Remove a github team.

Deprecated since version 1.1.0: Use github_org.remove_team instead.

name: The name of the team to be removed.
profile: The name of the profile configuration to use. Defaults to github.

CLI Example:

salt myminion github.remove_team 'team_name'

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

Gets the repo details for a given team as a dict from repo_name to repo details. Note that repo names are always in lower case.

Deprecated since version 1.1.0: Use github_org.list_team_repos instead.

team_name: The name of the team from which to list repos.
profile: The name of the profile configuration to use. Defaults to github.
ignore_cache: Bypasses the use of cached team repos.

CLI Example:

salt myminion github.list_team_repos 'team_name'

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

Adds a repository to a team with team_name.

Deprecated since version 1.1.0: Use github_org.add_team_repo instead.

repo_name: The name of the repository to add.
team_name: The name of the team of which to add the repository.
profile: The name of the profile configuration to use. Defaults to github.
permission: The permission for team members within the repository, can be pull, push or admin. If not specified, the default permission specified on the team will be used.

CLI Example:

salt myminion github.add_team_repo 'my_repo' 'team_name'

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

Removes a repository from a team with team_name.

Deprecated since version 1.1.0: Use github_org.remove_team_repo instead.

repo_name: The name of the repository to remove.
team_name: The name of the team of which to remove the repository.
profile: The name of the profile configuration to use. Defaults to github.

CLI Example:

salt myminion github.remove_team_repo 'my_repo' 'team_name'

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

Gets the names of team members in lower case.

Deprecated since version 1.1.0: Use github_org.list_team_members instead.

team_name: The name of the team from which to list members.
profile: The name of the profile configuration to use. Defaults to github.
ignore_cache: Bypasses the use of cached team members.

CLI Example:

salt myminion github.list_team_members 'team_name'

saltext.github.modules.github.list_members_without_mfa(profile='github', ignore_cache=False)[source]¶

List all members (in lower case) without MFA turned on.

Deprecated since version 1.1.0: Deprecated without replacement, along with the per-team MFA enforcement of the github.team_present state. Require 2FA organization-wide in the GitHub settings instead.

profile: The name of the profile configuration to use. Defaults to github.
ignore_cache: Bypasses the use of cached team repos.

CLI Example:

salt myminion github.list_members_without_mfa

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

Returns True if the github user is in the team with team_name, or False otherwise.

Deprecated since version 1.1.0: Use github_org.is_team_member instead.

name: The name of the user whose membership to check.
team_name: The name of the team to check membership in.
profile: The name of the profile configuration to use. Defaults to github.

CLI Example:

salt myminion github.is_team_member 'user_name' 'team_name'

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

Adds a team member to a team with team_name.

Deprecated since version 1.1.0: Use github_org.add_team_member instead.

name: The name of the team member to add.
team_name: The name of the team of which to add the user.
profile: The name of the profile configuration to use. Defaults to github.

CLI Example:

salt myminion github.add_team_member 'user_name' 'team_name'

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

Removes a team member from a team with team_name.

Deprecated since version 1.1.0: Use github_org.remove_team_member instead.

name: The name of the team member to remove.
team_name: The name of the team from which to remove the user.
profile: The name of the profile configuration to use. Defaults to github.

CLI Example:

salt myminion github.remove_team_member 'user_name' 'team_name'

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

Lists all teams with the organization.

Deprecated since version 1.1.0: Use github_org.list_teams instead.

profile: The name of the profile configuration to use. Defaults to github.
ignore_cache: Bypasses the use of cached teams.

CLI Example:

salt myminion github.list_teams

saltext.github.modules.github.get_prs(repo_name=None, profile='github', state='open', head=None, base=None, sort='created', direction='desc', output='min', per_page=None)[source]¶

Returns information for all pull requests in a given repository, based on the search options provided.

Deprecated since version 1.1.0: Use github_repo.list_pulls instead.

repo_name: The name of the repository for which to list pull requests. This argument is required, either passed via the CLI, or defined in the configured profile. A repo_name passed as a CLI argument will override the repo_name defined in the configured profile, if provided.
profile: The name of the profile configuration to use. Defaults to github.
state: Indicates the state of the pull requests to return. Can be either open, closed, or all. Default is open.
head: Filter pull requests by head user and branch name in the format of user:ref-name. Example: 'github:new-script-format'. Default is None.
base: Filter pulls by base branch name. Example: gh-pages. Default is None.
sort: What to sort results by. Can be either created, updated, popularity (comment count), or long-running (age, filtering by pull requests updated within the last month). Default is created.
direction: The direction of the sort. Can be either asc or desc. Default is desc.
output: The amount of data returned by each pull request. Defaults to min. Change to full to see all pull request output.
per_page: GitHub paginates data in their API calls. Use this value to increase or decrease the number of pull requests gathered from GitHub, per page. If not set, GitHub defaults are used. Maximum is 100.

CLI Example:

salt myminion github.get_prs
salt myminion github.get_prs base=2016.11

saltext.github.modules.github.get_ruleset(profile='github', **kwargs)[source]¶

Get information of specific ruleset.

Deprecated since version 1.1.0: Use github_org.get_ruleset or github_repo.get_ruleset instead.

profile: The name of the profile configuration to use. Defaults to github.
ruleset_type: The type of ruleset. repo or org.
ruleset_id: Id of the ruleset.
owner: The account owner of the repository.
repo_name: The name of the repo.
org_name: The name of the organization.
header_dict: Headers to pass to Github API.

CLI Example:

salt myminion github.get_ruleset
salt myminion github.get_ruleset ruleset_id=1

saltext.github.modules.github.delete_ruleset(profile='github', **kwargs)[source]¶

Delete ruleset

Deprecated since version 1.1.0: Use github_org.delete_ruleset or github_repo.delete_ruleset instead.

profile: The name of the profile configuration to use. Defaults to github.
ruleset_type: The type of ruleset. repo or org.
owner: The account owner of the repository.
repo_name: The name of the repo.
ruleset_id: Id of the ruleset.
org_name: The name of the organization.
header_dict: Headers to pass to Github API.

CLI Example:

salt myminion github.delete_ruleset
salt myminion github.delete_ruleset ruleset_id=1

saltext.github.modules.github.update_ruleset(profile='github', **kwargs)[source]¶

Update ruleset

Deprecated since version 1.1.0: Use github_org.update_ruleset or github_repo.update_ruleset instead.

profile: The name of the profile configuration to use. Defaults to github.
ruleset_type: The type of ruleset. repo or org.
ruleset_id: Id of the ruleset.
owner: The account owner of the repository.
repo_name: The name of the repo.
org_name: The name of the organization.
header_dict: headers to pass to Github API.
ruleset_params: The updated ruleset definition.

CLI Example:

salt myminion github.update_ruleset
salt myminion github.update_ruleset ruleset_id=1

saltext.github.modules.github.add_ruleset(profile='github', **kwargs)[source]¶

Add ruleset

Deprecated since version 1.1.0: Use github_org.add_ruleset or github_repo.add_ruleset instead.

profile: The name of the profile configuration to use. Defaults to github.
ruleset_type: The type of ruleset. repo or org.
owner: The account owner of the repository.
repo_name: The name of the repo.
org_name: The name of the organization.
header_dict: headers to pass to Github API.
ruleset_params: The ruleset definition. Must contain at least name and enforcement.

CLI Example:

salt myminion github.add_ruleset

saltext.github.modules.github.list_rulesets(profile='github', *, per_page=None, **kwargs)[source]¶

List rulesets

Deprecated since version 1.1.0: Use github_org.list_rulesets or github_repo.list_rulesets instead.

profile: The name of the profile configuration to use. Defaults to github.
ruleset_type: The type of ruleset. repo or org.
owner: The account owner of the repository.
repo_name: The name of the repo.
org_name: The name of the organization.
header_dict: headers to pass to Github API.
per_page: number of returned results (max 100).

CLI Example:

salt myminion github.list_rulesets

github¶

Configuration¶

`github`¶