Workflow setup

In your GitHub Actions workflow, include the following in your run step:

env:
  CONTEXT_GITHUB: ${{ toJson(github) }}

This stores the full github context, which includes information such as the name of the current workflow being run, the GitHub access token, and so forth.

As well as the github context, you can do that same thing for any of the other GitHub Actions contexts, which are:

github env job steps runner secrets strategy matrix needs

For instance, for the needs context, information about previous jobs specified in your needs clause, add this underneath your CONTEXT_GITHUB line:

CONTEXT_NEEDS: ${{ toJson(needs) }}

Note that here's no harm having entries that are not used -- GitHub Actions will set them to an empty dictionary by default.

GitHub also adds a number of GITHUB_* environment variables to all runners. These are available through the env_github AttrDict, with the GITHUB_ prefix removed, and remainder converted to lowercase. For instance:

env_github.repository

'octocat/Hello-World'

user_repo[source]

user_repo()

List of user,repo from `env_github.repository

user_repo()

['octocat', 'Hello-World']

The possible events are available in the Event enum.

', '.join(Event)

'page_build, content_reference, repository_import, create, workflow_run, delete, organization, sponsorship, project_column, push, context, milestone, project_card, project, package, pull_request, repository_dispatch, team_add, workflow_dispatch, member, meta, code_scanning_alert, public, needs, check_run, security_advisory, pull_request_review_comment, org_block, commit_comment, watch, marketplace_purchase, star, installation_repositories, check_suite, github_app_authorization, team, status, repository_vulnerability_alert, pull_request_review, label, installation, release, issues, repository, gollum, membership, deployment, deploy_key, issue_comment, ping, deployment_status, fork, schedule'

create_workflow_files[source]

create_workflow_files(fname:str, workflow:str, build_script:str, prebuild:bool=False)

Create workflow and script files in suitable places in github folder

fill_workflow_templates[source]

fill_workflow_templates(name:str, event, run, context, script, opersys='ubuntu', prebuild=False)

Function to create a simple Ubuntu workflow that calls a Python ghapi script

event is the event to trigger on. run is the shell lines to run before running the script, such as a pip install step. context are the env var context lines to include in the env: section of the workflow, normally created with env_contexts. opersys can be a string containing a comma-separated list of operating systems, e.g. macos, ubuntu, windows, which will be used to create a parallel matrix build.

The prebuild bool tells ghapi to include a prebuild job, which contains the following workflow:

runs-on: ubuntu-latest
outputs:
  out: ${{ toJson(steps) }}
steps:
- uses: actions/[email protected]
- uses: actions/[email protected]
  with: {python-version: '3.8'}
- name: Create release
  id: step1
  env:
    CONTEXT_GITHUB: ${{ toJson(github) }}
  run: |
    pip install -q ghapi
    python .github/scripts/prebuild.py

env_contexts[source]

env_contexts(contexts)

Create a suitable env: line for a workflow to make a context available in the environment

create_workflow[source]

create_workflow(name:str, event:Event, contexts:list=None, opersys='ubuntu', prebuild=False)

Function to create a simple Ubuntu workflow that calls a Python ghapi script

create_workflow('test', Event.release)

To create a basic ghapi workflow, call create_workflow, passing in the event that you wish to respond to, and a name for your workflow.

gh_create_workflow[source]

gh_create_workflow(name:"Name of the workflow file", event:"Event to listen for", contexts:"Space-delimited extra contexts to include in env in addition to 'github'"='')

Supports gh-create-workflow, a CLI wrapper for create_workflow.

Accessing contexts from Python

The information from these variables are provided by context_github, context_needs, and so forth for each named context. These variables are AttrDict objects.

L(context_github)

(#26) ['token','job','ref','sha','repository','repository_owner','repositoryUrl','run_id','run_number','retention_days'...]

context_github.ref

'refs/heads/master'

If you use our recommended workflow template, you will have this included in your prebuild step (if you have any):

outputs:
  out: ${{ toJson(steps) }}

You can access this content as a dictionary like so:

loads(nested_idx(context_needs, "prebuild", "outputs", "out"))

{'step1': {'outputs': {'tag': 'v0.79.0'},
  'outcome': 'success',
  'conclusion': 'success'}}

example_payload[source]

example_payload(event)

Get an example of a JSON payload for event

Workflow helper functions

github_token[source]

github_token()

Get GitHub token from GITHUB_TOKEN env var if available, or from github context

actions_output[source]

actions_output(name, value)

Print the special GitHub Actions ::set-output line for name::value

Details in the GitHub Documentation for set-output.

actions_debug[source]

actions_debug(message)

Print the special ::debug line for message

Details in the GitHub Documentation for debug. Note that you must create a secret named ACTIONS_STEP_DEBUG with the value true to see the debug messages set by this command in the log.

actions_warn[source]

actions_warn(message, details='')

Print the special ::warning line for message

Details in the GitHub Documentation for warning. For the optional details, you can provide comma-delimited file, line, and column information, e.g.: file=app.js,line=1,col=5.

actions_error[source]

actions_error(message, details='')

Print the special ::error line for message

Details in the GitHub Documentation for error. For the optional details, you can provide comma-delimited file, line, and column information, e.g.: file=app.js,line=1,col=5.

actions_group[source]

actions_group(title)

Print the special ::group line for title

actions_endgroup[source]

actions_endgroup()

Print the special ::endgroup

Details in the GitHub Documentation for grouping log lines.

actions_mask[source]

actions_mask(value)

Print the special ::add-mask line for value

Details in the GitHub Documentation for add-mask.

set_git_user[source]

set_git_user(api=None)

Set git user name/email to authenticated user (if api) or GitHub Actions bot (otherwise)

When pushing to git from a workflow, you'll need to set your username and email address. You can set them to the GhApi authenticated user's details by passing api. Otherwise, github-actions[bot] and github-actions[bot]@users.noreply.github.com will be used, which will make a push appear to be from "GitHub Actions".