Lets try to get a feel for how easy it is to create a new workflow.

In this issue:

• See the web interface's built-in support for workflow files
• Explore the pre-defined workflows
• Browse the available actions in the marketplace
• Create a new workflow
• Trigger a workflow manually

• 👉 Go back to the Actions tab and hit the New worlflow button 👈
• 👉 Browse around - locate the "Java with Maven" CI workflow - hit Configure to see the details 👈

Java with Maven

...Yup! It's pretty basic. It doesn't really do any integration, so calling it CI is probably a bit overreached, but it does give you a basic skeleton.

But we don't have any Java in this repo, so let's do something else instead. Notice that when you are in a yaml file, which is located in .github/worflows and you are in edit mode in GitHub's web interface, then a right panel shows up automatically, which allows you to search the marketplace for more actions.

• 👉 Look up the action called "Issue-metrics" by GitHub 👈
• 👉 Choose it and view it's full marketplace listing 👈
  

If you browse to the "Getting Started" section you'll see that they actually also suggest something of a template.

I've made an even simpler version of it

• 👉 Copy the code below and paste it into a new .yml file and save it in .github/worflows 👈
• 👉 add, commit and push to git 👈
• 👉 Go the the Actions tab and see what happens? 👈

name: Manually triggered issue metrics
on:
workflow_dispatch:

permissions:
issues: write
pull-requests: read

jobs:
build:
name: issue metrics
runs-on: ubuntu-latest
steps:
- name: Run issue-metrics tool
uses: github/issue-metrics@v2
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
SEARCH_QUERY: 'repo:${{ github.repository }} is:issue'

- name: Create issue
uses: peter-evans/create-issue-from-file@v4
with:
title: Monthly issue metrics report
token: ${{ secrets.GITHUB_TOKEN }}
content-filepath: ./issue_metrics.md

A few things worth noticing:

• The trigger on doesn't seem to mention an event?
• The env clause is used inside a step - not globally
• There and odd looking peter-evans/create-issue-from-file action in the equation 😱 What is that?
• This action seems to use the GitHub token in another way than we've seen before?

So it appears that nothin happens. On the Actions tab you don't see a new workflow run - but if you look closer, under "Workflows" you'll see that the new workflow is listed. If you select it you you'll see a notification the since this workflow defines a workflow_dispatch trigger, apparently you can then run it manually. In fact, since it's the only tigger defined, it's the only thing you can do with it!

• 👉 Run the workflow manually - locate the new issue created from from the run, read the report👈

If you haven't already:

• 👉 Try to add a few comments to some of your own issues, close the ones you're done with 👈
• 👉 Run the workflow again - read the new report👈

Congratulations

You successfully setup your copy from the template - and you are ready to work the issues. A a few things has already happened automatically in the background. Let's take a deeper look

Ultra shot on semantics in these issues: Each issue starts by listing the overall agenda as a table of content. The outcomes or learning goals of this issue. When you see:

• 👉 A task in Pointed text in bold like this 👈

It means that you should do what the task implies and mark it as done. When you've checked all tasks you close the issue and head on to the next.

In this issue:

• Browse the repo content in the GitHub web based editor (≈VS Code)
• Turn on sync of settings on your user profile.
• Introduce a tool to support an arbitrary new standard way-of-working
• Add the extension that supports this new standard and make it a recommendation for other repo co-users
• add, commit and push to git from the GitHub web based editor

Note:
Remember, these issues are yours. It's recommended that while you work the issues in this tutorial, you make it a habit to make notes-to-self in the comments to the issues. Leave a learning trail to your own future self. Or engage with others; come join the community discussions on this tutorial.

GitHub provides a lightweight version of VS Code for free for all GitHub users They call it the GitHub web based editor. It's hosted on github.dev as opposed to github.com

If you visit it directly github.dev you'll see an ultra short description on how to use this feature.

Either

• 👉 Replace .com with .dev in your URL 👈 or
• 👉 use the keyboard shortcut . 👈 ...while browsing a file.

The GitHub web based editor is actually a real VC Code IDE. You can even turn on the sync settings

• 👉 Turn on sync (everything) - sign in with your GitHub account and authorize 👈

Details...

Som extensions are not Web Editor compatible, they are designed to work in a CodeSpace. We'll go there next, but first, try to install an extension that is actually Web Editor Compatible:

