--- title: GitHub Actions details keywords: fastai sidebar: home_sidebar summary: "Functionality for helping to create GitHub Actions workflows in Python" description: "Functionality for helping to create GitHub Actions workflows in Python" nb_path: "01_actions.ipynb" ---
{% raw %}
{% endraw %} {% raw %}
{% endraw %}

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.

{% raw %}
{% endraw %} {% raw %}
{% endraw %}

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:

{% raw %}
{% endraw %} {% raw %} 
env_github.repository

'octocat/Hello-World'
{% endraw %} {% raw %}

user_repo[source]

user_repo()

List of user,repo from `env_github.repository

{% endraw %} {% raw %}
{% endraw %} {% raw %} 
user_repo()

['octocat', 'Hello-World']
{% endraw %}

The possible events are available in the Event enum.

{% raw %}
{% endraw %} {% raw %} 
', '.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'
{% endraw %} {% raw %}
{% endraw %} {% raw %}

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

{% endraw %} {% raw %}
{% endraw %} {% raw %}

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

{% endraw %} {% raw %}
{% endraw %}

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
{% raw %}

env_contexts[source]

env_contexts(contexts)

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

{% endraw %} {% raw %}
{% endraw %} {% raw %}
{% endraw %} {% raw %}

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

{% endraw %} {% raw %}
{% endraw %} {% raw %} 
create_workflow('test', Event.release)
{% endraw %}

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.

{% raw %}

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.

{% endraw %} {% raw %}
{% endraw %}

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.

{% raw %} 
L(context_github)

(#26) ['token','job','ref','sha','repository','repository_owner','repositoryUrl','run_id','run_number','retention_days'...]
{% endraw %} {% raw %} 
context_github.ref

'refs/heads/master'
{% endraw %}

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:

{% raw %} 
loads(nested_idx(context_needs, "prebuild", "outputs", "out"))

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

example_payload[source]

example_payload(event)

Get an example of a JSON payload for event

{% endraw %} {% raw %}
{% endraw %}

Workflow helper functions

{% raw %}

github_token[source]

github_token()

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

{% endraw %} {% raw %}
{% endraw %} {% raw %}

actions_output[source]

actions_output(name, value)

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

{% endraw %} {% raw %}
{% endraw %}

Details in the GitHub Documentation for set-output.

{% raw %}

actions_debug[source]

actions_debug(message)

Print the special ::debug line for message

{% endraw %} {% raw %}
{% endraw %}

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.

{% raw %}

actions_warn[source]

actions_warn(message, details='')

Print the special ::warning line for message

{% endraw %} {% raw %}
{% endraw %}

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.

{% raw %}

actions_error[source]

actions_error(message, details='')

Print the special ::error line for message

{% endraw %} {% raw %}
{% endraw %}

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.

{% raw %}

actions_group[source]

actions_group(title)

Print the special ::group line for title

{% endraw %} {% raw %}
{% endraw %} {% raw %}

actions_endgroup[source]

actions_endgroup()

Print the special ::endgroup

{% endraw %} {% raw %}
{% endraw %}

Details in the GitHub Documentation for grouping log lines.

{% raw %}

actions_mask[source]

actions_mask(value)

Print the special ::add-mask line for value

{% endraw %} {% raw %}
{% endraw %}

Details in the GitHub Documentation for add-mask.

{% raw %}

set_git_user[source]

set_git_user(api=None)

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

{% endraw %} {% raw %}
{% endraw %}

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