salt.modules.github module¶

Module for interacting with the GitHub v3 API.

New 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: only some functions, such as 'add_user',
  # require a dev_team_id.
  dev_team_id: 1234

salt.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

salt.modules.github.get_issue(issue_number, repo_name=None, profile='github', output='min')¶

Return information about a single issue in a named repository.

New in version Carbon.

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

salt.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.

New in version Carbon.

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

salt.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.

New in version Carbon.

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

salt.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.

New in version Carbon.

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

salt.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.

New in version Carbon.

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

salt.modules.github.get_repo_info(repo_name, profile='github')¶

Return information for a given repo.

New in version Carbon.

repo_name: The name of 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'

salt.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

salt.modules.github.list_private_repos(profile='github')¶

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

New in version Carbon.

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'

salt.modules.github.list_public_repos(profile='github')¶

List public repositories within the organization.

New in version Carbon.

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'

salt.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.

New in version Carbon.

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'

salt.modules.github.list_users(profile='github')¶

List all users within the organization.

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

CLI Example:

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

salt.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