tutorial_actions.html

---

title: Getting started with GitHub Actions


keywords: fastai
sidebar: home_sidebar



nb_path: "80_tutorial_actions.ipynb"
---
<!--

#################################################
### THIS FILE WAS AUTOGENERATED! DO NOT EDIT! ###
#################################################
# file to edit: 80_tutorial_actions.ipynb
# command to build the docs after a change: nbdev_build_docs

-->

<div class="container" id="notebook-container">
        
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<h2 id="About-GitHub-Actions">About GitHub Actions<a class="anchor-link" href="#About-GitHub-Actions"> </a></h2>
</div>
</div>
</div>
<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p><a href="https://docs.github.com/en/free-pro-team@latest/actions">GitHub Actions</a> help you automate tasks within your software development life cycle. GitHub say that:</p>
<blockquote><p>"<em>GitHub Actions are event-driven, meaning that you can run a series of commands after a specified event has occurred. For example, every time someone creates a pull request for a repository, you can automatically run a command that executes a software testing script.</em>"</p>
</blockquote>
<p>They are a powerful system for automating many software development processes, and open source projects get unlimited compute hours for free! A sequence of steps in GitHub Actions are be combined together into a "workflow", which can furthermore contain multiple "jobs", which are run on multiple machines, with (if needed) multiple operating systems, in parallel. For more information, read GitHub's <a href="https://docs.github.com/en/free-pro-team@latest/actions/learn-github-actions/introduction-to-github-actions">Introduction to GitHub Actions</a>.
However, workflows can be difficult to create and debug, because:</p>
<ul>
<li>They run in a special environment which is difficult to replicate locally</li>
<li>Each time you make a change it takes quite a few minutes before your updated workflow is run and you can see the results</li>
<li>It is difficult to develop interatively and iteratively</li>
<li>The actions environment and contexts are complex and the documentation, whilst detailed, provides few real examples to work from</li>
<li>The main "language" for building workflows is a YAML-based language which is quite verbose, and doesn't allow you to leverage your knowledge of other programming languages</li>
<li>Building full-featured extensions requires using TypeScript, which is not a language that most developers are used to using for scripting, sysadmin, and continuous integration tasks.</li>
</ul>
<p>However, with <a href="/cli.html#ghapi"><code>ghapi</code></a> you can write your workflows in Python and shell, and can do nearly all your development on your local machine. We'll start by importing from the library, along with <code>fastcore</code>:</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="kn">from</span> <span class="nn">ghapi</span> <span class="kn">import</span> <span class="o">*</span>
<span class="kn">from</span> <span class="nn">fastcore.utils</span> <span class="kn">import</span> <span class="o">*</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<h2 id="Your-first-Python-based-workflow">Your first Python-based workflow<a class="anchor-link" href="#Your-first-Python-based-workflow"> </a></h2>
</div>
</div>
</div>
<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>We're going to help you get started by building a simple workflow which will add a comment to all new pull requests, saying "thank you" to the contributor.</p>
<p><a href="/core.html#GhApi"><code>GhApi</code></a> makes developing workflows easier, because your actual YAML file is created for you entirely automatically. To create the new workflow, run the <a href="/actions.html#create_workflow"><code>create_workflow</code></a> function, like so:</p>
<div class="highlight"><pre><span></span><span class="n">create_workflow</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">&#39;thankyou&#39;</span><span class="p">,</span> <span class="n">event</span><span class="o">=</span><span class="n">Event</span><span class="o">.</span><span class="n">pull_request</span><span class="p">)</span>
</pre></div>
<p>Now it's time to create our python script. You'll find it in <code>.github/scripts</code>, named based on your <a href="/actions.html#create_workflow"><code>create_workflow</code></a> parameters. The initial skeleton just contains import statements.</p>
<p>It will be much easier for us to iterate on our script if we have a sample <em>context</em> that the GitHub workflow runner will provide to us. We can get one by calling <a href="/actions.html#example_payload"><code>example_payload</code></a>:</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">example</span> <span class="o">=</span> <span class="n">example_payload</span><span class="p">(</span><span class="n">Event</span><span class="o">.</span><span class="n">pull_request</span><span class="p">)</span>
<span class="nb">list</span><span class="p">(</span><span class="n">example</span><span class="p">)</span>
</pre></div>

    </div>
