GitHub Actions details

Functionality for helping to create GitHub Actions workflows in Python

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

 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

 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

 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/checkout@v1
- uses: actions/setup-python@v2
  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

 env_contexts (contexts)

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

create_workflow

 create_workflow (name:str, event:fastcore.basics.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

 gh_create_workflow (name:str, event:str, contexts:str='')

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

	Type	Default	Details
name	str		Name of the workflow file
event	str		Event to listen for
contexts	str		Space-delimited extra contexts to include in `env` in addition to github

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

 example_payload (event)

Get an example of a JSON payload for event

Workflow helper functions

github_token

 github_token ()

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

actions_output

 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

 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

 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

 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

 actions_group (title)

Context manager to print the special ::group/::endgroup lines for title

with actions_group('Adding numbers...'): print(1+1)

::group::Adding numbers...
2
::endgroup::

Details in the GitHub Documentation for grouping log lines.

actions_mask

 actions_mask (value)

Print the special ::add-mask line for value

Details in the GitHub Documentation for add-mask.

set_git_user

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