Skip to content

Modules

json

json.from_json(text):any

Convert a JSON string into a Starlark value

Arguments
  • text: str
Returns
  • any
Examples
1
2
load("json", "from_json")
print(from_json('{"cat": "meow"}')["cat"])

json.to_json(value):str

Convert a Starlark value to a JSON string.

Arguments
  • value: any - Value to convert
Returns
  • str
Examples
1
2
load("json", "to_json")
print(to_json({"cat": "meow", "dog": "woof"}))

random

random.randint(max):int

Return a random integer x such that 0 <= x < max

Arguments
  • max: int
Returns
  • int

random.randseed(seed)

Seed the random number generator

Arguments
  • seed: int

text

text.match(pattern,text):list(str)

Matches a string against a pattern and returns all submatches.

Arguments
  • pattern: str
  • text: str
Returns
  • list(str)
Examples
1
2
load("text", "match")
print(match("m(eo)w", "meow")) # -> ["meow", "eo"]
See Also

text.replace_all(pattern,text,w):str

Arguments
  • pattern: str
  • text: str
  • w: func or string - If w is a func(str)->str, it determines the value for each replacesment. If w is a str, that is the replacement.
Returns
  • str
Examples
1
print(replace_all('[xz]', 'xyz', '_')) # -> _y_

1
print(replace_all('[xz]', 'xyz', x.upper())) # -> XyZ
See Also

text.shellsplit(text):list(str)

Splits a given string like a shell would.

Arguments
  • text: str
Returns
  • list(str)
Examples
1
2
load("text", "shellsplit")
print(shellsplit('say --who="cat and dog" -v')) # -> ["say", "--who=cat and dog", "-v"]
See Also

time

time.now():time

Returns the current time in UTC.

Returns
  • time - time as a struct with the following fields: unix, hour, minute, second, month, year, day, yearday, weekday, zone and zone_ofs.
Examples
1
2
load("time", "now")
print(now()) # "time"(day = 3, hour = 21, minute = 38, month = 2, second = 57, unix = 1549229937, weekday = 0, year = 2019, yearday = 34, zone = "UTC", zone_ofs = 0)

time.parse_time(text,layout):time

Parses time from a string

Arguments
  • text: str - Text to parse.
  • layout: str (default=2006-01-02T15:04:05Z07:00 (RFC3339)) - Time text layout.
Returns
  • time - time as a struct with the following fields: unix, hour, minute, second, month, year, day, yearday, weekday, zone and zone_ofs.
Examples
1
2
load("time", "now", "parse_time")
print(parse_time("1999-11-11T23:00:15Z")) # "time"(day = 11, hour = 23, minute = 0, month = 11, second = 15, unix = 942361215, weekday = 4, year = 1999, yearday = 315, zone = "UTC", zone_ofs = 0)
See Also

github

github.call(method,path,body,success_codes,accept,**kwargs):status,status_code,body,json,links

Perform an HTTP call to the GitHub API.

Arguments
  • method: str
  • path - Path relative to api root. Any path that contains a ?, '#', '.' or '..' or begins with either app, app/, apps/, installation/ or installations/ is forbidden. Any values in the string in the form of {...} are replaced by the values from kwargs, or if not present there from the evaluation context.
  • body: object - Body as a Starlark object. This will converted into JSON as the body of the request.
  • success_codes: list(int) (default=[200, 201]) - List of permissable HTTP status codes. If code received is different, an error is reported.
  • accept: str (default=None) - Accept header content.
  • **kwargs - Used for path interpolation.
Returns
  • status: str - Response status as text.
  • status_code: int
  • body: str
  • json- JSON data is parsable.
  • links- Link header as dict.
Required Permissions
  • github_call
Examples
1
2
3
4
5
print(github.call(
  method='POST',
  path='repos/{repo_owner}/{repo_name}/issues/{issue_number}/labels',
  body=['zumi', 'gizmo'],
)['json'])

Add labels to the issue in context.

github.check_get_run(run_id,repo_owner,repo_name,issue_number):dict

Get check run.

Arguments
  • run_id: int
  • repo_owner: str (default=from context) - Must be supplied as a keyword argument.
  • repo_name: str (default=from context) - Must be supplied as a keyword argument.
  • issue_number: int (default=from context) - Must be supplied as a keyword argument.
Returns
  • dict - Same as GitHub API.
Required Permissions
  • github_call(method=GET, path=repos/{repo_owner}/{repo_name}/check-runs/{run_id})
See Also

github.check_list_runs(sha,repo_owner,repo_name):dict

List check runs.

