November 27, 2020

GitHub Actions 101

Today I was feeling a bit lost (again, sigh) trying to understand GitHub Actions.

Specifically, the documentation did not appear to have an overview of how actions are composed and what they are composed of. What are those things that run? How are they named and referenced?

In retrospect, instead of the docs, I would recommend getting started by looking at the yaml for the Simple workflow. The button appears in the Actions tab on any new repo.

Screenshot of GitHub Actions tab on new repo, showing sample workflow

The button will open the workflow yaml in an editor (it won't be committed to your repo yet).

Screenshot of Simple workflow yaml code

Not so mysterious after all 😀

The first takeaway is that actions can be written using simple shell commands.

Commands run in a shell in VMs which come preinstalled with commonly used tools. There is no need to learn a new scripting language. You can even write your action as a shell script in a file, and invoke it from the workflow yaml.

If you want, you can package and re-use portions of a job in different workflows. These components are also called actions (that's where some of my initial confusion originated), but you don't need to learn to write those yourself in order to build your own workflows.

Don't be thrown off by the yaml

Each job is identified by its key e.g. simple-job in the example below.
The workflow syntax documentation denotes this as jobs.<job-id>.

on: push
jobs:
  simple-job:
    runs-on: ubuntu-latest
    env:
      HELLO: world
    steps:
    - run: 'echo Hello: $HELLO'
    - run: |
        echo node version: `node -v`
        pwd

steps: contains a list of commands, each described by a run:
(In the earlier example above, there is also an action, described with uses: instead of run:)

The 1st run: command above is quoted, to avoid ": " being interpreted as a yaml map.

The 2nd run: contains 2 commands in a multi-line (indented) block using "|". This syntax does not require quotes, making it convenient for embedded scripts.

If you push the workflow above to a new repo on GitHub, the result should look like this:

Screenshot of workflow run showing simple-job output

A few more things to know about yaml

You can test the validity of your yaml online.
Seeing the JSON representation will often clear up confusion.
Quotes around (scalar) strings are optional, BUT there are a lot of gotchas!
E.g. look out for strings with '- ' at the start, or ': ' or '#' in the middle, or ':' at the end, or strings that look like numbers or booleans.
Maps are usually written as key: value lines at the same indentation.
Lists are usually written as lines with - value.
Or use {key1: v1, key2: v2, ...} for maps, [v1, v2, ...] for lists.
Indentation must use spaces (no tabs).
For more about multi-line strings see https://yaml-multiline.info/.

Have fun playing with GitHub Actions
⛭

To leave a comment
please visit dev.to/jldec

debug

user: anonymous

{
  "path": "/blog/github-actions-101",
  "attrs": {
    "title": "GitHub Actions 101",
    "splash": {
      "image": "/images/snowy-boathouse.jpg"
    },
    "date": "2020-11-27",
    "layout": "BlogPostLayout",
    "excerpt": "Not so mysterious after all 😀"
  },
  "md": "# GitHub Actions 101\n\nToday I was feeling a bit lost (again, sigh) trying to understand GitHub Actions.\n\nSpecifically, the [documentation](https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions) did not appear to have an overview of how actions are composed and what they are composed of. What are those things that run? How are they named and referenced?\n\nIn retrospect, instead of the docs, I would recommend getting started by looking at the yaml for the [Simple workflow](https://github.com/actions/starter-workflows/blob/main/ci/blank.yml). The button appears in the __Actions__ tab on any new repo.\n\n![Screenshot of GitHub Actions tab on new repo, showing sample workflow](/images/actions-start-here.png)\n\nThe button will open the workflow yaml in an editor (it won't be committed to your repo yet).\n\n![Screenshot of Simple workflow yaml code](/images/simple-workflow.png)\n\n## Not so mysterious after all 😀\n\n> The first takeaway is that actions can be written using simple shell commands.\n\nCommands run in a shell in VMs which come preinstalled with [commonly used tools](https://github.com/actions/runner-images/blob/main/images/linux/Ubuntu2204-Readme.md). There is no need to learn a new scripting language. You can even write your action as a shell script in a file, and invoke it from the workflow yaml.\n\nIf you want, you can package and re-use portions of a job in different workflows. These components are also called [actions](https://docs.github.com/en/actions/creating-actions) (that's where some of my initial confusion originated), _but you don't need to learn to write those yourself in order to build your own workflows_.\n\n## Don't be thrown off by the yaml\n\nEach job is identified by its key e.g. `simple-job` in the example below.  \nThe [workflow syntax](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) documentation denotes this as `jobs.<job-id>`.\n```yaml\non: push\njobs:\n  simple-job:\n    runs-on: ubuntu-latest\n    env:\n      HELLO: world\n    steps:\n    - run: 'echo Hello: $HELLO'\n    - run: |\n        echo node version: `node -v`\n        pwd\n```\n\n`steps:` contains a list of commands, each described by a `run:`  \n(In the earlier example above, there is also an [action](https://docs.github.com/en/actions/creating-actions/about-custom-actions), described with `uses:` instead of `run:`)\n\nThe 1st run: command above is quoted, to avoid \": \" being interpreted as a yaml map.\n\nThe 2nd run: contains 2 commands in a multi-line (indented) block using \"|\". This syntax does not require quotes, making it convenient for embedded scripts.\n\nIf you push the workflow above to a new repo on GitHub, the result should look like this:\n\n![Screenshot of workflow run showing simple-job output](/images/action1.png)\n\n### A few more things to know about [yaml](https://en.wikipedia.org/wiki/YAML)\n\n- You can test the validity of your yaml [online](https://onlineyamltools.com/convert-yaml-to-json).  \n  Seeing the JSON representation will often clear up confusion.\n- Quotes around (scalar) strings are optional, BUT there are a lot of gotchas!  \n  E.g. look out for strings with '- ' at the start, or ': ' or '#' in the middle, or ':' at the end, or strings that look like numbers or booleans.\n- Maps are usually written as `key: value` lines at the same indentation.  \n  Lists are usually written as lines with `- value`.  \n  _Or_ use `{key1: v1, key2: v2, ...}` for maps, `[v1, v2, ...]` for lists.\n- Indentation must use spaces (no tabs).\n- For more about multi-line strings see https://yaml-multiline.info/.\n\n\n> Have fun playing with GitHub Actions  \n> ⛭\n\n_To leave a comment  \nplease visit [dev.to/jldec](https://dev.to/jldec/github-actions-101-pfn)_\n\n",
  "html": "<h1>GitHub Actions 101</h1>\n<p>Today I was feeling a bit lost (again, sigh) trying to understand GitHub Actions.</p>\n<p>Specifically, the <a href=\"https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions\">documentation</a> did not appear to have an overview of how actions are composed and what they are composed of. What are those things that run? How are they named and referenced?</p>\n<p>In retrospect, instead of the docs, I would recommend getting started by looking at the yaml for the <a href=\"https://github.com/actions/starter-workflows/blob/main/ci/blank.yml\">Simple workflow</a>. The button appears in the <strong>Actions</strong> tab on any new repo.</p>\n<p><img src=\"/images/actions-start-here.png\" alt=\"Screenshot of GitHub Actions tab on new repo, showing sample workflow\"></p>\n<p>The button will open the workflow yaml in an editor (it won't be committed to your repo yet).</p>\n<p><img src=\"/images/simple-workflow.png\" alt=\"Screenshot of Simple workflow yaml code\"></p>\n<h2>Not so mysterious after all 😀</h2>\n<blockquote>\n<p>The first takeaway is that actions can be written using simple shell commands.</p>\n</blockquote>\n<p>Commands run in a shell in VMs which come preinstalled with <a href=\"https://github.com/actions/runner-images/blob/main/images/linux/Ubuntu2204-Readme.md\">commonly used tools</a>. There is no need to learn a new scripting language. You can even write your action as a shell script in a file, and invoke it from the workflow yaml.</p>\n<p>If you want, you can package and re-use portions of a job in different workflows. These components are also called <a href=\"https://docs.github.com/en/actions/creating-actions\">actions</a> (that's where some of my initial confusion originated), <em>but you don't need to learn to write those yourself in order to build your own workflows</em>.</p>\n<h2>Don't be thrown off by the yaml</h2>\n<p>Each job is identified by its key e.g. <code>simple-job</code> in the example below.<br>\nThe <a href=\"https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions\">workflow syntax</a> documentation denotes this as <code>jobs.&lt;job-id&gt;</code>.</p>\n<pre><code class=\"language-yaml\">on: push\njobs:\n  simple-job:\n    runs-on: ubuntu-latest\n    env:\n      HELLO: world\n    steps:\n    - run: 'echo Hello: $HELLO'\n    - run: |\n        echo node version: `node -v`\n        pwd\n</code></pre>\n<p><code>steps:</code> contains a list of commands, each described by a <code>run:</code><br>\n(In the earlier example above, there is also an <a href=\"https://docs.github.com/en/actions/creating-actions/about-custom-actions\">action</a>, described with <code>uses:</code> instead of <code>run:</code>)</p>\n<p>The 1st run: command above is quoted, to avoid &quot;: &quot; being interpreted as a yaml map.</p>\n<p>The 2nd run: contains 2 commands in a multi-line (indented) block using &quot;|&quot;. This syntax does not require quotes, making it convenient for embedded scripts.</p>\n<p>If you push the workflow above to a new repo on GitHub, the result should look like this:</p>\n<p><img src=\"/images/action1.png\" alt=\"Screenshot of workflow run showing simple-job output\"></p>\n<h3>A few more things to know about <a href=\"https://en.wikipedia.org/wiki/YAML\">yaml</a></h3>\n<ul>\n<li>You can test the validity of your yaml <a href=\"https://onlineyamltools.com/convert-yaml-to-json\">online</a>.<br>\nSeeing the JSON representation will often clear up confusion.</li>\n<li>Quotes around (scalar) strings are optional, BUT there are a lot of gotchas!<br>\nE.g. look out for strings with '- ' at the start, or ': ' or '#' in the middle, or ':' at the end, or strings that look like numbers or booleans.</li>\n<li>Maps are usually written as <code>key: value</code> lines at the same indentation.<br>\nLists are usually written as lines with <code>- value</code>.<br>\n<em>Or</em> use <code>{key1: v1, key2: v2, ...}</code> for maps, <code>[v1, v2, ...]</code> for lists.</li>\n<li>Indentation must use spaces (no tabs).</li>\n<li>For more about multi-line strings see <a href=\"https://yaml-multiline.info/\">https://yaml-multiline.info/</a>.</li>\n</ul>\n<blockquote>\n<p>Have fun playing with GitHub Actions<br>\n⛭</p>\n</blockquote>\n<p><em>To leave a comment<br>\nplease visit <a href=\"https://dev.to/jldec/github-actions-101-pfn\">dev.to/jldec</a></em></p>\n"
}