</div>
</div>

<div class="output_wrapper">
<div class="output">

<div class="output_area">



<div class="output_text output_subarea output_execute_result">
<pre>[&#39;action&#39;, &#39;number&#39;, &#39;pull_request&#39;, &#39;repository&#39;, &#39;sender&#39;]</pre>
</div>

</div>

</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>For information about all the fields in a <em>payload</em>, use the GitHub <a href="https://docs.github.com/en/free-pro-team@latest/developers/webhooks-and-events/webhook-events-and-payloads#pull_request">webhook payload</a> documentation. For instance, the docs tell us that the "action" field can be:</p>
<blockquote><p>"<em>opened, edited, closed, assigned, unassigned, review_requested, review_request_removed, ready_for_review, labeled, unlabeled, synchronize, locked, unlocked, or reopened</em>"</p>
</blockquote>
<p>Let's see what it contains for our example payload:</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">example</span><span class="o">.</span><span class="n">action</span>
</pre></div>

    </div>
</div>
</div>

<div class="output_wrapper">
<div class="output">

<div class="output_area">



<div class="output_text output_subarea output_execute_result">
<pre>&#39;opened&#39;</pre>
</div>

</div>

</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>For our script, we should ensure that it's only run for the <code>opened</code> action. Next up, we need to find out how to add a comment to a pull request. First, we'll need to create our <a href="/core.html#GhApi"><code>GhApi</code></a> object. On your own PC, your GitHub token should be in the <code>GITHUB_TOKEN</code> environment variable, whereas when run in a workflow it will be part of the <code>github</code> context. The <a href="/actions.html#github_token"><code>github_token</code></a> function handles this for you automatically, so we can say:</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">api</span> <span class="o">=</span> <span class="n">GhApi</span><span class="p">(</span><span class="n">owner</span><span class="o">=</span><span class="s1">&#39;fastai&#39;</span><span class="p">,</span> <span class="n">repo</span><span class="o">=</span><span class="s1">&#39;ghapi-test&#39;</span><span class="p">,</span> <span class="n">token</span><span class="o">=</span><span class="n">github_token</span><span class="p">())</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>One way to find the correct operation to call is to search the <a href="https://ghapi.fast.ai/fullapi.html">full API reference</a>. Operations are generally named as <code>{verb}_{object}</code>, so search for <code>create_comment</code>. Alternatively, you can jump to the section that you expect to contain your required operation -- in this case, it's important to know that GitHub considers a "pull request" to be a special kind of "issue". After some looking through the page, we found this operation:</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">api</span><span class="o">.</span><span class="n">issues</span><span class="o">.</span><span class="n">create_comment</span>
</pre></div>

    </div>
</div>
</div>

<div class="output_wrapper">
<div class="output">

<div class="output_area">


<div class="output_markdown rendered_html output_subarea output_execute_result">
<p><a href="https://docs.github.com/rest/reference/issues#create-an-issue-comment">issues.create_comment</a>(issue_number, body): <em>Create an issue comment</em></p>

</div>

</div>

</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>The hyperlink provided will take you to the GitHub docs for this operation, so take a look at that now. We need to provide an <code>issue_number</code> and the <code>body</code> of the comment. We can look inside the payload to find the issue number we need to use:</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="s1">&#39;, &#39;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">example</span><span class="o">.</span><span class="n">pull_request</span><span class="p">)</span>
</pre></div>

    </div>
</div>
</div>

<div class="output_wrapper">
<div class="output">

<div class="output_area">



<div class="output_text output_subarea output_execute_result">
<pre>&#39;url, id, node_id, html_url, diff_url, patch_url, issue_url, number, state, locked, title, user, body, created_at, updated_at, closed_at, merged_at, merge_commit_sha, assignee, assignees, requested_reviewers, requested_teams, labels, milestone, commits_url, review_comments_url, review_comment_url, comments_url, statuses_url, head, base, _links, author_association, draft, merged, mergeable, rebaseable, mergeable_state, merged_by, comments, review_comments, maintainer_can_modify, commits, additions, deletions, changed_files&#39;</pre>
</div>

</div>

</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>Since the docs call the parameter <code>issue_number</code>, and there is a <code>number</code> field here, that's probably what we should use.</p>

</div>
</div>
</div>
<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>To test this out, we'll first create a PR or issue, and then create our comment:</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">com</span> <span class="o">=</span> <span class="n">api</span><span class="o">.</span><span class="n">issues</span><span class="o">.</span><span class="n">create_comment</span><span class="p">(</span><span class="n">issue_number</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">body</span><span class="o">=</span><span class="s1">&#39;Thank you for your *valuable* contribution&#39;</span><span class="p">)</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>We can view the comment by visiting its URL:</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">com</span><span class="o">.</span><span class="n">url</span>
</pre></div>

    </div>
</div>
</div>

<div class="output_wrapper">
<div class="output">

<div class="output_area">



<div class="output_text output_subarea output_execute_result">
<pre>&#39;https://api.github.com/repos/fastai/ghapi-test/issues/comments/737393228&#39;</pre>
</div>

</div>

</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>...and then delete it since we were just testing:</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">com</span> <span class="o">=</span> <span class="n">api</span><span class="o">.</span><span class="n">issues</span><span class="o">.</span><span class="n">delete_comment</span><span class="p">(</span><span class="n">com</span><span class="o">.</span><span class="n">id</span><span class="p">)</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>The payload will be available in the <a href="https://docs.github.com/en/free-pro-team@latest/actions/reference/context-and-expression-syntax-for-github-actions#github-context"><code>github</code> context</a>, which is provided automatically to you using the <code>context_github</code> variable. When running locally, an example github context will be used instead. (This example github context will not, in general, have the same payload as the event you're using, so use the <code>example payload</code> for that.)</p>
<p>The <a href="/event.html"><code>event</code></a> contains the actual payload:</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="nb">list</span><span class="p">(</span><span class="n">context_github</span><span class="o">.</span><span class="n">event</span><span class="p">)</span>
</pre></div>

    </div>
</div>
</div>

<div class="output_wrapper">
<div class="output">

<div class="output_area">



<div class="output_text output_subarea output_execute_result">
<pre>[&#39;inputs&#39;, &#39;organization&#39;, &#39;ref&#39;, &#39;repository&#39;, &#39;sender&#39;, &#39;workflow&#39;]</pre>
</div>

</div>

</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>When we called <a href="/actions.html#create_workflow"><code>create_workflow</code></a>, the workflow it created can also be triggered using <a href="https://github.blog/changelog/2020-07-06-github-actions-manual-triggers-with-workflow_dispatch/">workflow dispatch</a>, which is more convenient for testing. In this case, our payload will not have the same information, so we should write our function in a way that can handle workflow dispatch as well.</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">dispatch</span> <span class="o">=</span> <span class="n">example_payload</span><span class="p">(</span><span class="n">Event</span><span class="o">.</span><span class="n">workflow_dispatch</span><span class="p">)</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>We can check what type of trigger we're responding to, by checking the keys of our payload:</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="s1">&#39;workflow&#39;</span> <span class="ow">in</span> <span class="n">dispatch</span>
</pre></div>

    </div>
</div>
</div>

<div class="output_wrapper">
<div class="output">

<div class="output_area">



<div class="output_text output_subarea output_execute_result">
<pre>True</pre>
</div>

</div>

</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>In that case, we'll use a fixed issue number, instead of using the actual payload number.</p>
<p>We can now write our function.</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="k">def</span> <span class="nf">reply_thanks</span><span class="p">():</span>
    <span class="n">api</span> <span class="o">=</span> <span class="n">GhApi</span><span class="p">(</span><span class="n">owner</span><span class="o">=</span><span class="s1">&#39;fastai&#39;</span><span class="p">,</span> <span class="n">repo</span><span class="o">=</span><span class="s1">&#39;ghapi&#39;</span><span class="p">,</span> <span class="n">token</span><span class="o">=</span><span class="n">github_token</span><span class="p">())</span>
    <span class="n">payload</span> <span class="o">=</span> <span class="n">context_github</span><span class="o">.</span><span class="n">event</span>
    <span class="k">if</span> <span class="s1">&#39;workflow&#39;</span> <span class="ow">in</span> <span class="n">payload</span><span class="p">:</span> <span class="n">issue</span> <span class="o">=</span> <span class="mi">1</span>
    <span class="k">else</span><span class="p">:</span>
        <span class="k">if</span> <span class="n">payload</span><span class="o">.</span><span class="n">action</span> <span class="o">!=</span> <span class="s1">&#39;opened&#39;</span><span class="p">:</span> <span class="k">return</span>
        <span class="n">issue</span> <span class="o">=</span> <span class="n">payload</span><span class="o">.</span><span class="n">number</span>
    <span class="n">api</span><span class="o">.</span><span class="n">issues</span><span class="o">.</span><span class="n">create_comment</span><span class="p">(</span><span class="n">issue_number</span><span class="o">=</span><span class="n">issue</span><span class="p">,</span> <span class="n">body</span><span class="o">=</span><span class="s1">&#39;Thank you for your *valuable* contribution&#39;</span><span class="p">)</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>Finally, copy this to the script in <code>.github/scripts</code>, along with a line to run it (<code>reply_thanks()</code>), and commit it to GitHub.</p>
<p>You can now test the workflow by going to GitHub, clicking the "Actions" tab, then clicking the workflow you just created, and then clicking the "Run workflow" button.</p>
<p>Alternatively, you can run it using <a href="/core.html#GhApi"><code>GhApi</code></a>, which we'll do now:</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">wf</span> <span class="o">=</span> <span class="n">api</span><span class="o">.</span><span class="n">actions</span><span class="o">.</span><span class="n">get_workflow</span><span class="p">(</span><span class="s1">&#39;thankyou-pull_request.yml&#39;</span><span class="p">)</span>
<span class="n">api</span><span class="o">.</span><span class="n">actions</span><span class="o">.</span><span class="n">create_workflow_dispatch</span><span class="p">(</span><span class="n">wf</span><span class="o">.</span><span class="n">id</span><span class="p">,</span> <span class="n">ref</span><span class="o">=</span><span class="s1">&#39;master&#39;</span><span class="p">)</span>
</pre></div>

    </div>
</div>
</div>

<div class="output_wrapper">
<div class="output">

<div class="output_area">


<div class="output_markdown rendered_html output_subarea output_execute_result">

</div>

</div>

</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>To find out if the dispatch succeeded, go to the Actions tab on your repo and look for a yellow circle, which means it's running, or a green tick, which means it succeeded. If you get a red cross, it failed - you can click the item for details. You can also get the results of the latest run through the API (but be sure to wait at least 30 seconds for the workflow to kick off):</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">last_run</span> <span class="o">=</span> <span class="n">api</span><span class="o">.</span><span class="n">actions</span><span class="o">.</span><span class="n">list_workflow_runs</span><span class="p">(</span><span class="n">wf</span><span class="o">.</span><span class="n">id</span><span class="p">)</span><span class="o">.</span><span class="n">workflow_runs</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
<span class="n">last_run</span><span class="o">.</span><span class="n">conclusion</span>
</pre></div>

    </div>
</div>
</div>

<div class="output_wrapper">
<div class="output">

<div class="output_area">



<div class="output_text output_subarea output_execute_result">
<pre>&#39;success&#39;</pre>
</div>

</div>

</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>If it doesn't work, you can add <code>print(payload)</code> after the first line, and when GitHub runs your workflow you'll see the whole payload in your "Actions" panel.</p>
<p>Once it's working OK using the manual workflow dispatch, try creating a pull request.</p>

</div>
</div>
</div>
<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<h2 id="Advanced-multi-job-workflow">Advanced multi-job workflow<a class="anchor-link" href="#Advanced-multi-job-workflow"> </a></h2>
</div>
</div>
</div>
<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>Sometimes, you need to join more than one <em>job</em> in a workflow. This isn't common, but one example it's absolutely needed is if you want to build software or run tests on multiple platforms, and then have some step that runs before or after all of them. For instance, building and releasing software that needs to be built on each platform requires one job to create a release, and then a separate job to do the builds and add artifacts to the release, since GitHub Actions runs all your steps in a job in a single platform. Furthermore, we need to set up <a href="https://docs.github.com/en/free-pro-team@latest/actions/learn-github-actions/managing-complex-workflows#creating-dependent-jobs">dependencies between jobs</a> using <code>needs</code>. <a href="/cli.html#ghapi"><code>ghapi</code></a> provides helpers to set up multi-job workflows with depedencies for you, which we'll show an example of here.</p>
<p>In this tutorial we're going to show how we created <a href="https://github.com/fastai/hugo-mathjax">hugo-mathjax</a>. The workflow in this project patches <a href="https://gohugo.io/">Hugo</a> to add <a href="https://www.mathjax.org/">Mathjax</a> support, then builds Mac, Ubuntu, and Windows versions of the software, creating a release which includes each of those builds as artifacts. It does the following:</p>
<ul>
<li>On a Ubuntu runner:<ul>
<li>Find out what the latest release of Hugo is</li>
<li>It we haven't yet built a patched version of this release, create a new release</li>
<li>Output the release number for the next job to use</li>
</ul>
</li>
<li>On Mac, Ubuntu, and Windows runners all running in parallel:<ul>
<li>Get the release number output by the previous step</li>
<li>Download this release from the Hugo repo, and untar it</li>
<li>Patch, build, and tar this release</li>
<li>Add the tarred release as an artifact of the release created in the first job</li>
</ul>
</li>
</ul>
<p>First, we'll create the workflow and script files:</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">create_workflow</span><span class="p">(</span><span class="s1">&#39;create&#39;</span><span class="p">,</span> <span class="n">Event</span><span class="o">.</span><span class="n">schedule</span><span class="p">,</span> <span class="n">contexts</span><span class="o">=</span><span class="s1">&#39;needs&#39;</span><span class="p">,</span> <span class="n">opersys</span><span class="o">=</span><span class="s1">&#39;macos, ubuntu, windows&#39;</span><span class="p">,</span> <span class="n">prebuild</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>This has some pieces we haven't seen before, so let's take a look at them now.</p>
<p>The <code>prebuild</code> bool tells <a href="/cli.html#ghapi"><code>ghapi</code></a> to include a prebuild job (see <a href="/actions.html#create_workflow"><code>create_workflow</code></a> for the full workflow created). After you run the above, take a look at the YAML that was created, to see how it all works. We're going to need to modify the YAML, to add the <a href="https://docs.github.com/en/free-pro-team@latest/actions/reference/events-that-trigger-workflows#schedule">schedule</a> we want to run it on, using a <code>cron:</code> line. You can see the final YAML file <a href="https://github.com/fastai/hugo-mathjax/blob/master/.github/workflows/python.yml">here</a>.</p>
<p>The prebuild job calls a prebuild script using a Ubuntu runner. We'll create the prebuild script now.</p>
<p>The script needs to get the current Hugo release tag:</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">tag</span> <span class="o">=</span> <span class="n">GhApi</span><span class="p">()</span><span class="o">.</span><span class="n">repos</span><span class="o">.</span><span class="n">get_latest_release</span><span class="p">(</span><span class="s1">&#39;gohugoio&#39;</span><span class="p">,</span> <span class="n">repo</span><span class="o">=</span><span class="s1">&#39;hugo&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">name</span>
<span class="n">tag</span>
</pre></div>

    </div>
</div>
</div>

<div class="output_wrapper">
<div class="output">

<div class="output_area">



<div class="output_text output_subarea output_execute_result">
<pre>&#39;v0.79.0&#39;</pre>
</div>

</div>

</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>...and check whether we have released that patched version:</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">api</span> <span class="o">=</span> <span class="n">GhApi</span><span class="p">(</span><span class="n">owner</span><span class="o">=</span><span class="s1">&#39;fastai&#39;</span><span class="p">,</span> <span class="n">repo</span><span class="o">=</span><span class="s1">&#39;hugo-mathjax&#39;</span><span class="p">,</span> <span class="n">token</span><span class="o">=</span><span class="n">github_token</span><span class="p">())</span>
<span class="n">exists</span> <span class="o">=</span> <span class="kc">True</span>
<span class="k">try</span><span class="p">:</span> <span class="n">api</span><span class="o">.</span><span class="n">repos</span><span class="o">.</span><span class="n">get_release_by_tag</span><span class="p">(</span><span class="n">tag</span><span class="p">)</span>
<span class="k">except</span> <span class="n">HTTP404NotFoundError</span><span class="p">:</span> <span class="n">exists</span> <span class="o">=</span> <span class="kc">False</span>
<span class="n">exists</span>
</pre></div>

    </div>
</div>
</div>

<div class="output_wrapper">
<div class="output">

<div class="output_area">



<div class="output_text output_subarea output_execute_result">
<pre>True</pre>
</div>

</div>

</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>In the case that the release already exists, we'll want to just exit, otherwise we'll create a new release:</p>
<div class="highlight"><pre><span></span><span class="n">rel</span> <span class="o">=</span> <span class="n">api</span><span class="o">.</span><span class="n">repos</span><span class="o">.</span><span class="n">create_release</span><span class="p">(</span><span class="n">tag</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="n">tag</span><span class="p">)</span>
</pre></div>
<p>The <code>build</code> job will run in a separate runner, so we need to create an output telling it the tag of the release we've created. The <a href="/actions.html#actions_output"><code>actions_output</code></a> function does that, but print a special format that GitHub Actions uses:</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">actions_output</span><span class="p">(</span><span class="s1">&#39;tag&#39;</span><span class="p">,</span> <span class="n">tag</span><span class="p">)</span>
</pre></div>

    </div>
</div>
</div>

<div class="output_wrapper">
<div class="output">

<div class="output_area">

<div class="output_subarea output_stream output_stdout output_text">
<pre>::set-output name=tag::v0.79.0
</pre>
</div>
</div>

</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>You can see the completed prebuild script <a href="https://github.com/fastai/hugo-mathjax/blob/master/.github/scripts/prebuild.py">here</a>.</p>
<p>Now we can move on to creating the <code>build</code> script. First, we can get the outputs of the <code>prebuild</code> job as a <code>dict</code> by using <code>context_needs</code>, which contains information from any jobs in the <code>needs</code> section (which <a href="/cli.html#ghapi"><code>ghapi</code></a> will automatically set up for you if you enable <code>prebuild</code>):</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">out</span> <span class="o">=</span> <span class="n">loads</span><span class="p">(</span><span class="n">nested_idx</span><span class="p">(</span><span class="n">context_needs</span><span class="p">,</span> <span class="s1">&#39;prebuild&#39;</span><span class="p">,</span> <span class="s1">&#39;outputs&#39;</span><span class="p">,</span> <span class="s1">&#39;out&#39;</span><span class="p">))</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>To get the <code>tag</code> output of the job, we index into the <code>dict</code>:</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">tag</span> <span class="o">=</span> <span class="n">nested_idx</span><span class="p">(</span><span class="n">out</span><span class="p">,</span> <span class="s1">&#39;step1&#39;</span><span class="p">,</span> <span class="s1">&#39;outputs&#39;</span><span class="p">,</span> <span class="s1">&#39;tag&#39;</span><span class="p">)</span>
<span class="n">tag</span>
</pre></div>

    </div>
</div>
</div>

<div class="output_wrapper">
<div class="output">

<div class="output_area">



<div class="output_text output_subarea output_execute_result">
<pre>&#39;v0.79.0&#39;</pre>
</div>

</div>

</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>We get the release details using the same approach as before, then download, untar, patch, and build it. We won't discuss those steps here since they're not specific to <a href="/cli.html#ghapi"><code>ghapi</code></a>.</p>
<p>Once the software is built, we need to know the name of the created file, which depends on the operating system we're running on. We can use the following approach to check:</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">platform</span> <span class="o">=</span> <span class="nb">dict</span><span class="p">(</span><span class="n">linux</span><span class="o">=</span><span class="s1">&#39;linux&#39;</span><span class="p">,</span> <span class="n">linux2</span><span class="o">=</span><span class="s1">&#39;linux&#39;</span><span class="p">,</span> <span class="n">win32</span><span class="o">=</span><span class="s1">&#39;win&#39;</span><span class="p">,</span> <span class="n">darwin</span><span class="o">=</span><span class="s1">&#39;mac&#39;</span><span class="p">)[</span><span class="n">sys</span><span class="o">.</span><span class="n">platform</span><span class="p">]</span>
<span class="n">ext_nm</span> <span class="o">=</span> <span class="s1">&#39;hugo.exe&#39;</span> <span class="k">if</span> <span class="n">platform</span><span class="o">==</span><span class="s1">&#39;win&#39;</span> <span class="k">else</span> <span class="s1">&#39;hugo&#39;</span>
<span class="n">ext_nm</span>
</pre></div>

    </div>
</div>
</div>

<div class="output_wrapper">
<div class="output">

<div class="output_area">



<div class="output_text output_subarea output_execute_result">
<pre>&#39;hugo&#39;</pre>
</div>

</div>

</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>Finally, we can upload our file as an artifact:</p>
<div class="highlight"><pre><span></span><span class="n">api</span> <span class="o">=</span> <span class="n">GhApi</span><span class="p">(</span><span class="n">owner</span><span class="o">=</span><span class="s1">&#39;fastai&#39;</span><span class="p">,</span> <span class="n">repo</span><span class="o">=</span><span class="s1">&#39;hugo-mathjax&#39;</span><span class="p">,</span> <span class="n">token</span><span class="o">=</span><span class="n">github_token</span><span class="p">())</span>
<span class="n">rel</span> <span class="o">=</span> <span class="n">api</span><span class="o">.</span><span class="n">repos</span><span class="o">.</span><span class="n">get_release_by_tag</span><span class="p">(</span><span class="n">tag</span><span class="p">)</span>
<span class="n">api</span><span class="o">.</span><span class="n">upload_file</span><span class="p">(</span><span class="n">rel</span><span class="p">,</span> <span class="n">fn</span><span class="p">)</span>
</pre></div>
<p>You can see the complete script <a href="https://github.com/fastai/hugo-mathjax/blob/master/.github/scripts/build.py">here</a>.</p>
<p>We've now successfully built a workflow that automatically patches, builds, and releases a mixed C/Go project, across multiple platforms, in parallel!</p>

</div>
</div>
</div>
</div>