Start here!

[github-learning-lab]

Hi there 👋!

Hello @epuertat, I'm so excited to teach you how to use GitHub Script in your workflows 😄

What is GitHub Script?

GitHub Script is a really awesome action that allows you to quickly interact with the GitHub API directly in your workflow!

This allows you to use the workflow context to script any API usage that is available through the octokit/rest.js library without the need to build a bulky custom action to do so.

📖 See octokit/rest.js for the API client documentation.

Let's take a closer look at how this action compares to Octokit.

[github-learning-lab]

Create an issue comment

If we take a look at the Octokit documentation on how to create issue comments we are greeted with the following method:

someFile.js

octokit.issues.createComment({
  owner,
  repo,
  issue_number,
  body
});

Okay, that doesn't seem so hard. Now that we know how to do it with Octokit let's take a look at how to use GitHub Script to create an issue comment:

my-workflow.yml

- uses: actions/[email protected]
  with:
    github-token: ${{secrets.GITHUB_TOKEN}}
    script: |
    github.issues.createComment({
        issue_number: context.issue.number,
        owner: context.repo.owner,
        repo: context.repo.repo,
        body: '👋 Thanks for reporting!'
    })

Open a pull request

Now let's examine what it's like to open a pull request with octokit/rest.js:

someFile.js

octokit.pulls.create({
  owner,
  repo,
  title,
  head,
  base
});

Again, that's not too hard at all. Now let's do the same thing, only using the GitHub Script action:

- uses: actions/[email protected]
  with:
    github-token: ${{secrets.GITHUB_TOKEN}}
    script: |
    github.pull.create({
        repo: github.context.repo.repo,
        owner: github.context.repo.owner,
        head: github.context.ref,
        base: "main",
        title: "from my action",
        body: "## I totally used GitHub Script to pull this off 🔥"
    })

[github-learning-lab]

That's not much different, so why might I want to use GitHub Script?

With GitHub Script you don't have to worry about

• Building a custom action to create this issue comment.
• No Octokit dependencies to worry about.
• No additional packages to manage.
• No need to write action metadata.
• No need to write source code to handle this Octokit method.

Using GitHub Script instead of writing custom actions for repository related tasks can prove to be a much more light-weight solution in most cases.

Anything you can do with Octokit can be accomplished with GitHub Script 🎉!

---

You may have noticed that when using GitHub Script the method call starts with github and not octokit. This is because GitHub Script provides you with a pre-authenticated octokit/rest.js client stored in a variable named github.

context is a reference to an object containing the context of the current workflow run

[github-learning-lab]

Using GitHub Script in a workflow

Actions are enabled on your repository by default, but we still have to tell our repository to use them. We do this by creating a workflow file in our repository.

If you've been following the learning path for GitHub Actions then this task is quite familiar to you.

Brand new to GitHub Actions? Click here to learn about workflows!

What is a workflow file?

A workflow file can be thought of as the recipe for automating a task. They house the start to finish instructions, in the form of jobs and steps, for what should happen based on specific triggers.

Your repository can contain multiple workflow files that carry out a wide variety of tasks. It is important to consider this when deciding on a name for your workflow. The name you choose should reflect the tasks being performed.

📖 Read more about workflows

⌨️ Activity: Respond to an issue when it gets opened

1. Create a new workflow file titled .github/workflows/my-workflow.yml with the following contents:
   You can use this quicklink to easily create this file

   name: Learning GitHub Script
   
   on:
     issues:
       types: [opened]
   
   jobs:
     comment:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/[email protected]
           with:
             github-token: ${{secrets.GITHUB_TOKEN}}
             script: |
               github.issues.createComment({
                 issue_number: context.issue.number,
                 owner: context.repo.owner,
                 repo: context.repo.repo,
                 body: "🎉 You've created this issue comment using GitHub Script!!!"
               })

2. Commit the workflow to a new branch.

3. Create a pull request. I suggest a title like Automate issue responses.

4. Supply the pull request body content and click Create pull request.

About pull pull request titles and content

It is important to place meaningful content into the body of the pull requests you create. This repository will stay with you long after you complete the course. We recommend you use the body of your pull requests as a way to take long lived notes about thing you want to remember.

In practice, good pull request titles and content convey information efficiently to your collaborators.

You can fill the body of this pull request with the following recommended content:

Workflow files are the recipe for task automation. This is where actions are placed if I want to use them for a task.

---

I am waiting for you to create a new pull request before moving on.