• 👉 Search for and install GitHub Issue Notebooks 👈

The plugin is a Jupyter-like Notebook that enables you to generate all kinds of reports-as-code which will be stored as files .github-issues in the repo and shared among all team-members - and version controlled! Nice!

• 👉 Create a GitHub Issue Notebooks file in the root of the repo. Give it a spin, add add, commit and push it. 👈

Now that we've added a .github-issues file in our project. This is probably going to be included in our standard way of working. So let's add that particular extension as a recommendation to our teammates and repo co-users. Such recommendations are captured in a /.vscode/extensions.json file.

• 👉 Add the GitHub Issue Notebooks extension to the Workspace Recomendations. 👈
• 👉 add, commit and pushthe /.vscode/extensions.json file . 👈

GitHub actions

GitHub actions are an almost endless source of features that will allow you to trigger on any kind of event that happens on GitHub. The trigger is executed in a container injected with your source code. GitHub actions are extensions which are effectively repos on GitHub. You can then use them from the workflow (.yml file).

Some actions are officially published but you and your team can just create your own actions and store them on GitHub and use then directly from there - no official release is required for it to be available.

The actions that trigger are defined in a workflow file - and since the runtime environment for the execution is a linux based container you can literally run anything that you can script - either embedded in the workflow file or in a separate script you call from the the workflow.

The runtime environment in which the action is triggered is default pre-authenticated (you can turn it off) so it can access the GitHub eco-system with the same credentials as yourself.

GitHub has a full fledged API that allows you to do access all GitHub features. But it's tedious and verbose to use an API like that from a shell script. So in January 2020 GitHub released the first version of the GitHub CLI gh. Although it it doesn't (yet) cover all features it's amazingly comprehensive. It gives you command line access to 'all' GitHub features - from the terminal. Which means that your actions can do anything.

In this issue:

• Understand the workflow yaml file; on, env, permissions, jobs, usesand run.
• See the gh CLI in action
• Use the GitHub REST API for additional stuff gh doesn't support (yet)
• Log messages to the action execution using different log levels
• Use the GitHub web interface to create new workflows from 100's of predefined templates

Let's examine the workflow that was triggered on repo-creation - when you pushed "Use this template".

Here's the context:

• 👉 Go to the ▶️ Actions panel and open the workflow that just ran on "Initial commit" 👈

You will see something similar to this. Each section is expandable/collapsable and gives you exact details on what happened during the workflow execution.

• 👉 Open the worflow file that ran this particular workflow" 👈

In the left panel you'll find a read-only reference to the workflow file, in the version as it looked in the actual commit that triggered the workflow.

• 👉 Find the original workflow file in the git repo at /.github/worflows/template.yml and open that in the web editor 👈

You'll see the same file, but in the editable version from masterbranch. Since you are now in a genuine VS Code IDE you'll the IntelliSense support you expect.

As an example, if you hover on: you'll get instant access to a tool-tip box on this particular keyword. Apparently VS Code has built in support for GitHub Actions Workflow files.

• 👉 Hover over the keywords in the worflow file and see how much you'll learn about GitHub Actions 👈

A rundown on what goes on in this particular workflow:

In the reminder of this particular issue I'll not throw exercises at you, but rater walk you through some of the finer details in this flow. If you are already familiar with the semantics of the workflow files you may skip it - and then again; It does take you through some special cases, that serves to clarify the point, that a lot can be done with small means, by standing on the shoulders of other's general abstractions: Fight software complexity with more software!

Workflow: /.github/worflows/template.yml

name: Initial commit workflow

on:
push:
branches:
- '**' 

name is optional, it serves as a heading in the workflow execution. on- defines what should trigger this workflow. Since there is not an actual event for creating a new repo the hack is to use '**' this will make the trigger fire on any branch.

env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

env is the section that defines environment variables. Setting GITHUB_TOKEN is the standard way of authenticating the GitHub CLI. GitHub actions support secrets and GitHub automatically generate the a token when strating a workflow, it's stored in the secrets so this becomes that standard way of using the automatic token authentications

permissions:
checks: write
actions: write
contents: write
issues: write

permissions is used to change the permission if you need anything other than the default permissions. For this particular run I had to add explicit write permissions to actions (as you'll see later I'll disable this flow as soon as it has run once) and issues so the workflow can create new issues.

jobs:
cpissues:
name: "Initial commit only"
runs-on: ubuntu-latest

