github

Module for interacting with the GitHub v3 API.

Added in version 2016.3.0.

depends:

PyGithub python module

Configuration

Configure this module by specifying the name of a configuration profile in the minion config, minion pillar, or master config. The module will use the ‘github’ key by default, if defined.

For example:

github:
  token: abc1234
  org_name: my_organization

  # optional: some functions require a repo_name, which
  # can be set in the config file, or passed in at the CLI.
  repo_name: my_repo

  # optional: it can be dangerous to change the privacy of a repository
  # in an automated way. set this to True to allow privacy modifications
  allow_repo_privacy_changes: False

saltext.github.modules.github.__virtual__()

Only load this module if PyGithub is installed on this minion.

saltext.github.modules.github.list_users(profile='github', ignore_cache=False)

List all users within the organization.

profile

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

ignore_cache

Bypasses the use of cached users.

Added in version 2016.11.0.

CLI Example:

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

saltext.github.modules.github.get_user(name, profile='github', user_details=False)

Get a GitHub user by name.

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.add_user(name, profile='github')

Add a GitHub user.

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')

Remove a Github user by name.

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')

Return information about a single issue in a named repository.

Added in version 2016.11.0.

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')

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

Added in version 2016.11.0.

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)

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

Added in version 2016.11.0.

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)

Return information about milestones for a given repository.

Added in version 2016.11.0.

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')

Return information about a single milestone in a named repository.

Added in version 2016.11.0.

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)

Return information for a given repo.

Added in version 2016.11.0.

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')

Return teams belonging to a repository.

Added in version 2017.7.0.

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')

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

Added in version 2016.11.0.

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')

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

Added in version 2016.11.0.

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')

List public repositories within the organization.

Added in version 2016.11.0.

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')

Create a new github repository.

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'

Added in version 2016.11.0.

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

Updates an existing Github repository.

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'

Added in version 2016.11.0.

saltext.github.modules.github.remove_repo(name, profile='github')

Remove a Github repository.

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'

Added in version 2016.11.0.

saltext.github.modules.github.get_team(name, profile='github')

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

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')

Create a new Github team within an organization.

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'

Added in version 2016.11.0.

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

Updates an existing Github team.

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'

Added in version 2016.11.0.

saltext.github.modules.github.remove_team(name, profile='github')

Remove a github team.

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'

Added in version 2016.11.0.

saltext.github.modules.github.list_team_repos(team_name, profile='github', ignore_cache=False)

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.

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'

Added in version 2016.11.0.

saltext.github.modules.github.add_team_repo(repo_name, team_name, profile='github', permission=None)

Adds a repository to a team with team_name.

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.

Added in version 2017.7.0.

CLI Example:

salt myminion github.add_team_repo 'my_repo' 'team_name'

Added in version 2016.11.0.

saltext.github.modules.github.remove_team_repo(repo_name, team_name, profile='github')

Removes a repository from a team with team_name.

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'

Added in version 2016.11.0.

saltext.github.modules.github.list_team_members(team_name, profile='github', ignore_cache=False)

Gets the names of team members in lower case.

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'

Added in version 2016.11.0.

saltext.github.modules.github.list_members_without_mfa(profile='github', ignore_cache=False)

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

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

Added in version 2016.11.0.

saltext.github.modules.github.is_team_member(name, team_name, profile='github')

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

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'

Added in version 2016.11.0.

saltext.github.modules.github.add_team_member(name, team_name, profile='github')

Adds a team member to a team with team_name.

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'

Added in version 2016.11.0.

saltext.github.modules.github.remove_team_member(name, team_name, profile='github')

Removes a team member from a team with team_name.

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'

Added in version 2016.11.0.

saltext.github.modules.github.list_teams(profile='github', ignore_cache=False)

Lists all teams with the organization.

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

Added in version 2016.11.0.

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)

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

Added in version 2017.7.0.

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)

Get information of specific ruleset.

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)

Delete ruleset

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)

Update ruleset

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

number of returned results (max 100).

CLI Example:

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

saltext.github.modules.github.add_ruleset(profile='github', **kwargs)

Add ruleset

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

number of returned results (max 100).

CLI Example:

salt myminion github.add_ruleset

saltext.github.modules.github.list_rulesets(profile='github', **kwargs)

List rulesets

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