Arguments
  • sha: str (default=from context)
  • repo_owner: str (default=from context) - Must be supplied as a keyword argument.
  • repo_name: str (default=from context) - Must be supplied as a keyword argument.
Returns
  • dict - Same as GitHub API.
Required Permissions
  • github_call(method=GET, path=repos/{repo_owner}/{repo_name}/commits/{sha}/check-runs
See Also

github.compare_commits(base,head,repo_owner,repo_name):dict

Compare two commits.

Arguments
  • base: str
  • head: str
  • repo_owner: str (default=from context) - Must be supplied as a keyword argument.
  • repo_name: str (default=from context) - Must be supplied as a keyword argument.
Returns
  • dict - Same as GitHub API.
Required Permissions
  • github_call(method=GET, path=repos/{repo_owner}/{repo_name}/compare/%s...%s)
See Also

github.create_status(state,context,description,target_url,repo_owner,repo_name):dict

Create a commit status.

Arguments
  • state: str
  • context: str
  • description: str (default="")
  • target_url: str (default="")
  • repo_owner: str (default=from context) - Must be supplied as a keyword argument.
  • repo_name: str (default=from context) - Must be supplied as a keyword argument.
Returns
  • dict - Same as GitHub API.
Required Permissions
  • github_call(method=POST, path=repos/{repo_owner}/{repo_name}/statuses/{sha})
See Also

github.get_all_pages(path,success_codes,accept,**kwargs):status,status_code,body,json

Perform HTTP GET calls to the GitHub API, iterating over all pages.

Arguments
  • path - Path relative to api root. Any path that contains a ?, '#', '.' or '..' or begins with either app, app/, apps/, installation/ or installations/ is forbidden. Any values in the string in the form of {...} are replaced by the values from kwargs, or if not present there from the evaluation context.
  • success_codes: list(int) (default=[200, 201]) - List of permissable HTTP status codes. If code received is different, an error is reported.
  • accept: str (default=None) - Accept header content.
  • **kwargs - Used for path interpolation.
Returns
  • status: str - Last response status as text.
  • status_code: int - Last response status code as text.
  • body: str - Last response body.
  • json- List of all elements returned.
Required Permissions
  • github_call
Examples
1
2
3
print(github.get_all_pages(
  path='repos/{repo_owner}/{repo_name}/issues/{issue_number}/labels',
)['json'])

github.get_combined_status(sha,repo_owner,repo_name):dict

Get a commit combined status.

Arguments
  • sha: str (default=from context)
  • repo_owner: str (default=from context) - Must be supplied as a keyword argument.
  • repo_name: str (default=from context) - Must be supplied as a keyword argument.
Returns
  • dict - Same as GitHub API.
Required Permissions
  • github_call(method=GET, path=repos/{repo_owner}/{repo_name}/commits/{sha}/status)
See Also

github.issue_assign(*assignees,repo_owner,repo_name,issue_number):dict

Add assignees to an issue.

Arguments
  • *assignees: list(str)
  • repo_owner: str (default=from context) - Must be supplied as a keyword argument.
  • repo_name: str (default=from context) - Must be supplied as a keyword argument.
  • issue_number: int (default=from context) - Must be supplied as a keyword argument.
Returns
  • dict - Same as GitHub API.
Required Permissions
  • github_call(method=POST, path=repos/{repo_owner}/{repo_name}/issues/{issue_number}/assignees)
See Also

github.issue_check_assignee(user,repo_owner,repo_name):bool

Check if a user can be assigned to an issue.

Arguments
  • user: str
  • repo_owner: str (default=from context) - Must be supplied as a keyword argument.
  • repo_name: str (default=from context) - Must be supplied as a keyword argument.
Returns
  • bool
Required Permissions
  • github_call(method=GET, path=repos/{repo_owner}/{repo_name}/assignees/{user})
See Also

github.issue_create_comment(body,attach_context,repo_owner,repo_name,issue_number):dict

Creates a new issue comment.

Arguments
  • body: str
  • attach_context: bool (default=True) - If True, append evaluation context description at the end of body.
  • repo_owner: str (default=from context) - Must be supplied as a keyword argument.
  • repo_name: str (default=from context) - Must be supplied as a keyword argument.
  • issue_number: int (default=from context) - Must be supplied as a keyword argument.
Returns
  • dict - Same as GitHub API.
Required Permissions
  • github_call(method=POST, path=repos/{repo_owner}/{repo_name}/issues/{issue_number}/comments)
See Also

github.issue_create_comment_reaction(comment_id,content,repo_owner,repo_name):dict

Create a new issue comment reaction.

Arguments
  • comment_id: int
  • content: str - Reaction content.
  • repo_owner: str (default=from context) - Must be supplied as a keyword argument.
  • repo_name: str (default=from context) - Must be supplied as a keyword argument.
Returns
  • dict - Same as GitHub API.
Required Permissions
  • github_call(method=POST, path=repos/{repo_owner}/{repo_name}/issues/comments/{comment_id}/reactions)
See Also

github.issue_label(*labels,repo_owner,repo_name,issue_number):dict

Add a label to an issue.

Arguments
  • *labels: list(str)
  • repo_owner: str (default=from context) - Must be supplied as a keyword argument.
  • repo_name: str (default=from context) - Must be supplied as a keyword argument.
  • issue_number: int (default=from context) - Must be supplied as a keyword argument.
Returns
  • dict - Same as GitHub API.
Required Permissions
  • github_call(method=POST, path=repos/{repo_owner}/{repo_name}/issues/{issue_number}/labels)
Examples
1
print(github.issue_label('wip', 'pending')[0]['id'])
See Also

github.issue_list_comments(repo_owner,repo_name,issue_number):dict

List comments on an issue.

Arguments
  • repo_owner: str (default=from context) - Must be supplied as a keyword argument.
  • repo_name: str (default=from context) - Must be supplied as a keyword argument.
  • issue_number: int (default=from context) - Must be supplied as a keyword argument.
Returns
  • dict - Same as GitHub API.
Required Permissions
  • github_call(method=GET, path=repos/{repo_owner}/{repo_name}/issues/{issue_number}/comments)
See Also

github.issue_list_labels(repo_owner,repo_name,issue_number):dict

List labels on an issue.

Arguments
  • repo_owner: str (default=from context) - Must be supplied as a keyword argument.
  • repo_name: str (default=from context) - Must be supplied as a keyword argument.
  • issue_number: int (default=from context) - Must be supplied as a keyword argument.
Returns
  • dict - Same as GitHub API.
Required Permissions
  • github_call(method=GET, path=repos/{repo_owner}/{repo_name}/issues/{issue_number}/labels)
See Also

github.issue_list_labels_names():list(str)

List labels on an issue, returning only their names.

Returns
  • list(str) - List of label names.
Required Permissions
  • github_call(method=GET, path=repos/{repo_owner}/{repo_name}/issues/{issue_number}/labels)
See Also

github.issue_unassign(*assignees,repo_owner,repo_name,issue_number):dict

Remove assignees from an issue.

Arguments
  • *assignees: list(str)
  • repo_owner: str (default=from context) - Must be supplied as a keyword argument.
  • repo_name: str (default=from context) - Must be supplied as a keyword argument.
  • issue_number: int (default=from context) - Must be supplied as a keyword argument.
Returns
  • dict - Same as GitHub API.
Required Permissions
  • github_call(method=DELETE, path=repos/{repo_owner}/{repo_name}/issues/{issue_number}/assignees)
See Also

github.issue_unlabel(label,repo_owner,repo_name,issue_number):dict

Remove a single label from an issue.

Arguments
  • label: str
  • repo_owner: str (default=from context) - Must be supplied as a keyword argument.
  • repo_name: str (default=from context) - Must be supplied as a keyword argument.
  • issue_number: int (default=from context) - Must be supplied as a keyword argument.
Returns
  • dict - Same as GitHub API.
Required Permissions
  • github_call(method=DELETE, path=repos/{repo_owner}/{repo_name}/issues/{issue_number}/labels/{label})
See Also

github.pr_get_review(review_id,repo_owner,repo_name,issue_number):dict

Get a single PR review.

Arguments
  • review_id: int
  • repo_owner: str (default=from context) - Must be supplied as a keyword argument.
  • repo_name: str (default=from context) - Must be supplied as a keyword argument.
  • issue_number: int (default=from context) - Must be supplied as a keyword argument.
Returns
  • dict - Same as GitHub API.
Required Permissions
  • github_call(method=GET, path=repos/{repo_owner}/{repo_name}/pulls/{issue_number}/reviews/{review_id})
See Also

github.pr_get_review_comments(review_id,repo_owner,repo_name,issue_number):dict

List comments made in a specific review.

Arguments
  • review_id: int
  • repo_owner: str (default=from context) - Must be supplied as a keyword argument.
  • repo_name: str (default=from context) - Must be supplied as a keyword argument.
  • issue_number: int (default=from context) - Must be supplied as a keyword argument.
Returns
  • dict - Same as GitHub API.
Required Permissions
  • github_call(method=GET, path=repos/{repo_owner}/{repo_name}/pulls/{issue_number}/reviews/{review_id}/comments)
See Also

github.pr_list_files():list(dict),repo_owner,repo_name,issue_number

Lists files of a specific PR.

Returns
  • list(dict) - List of files along with ancellary data as returned from the GitHub API.
  • repo_owner: str - Must be supplied as a keyword argument.
  • repo_name: str - Must be supplied as a keyword argument.
  • issue_number: int - Must be supplied as a keyword argument.
Required Permissions
  • github_call(method=GET, path=repos/{repo_owner}/{repo_name}/pulls/{issue_number}/files)
See Also

github.pr_list_reviewers():list(str),repo_owner,repo_name,issue_number

Lists reviewers of a specific PR.

Returns
  • list(str) - List of reviewers, both teams and users. Teams are prepended with the repo name, for example cats/zumi.
  • repo_owner: str - Must be supplied as a keyword argument.
  • repo_name: str - Must be supplied as a keyword argument.
  • issue_number: int - Must be supplied as a keyword argument.
Required Permissions
  • github_call(method=GET, path=repos/{repo_owner}/{repo_name}/pulls/{issue_number}/requested_reviewers)
See Also

github.pr_list_reviews(repo_owner,repo_name,issue_number):list(dict)

List reviews for a single PR.

Arguments
  • repo_owner: str (default=from context) - Must be supplied as a keyword argument.
  • repo_name: str (default=from context) - Must be supplied as a keyword argument.
  • issue_number: int (default=from context) - Must be supplied as a keyword argument.
Returns
  • list(dict) - Same as GitHub API.
Required Permissions
  • github_call(method=GET, path=repos/{repo_owner}/{repo_name}/pulls/{issue_number}/reviews
See Also

github.pr_request_review(*reviewers,repo_owner,repo_name,issue_number):dict

Add a reviewer to a pull request.

Arguments
  • *reviewers: list(str)
  • repo_owner: str (default=from context) - Must be supplied as a keyword argument.
  • repo_name: str (default=from context) - Must be supplied as a keyword argument.
  • issue_number: int (default=from context) - Must be supplied as a keyword argument.
Returns
  • dict - Same as GitHub API.
Required Permissions
  • github_call(method=POST, path=repos/{repo_owner}/{repo_name}/pulls/{issue_number}/requested_reviewers)
See Also

github.pr_unrequest_review(*reviewers,repo_owner,repo_name,issue_number):dict

Remove a reviewer from a pull request.

Arguments
  • *reviewers: list(str)
  • repo_owner: str (default=from context) - Must be supplied as a keyword argument.
  • repo_name: str (default=from context) - Must be supplied as a keyword argument.
  • issue_number: int (default=from context) - Must be supplied as a keyword argument.
Returns
  • dict - Same as GitHub API.
Required Permissions
  • github_call(method=DELETE, path=repos/{repo_owner}/{repo_name}/pulls/{issue_number}/requested_reviewers)
See Also

github.repo_is_collaborator(user,repo_owner,repo_name):bool

Check if a user is a collaborator for a specific repo.

Arguments
  • user: str
  • repo_owner: str (default=from context) - Must be supplied as a keyword argument.
  • repo_name: str (default=from context) - Must be supplied as a keyword argument.
Returns
  • bool
Required Permissions
  • github_call(method=GET, path=repos/{repo_owner}/{repo_name}/collaborators/{user})
See Also

github.team_get_by_name(name):dict

Get team by name.

Arguments
  • name: str
Returns
  • dict - Same as GitHub API.
Required Permissions
  • github_call(method=GET, path=/orgs/{repo_owner}/teams/{name})
See Also

github.team_list_members(team_id):list(dict)

List members for a team.

Arguments
  • team_id: int
Returns
  • list(dict) - Same as GitHub API.
Required Permissions
  • github_call(method=GET, path=/teams/{team_id}/members)
See Also

handlers

handlers.check_run(func,enabled,**kwargs):handler

Register a check_run event handler. This is called when a check_run event is received.

Arguments
  • func: callable - Handler function to be fired.
  • enabled: bool (default=True) - If False, handler is not enabled and will not be fired unless enabled using the enable function.
  • **kwargs - These arguments are passed as an argument hconfig to the handler when fired.
Returns
  • handler

handlers.check_suite(func,enabled,**kwargs):handler

Register a check_suite event handler. This is called when a check_suite event is received.

Arguments
  • func: callable - Handler function to be fired.
  • enabled: bool (default=True) - If False, handler is not enabled and will not be fired unless enabled using the enable function.
  • **kwargs - These arguments are passed as an argument hconfig to the handler when fired.
Returns
  • handler

handlers.command(name,func,enabled,**kwargs):handler

Register a command handler.

Arguments
  • name: str (default=catch-all) - Command name to register. If omitted, all commands will fire this handler.
  • func: callable - Handler function to be fired.
  • enabled: bool (default=True) - If False, handler is not enabled and will not be fired unless enabled using the enable function.
  • **kwargs - These arguments are passed as an argument hconfig to the handler when fired.
Returns
  • handler
Examples
1
2
3
4
def meow():
  github.issue_create_comment("meow")

handlers.command(name='say', func=meow)
Discussion

The command handler is fired when a command is detected in an event. Events that are considered as command sources are a creations (not edits) of a pull request (PR body), issue comment, pull request review and pull request review comment. Such events can have multiple commands in the same event, such as multiple commands in a pull request comment.

handlers.done(func,enabled,**kwargs):handler

Register a module done handler.

Arguments
  • func: callable - Handler function to be fired.
  • enabled: bool (default=True) - If False, handler is not enabled and will not be fired unless enabled using the enable function.
  • **kwargs - These arguments are passed as an argument hconfig to the handler when fired.
Returns
  • handler
Discussion

This handler is fired before any other handler when the evaluation ends.

handlers.init(func,enabled,**kwargs):handler

Register a module init handler.

Arguments
  • func: callable - Handler function to be fired.
  • enabled: bool (default=True) - If False, handler is not enabled and will not be fired unless enabled using the enable function.
  • **kwargs - These arguments are passed as an argument hconfig to the handler when fired.
Returns
  • handler
Discussion

This handler is fired before any other handler when the evaluation begins.

handlers.issue_comment(func,enabled,**kwargs):handler

Register an issue comment event handler. This is called when an issue comment event is received.

Arguments
  • func: callable - Handler function to be fired.
  • enabled: bool (default=True) - If False, handler is not enabled and will not be fired unless enabled using the enable function.
  • **kwargs - These arguments are passed as an argument hconfig to the handler when fired.
Returns
  • handler

handlers.issues(func,enabled,**kwargs):handler

Register an issues event handler. This is called when an issues event is received.

Arguments
  • func: callable - Handler function to be fired.
  • enabled: bool (default=True) - If False, handler is not enabled and will not be fired unless enabled using the enable function.
  • **kwargs - These arguments are passed as an argument hconfig to the handler when fired.
Returns
  • handler

handlers.pull_request(func,enabled,**kwargs):handler

Register a pull request event handler. This is called when a pull request event is received.

Arguments
  • func: callable - Handler function to be fired.
  • enabled: bool (default=True) - If False, handler is not enabled and will not be fired unless enabled using the enable function.
  • **kwargs - These arguments are passed as an argument hconfig to the handler when fired.
Returns
  • handler

handlers.pull_request_review(func,enabled,**kwargs):handler

Register a pull request review event handler. This is called when a pull request review event is received.

Arguments
  • func: callable - Handler function to be fired.
  • enabled: bool (default=True) - If False, handler is not enabled and will not be fired unless enabled using the enable function.
  • **kwargs - These arguments are passed as an argument hconfig to the handler when fired.
Returns
  • handler

handlers.pull_request_review_comment(func,enabled,**kwargs):handler

Register a pull request review comment event handler. This is called when a pull request review comment event is received.

Arguments
  • func: callable - Handler function to be fired.
  • enabled: bool (default=True) - If False, handler is not enabled and will not be fired unless enabled using the enable function.
  • **kwargs - These arguments are passed as an argument hconfig to the handler when fired.
Returns
  • handler

handlers.push(func,enabled,**kwargs):handler

Register a push event handler. This is called when a push event is received.

Arguments
  • func: callable - Handler function to be fired.
  • enabled: bool (default=True) - If False, handler is not enabled and will not be fired unless enabled using the enable function.
  • **kwargs - These arguments are passed as an argument hconfig to the handler when fired.
Returns
  • handler

handlers.status(func,enabled,**kwargs):handler

Register a status event handler. This is called when a status event is received.

Arguments
  • func: callable - Handler function to be fired.
  • enabled: bool (default=True) - If False, handler is not enabled and will not be fired unless enabled using the enable function.
  • **kwargs - These arguments are passed as an argument hconfig to the handler when fired.
Returns
  • handler

handlers.timer_1h(func,enabled,**kwargs):handler

Register a 1h timer event handler.

Arguments
  • func: callable - Handler function to be fired.
  • enabled: bool (default=True) - If False, handler is not enabled and will not be fired unless enabled using the enable function.
  • **kwargs - These arguments are passed as an argument hconfig to the handler when fired.
Returns
  • handler