jobs is where the action happens - the section defines all the jobs that the workflow knows of. Each job has it's on tag (you define the name yourself) in this case I only have one job and I came up with the clever name cpissues.

runs-on specifies the runner and image that this workflow will run in. I only need to do small bits in the terminal, so I'm happy with the default latest Ubuntu But even though runs-on is just a small clause it has a huge impact and by defining your own runners and images you can open up a complete customized world to Platform Engineering and Internal Development Platforms where you can configure the actions to support anything as code - quite literally "anything"! I will point you to a an example of using a customized docker container in a bit, but the finder details of the world that opens up underneath runs-on is beyond the scope of this tutorial. So go and explore yourself.

if: ${{ contains(github.event.head_commit.message, 'Initial commit') }}
steps: 
- name: "Checkout"
uses: actions/checkout@v3

steps defined the different steps executed in this workflow. Each that becomes an expandable/collabsable setting in the job execution log you saw earlier, so this is how tiy add abit of readbility to your workflows. The rest of the this workflow happens in the context of these steps but before the workflow continues and if statement is used to fix the inconvenient fact that there is not dedicated event that fires on repository creation only that this workflow then fires on everything; The steps are simply ignored, unless the commit message of the commit spells exactly 'Initial commit'. Because this is exactly the commit message the GitHub always uses when it creates new repos off of templates.

uses i referring to actions so -apparently - the workflow somehow has access to to a GitHub Action called actions/checkout which is executed with no additional parameters in version 3.

As hinted earlier the access is simply that this is a Github repo called checkout under the GitHub user or organisations with handle actions. Consequently there should be somthing of interest at:

https://github.com/actions/checkout

There is! The user actions is controlled by GitHub self, so you know that if an action is located here it's considered GitHub standard. Almost every workflow will call this particular action as the first - It makes sure, that the rest of the workflow execution has access to the content of the repo.

- name: "Raise semaphore or quit"
run: |
... 

...
if $(gh workflow disable template.yml); then
echo ::notice title=Workflow successfully disabled::This also works as a raised semaphore - parallel workflow runs will see it and cancel
else
echo "::warning title=Another job got here first::This room is crowded - I'm outta here!"
curl -X POST \
-H "Accept: application/vnd.github.v3+json" \
-H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \
https://api.github.com/repos/${{ github.repository }}/actions/runs/${{ github.run_id }}/cancel
exit 1
fi

run is similar to uses but where uses calls a predefined action, run executes native shell commands. Starting the run clause with a pipe | followed by a new-line is a notation used to make the rest of the clause - a shell script.

The first thing that happens is that the workflow template.ymlis disabled. The is done simply by using the gh cli The command will raise an error if it doesn't succeed - like if it's already disabled.

The next line demonstrate how to use simple echo statements to create messages in the workflow execution log four levels are supported: debug, notice, warning and error. You already saw the output from this earlier, when you browsed the content on the ▶️ Actions panel.

The else clause runs if we didn't succeed to disable the workflow - as the message states, another job got here first. This is a precaution that deals with the occasional abnormality that sometimes GitHub fires the workflow twice on the same catch-all '**' branch pattern. When that is the case, I'd rather have this workflow cancelled, that having the record of a failed workflow. But cancelling a running instance of a workflow is is not supported from the gh CLI. It is hover supported by a webhook on the GitHub REST API.

Consequently this worflow now works as intended: It runs once - and only once, and only on the initial commit. And it doesn't take up any polling resources after, because it's effectively disabled.

- name: "Copying issues over"
run: .github/template/cpissues.sh

run executes the script I provided in this repo at /.github/template/cpissues.sh In large; It starts by reading settings from a local gitconfig file (lines #3-7) and it then uses gh to generate a json output of all issues in the source repo that has the designated label template (line #18). It then iterates over this json and uses an unholy mix of jq, base64 and sed - which are all standard linux commands - to capture the title of the issue (lines #22-26) and then, checks if an issue with the same title doesn't already exit (line #28) if not it pipes the issue body into a temporary file and uses a special flag on on the gh cli to create an issue from the file (lines #30-35)

- name: "Set the README"
run: |
cp .github/template/README.md .
git config --global user.email "[email protected]"
git config --global user.name "The GitHub Action Bot"
git add .
git commit -m "Updated the README"
git push origin

This bit uses run to replace the README.md in the root with the one that's designed, to be shown in the copy. This needs to be committed and pushed, and in order to do that we need to verify to git who we are by name and email.

This creates a new commit - If you go and take a look, your repo already has two commits, but also notice that you only have one job execution - despite that the workflow subscribes to any branch '**'; the disablement of the job works as intended.

After a bit of trial and beta back and forth GitHub CodeSpaces are now available for free to all GitHub users. CodeSpaces are essentially next step from the web based VS Code editor we've already explored. The addition is that we now also have access to an actual linux terminal.

In this issue:

• Start a Code Space
• Work from there as if it was your own PC - but in a shared setup
• Open a new development branch on an issue - from the command line
• Tweak the CodeSpace to your team's standards by adding a .devcontainer configuration

You can see you current CodeSpaces from https://github.com/codespaces This follows the well known GitHub standard, that you access personal information from global URLs - when you are logged in:

https://github.com/issues
https://github.com/settings
https://github.com/notifications
https://github.com/codespaces

Create a new CodeSpace on this repo

• 👉 You go to Code panel, hit the Code button, Select the CodeSpace tab and then create a CodeSpace 👈

When the CodeSpace is done building you'll see a full fledged IDE environment - it look like the one we explored earlier in the web based editor, only this time you have a genuine linux terminal in the bottom - as if your were on your own machine.

• 👉 run a few familiar commands; ls, gh, env, cat R<TAB>, git log, az and docker run hello-world 👈

It feels like home eh? Even tab-completion, git, docker, gh is pre-installed. Well the Azure CLI az wasn't installed, but everything else was there.

Let's imagine that we're a development team who agrees that:

👮‍♀️ You must only make changes that are related to an issue.
👮‍♀️ Each issue must have its own dedicated development branch.
👮‍♀️ Work can only be added to the master branch through pull-requests.

If these are rules we should make it easy to follow them.

Now consider, that this issue you're looking at now - #4 instructs you to configure the CodeSpace in a way that ensures that.

• The az CLI must be pre-installed
• The GitLens VS Code extension by Kraken must be installed
• A .gitconfig file must be added in the root of the repo, and it must become active

Let's do all this! it's easy!

• 👉 In the CodeSpace go to the terminal and run the command listed below: 👈

gh issue develop 4 --checkout

• 👉 In the command palette find the command that will Add Dev Container configuration 👈
• 👉 In the list find and install the Azure CLI 👈
• 👉 In the extension list find and add GitLens, Copilot and Copilot Chat to the Dev Container configuration 👈
• 👉 Add the line listed below as the second-to-last line in the configuration - just before the last closing bracket } ⚠️ remember to add a comma , after the closing bracket above 👈

"postCreateCommand": "git config --local --get include.path | grep -e ../.gitconfig || git config --local --add include.path ../.gitconfig"

...and finally

• 👉 Add a new file .gitconfig in the root of the repo and let it contain the following: 👈

[core]
editor = nano

[push]
default = current

[alias]
undo-commit = reset --soft HEAD^
addremove = add -A
recommit = commit -C HEAD --amend
co = checkout
st = status
root = rev-parse --show-toplevel
tree = log --graph --full-history --all --color --date=short --pretty=format:\"%Cred%x09%h %Creset%ad%Cblue%d %Creset %s %C(bold)(%an)%Creset\"
backward = checkout HEAD^1
forward = !git checkout $(git log --all --ancestry-path ^HEAD --format=format:%H | tail -n 1)

You may want to test the new Dev Container configuration before you commit it?

• 👉 In the command palette find the command that will Rebuild Dev Container configuration 👈
• 👉 Perform some tests - a few ones are suggested below 👈

From the terminal test the following commands

git config --list --show-origin
git tree
az

Open the workflow .yml you created earlier and see that is gives you info about who committed it

Open the .gitconfig file you created - invoke the CoPilot Chat. Ask it to "Add the most commonly used aliases, but don't delete or overwrite any existing settings"

• 👉 add, commit -m "related to #4" and push the development branch branch 👈
• 👉 Create a pull request run: gh pr create --fill 👈
• 👉 Run gh browse and finish the pull request from the web 👈
• 👉 Come back to the CodeSpace and run the commands listed below: 👈

git co master
git pull
git branch -d 4
# After you've typed '4' use <TAB> to complete the branch name