DEV Community: Michael Heap

The ultimate guide to GitHub Actions authentication

Michael Heap — Tue, 05 Oct 2021 16:01:58 +0000

If you’ve done any work with GitHub Actions, you’ve probably come across the GITHUB_TOKEN secret. This token allows you to interact with the GitHub API and push or pull a repositories contents. GitHub automatically generate a token for you, and it’s only available whilst your workflow jobs are running.

This is awesome for 90% of the things you’d want to do with GitHub Actions, but what about the remaining 10%? The tasks where GITHUB_TOKEN doesn’t have the correct permissions, or when you want to trigger another GitHub Action somehow, but the GITHUB_TOKEN key won’t let you?

The good news is that you’re not out of luck! You’ve got two options for working with the GitHub API - a personal access token (or PAT) and a GitHub App. A PAT is much simpler to set up, but a GitHub App is a lot more powerful. It’s entirely up to you which route you choose.

Working with `GITHUB_TOKEN`

Before we move on to personal access tokens and GitHub Apps, I want to spend a little time talking about the magical GITHUB_TOKEN secret that GitHub provide. It works well enough for the majority of cases, so you probably haven’t thought too much about it.

Even though it’s just there, there’s a lot to GITHUB_TOKEN.

Token Permissions

I'm going to lead with this as it’s key but not many people know about it. GITHUB_TOKEN allows you to specify which permissions the token is granted.

I’m going to say that one more time for the people in the back. GITHUB_TOKEN allows you to specify which permissions the token is granted.

This is huge, as it means that a rogue action can only perform the actions that you’re expecting a workflow to do.

Imagine that you work on a team where you use labels to mark pull requests as major, minor or patch version changes. If it’s a major change, you want to automatically add a comment explaining why the PR won’t be immediately merged. The workflow file you use would look something like this:

on:
  pull_request:
    types:
      - labeled
jobs:
  add-comment:
    runs-on: ubuntu-latest
    steps:
      - uses: evil-author/add-comment@main
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          comment: "Thanks for the PR! I've tagged this for the next major release as it has some backwards compatability breaks"
          label: "semver:major"

Your workflow could work great for the first month, six months, or year. However, there’s no guarantees about what code evil-author/add-comment@main will run at any point in time (if you do want guarantees, check out pin-github-action).

Imagine that you’re running the action on a private repository full of sensitive information. Although you set out to automatically add comments to a pull request, somehow the add-comment action has been compromised and the code on main is doing something that you're not expecting. Now all your data has been sent off to a third party server by some code that wasn't there when you added the action to your workflow.

You can prevent actions from doing anything except what you expect by using the permissions key in your workflow file. If we want the add-comment action to only have the ability to add a comment to an issue, we can add the issues permission:

on:
  pull_request:
    types:
      - labeled

permissions:
  issues: write

jobs:
  add-comment:
    runs-on: ubuntu-latest
    steps:
      - uses: evil-author/add-comment@main
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          comment: "Thanks for the PR! I've tagged this for the next major release as it has some backwards compatability breaks"
          label: "semver:major"

If the add-comment action is compromised with this workflow, it will be unable to read the repository’s contents using the API as you’ve only provided the issues permission. When you set the permissions key, all unspecified permissions default to no access.

You can also provide permissions at the job level instead of, or in addition to, the workflow level. This allows you to provide specific permissions to actions that require them.

on:
  pull_request:
    types:
      - labeled

permissions:
  issues: write

jobs:
  add-comment:
    runs-on: ubuntu-latest
    steps:
      - uses: evil-author/add-comment@main
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          comment: "Thanks for the PR! I've tagged this for the next major release as it has some backwards compatability breaks"
          label: "semver:major"
  needs-checks:
    runs-on: ubuntu-latest
    permissions:
      checks: write
    steps:
      - uses: trusted-user/update-check@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          name: merge-this-sprint
          status: fail

Be careful! If you don’t specify the permissions key, the token will be granted read/write permission for all of the available scopes. If you’d like to change this behaviour, you can head in to your repository settings, choose the Actions section on the left and then select Read repository contents permission at the bottom.

Once that’s done, any GITHUB_TOKEN generated in a workflow without a permissions section will only be able to read repository contents and metadata - not pull requests, issues, checks or any of the other scopes.

Be careful though, as even with this restricted configuration, the read permission is granted for your repo contents (and the contents permission covers a lot more than just the files in the repo).

If you’ve unsure which permissions your GITHUB_TOKEN has, you can see them listed in the Set up job section of the logs for your run. It’ll look something like this:

> GITHUB_TOKEN Permissions
  Actions: write
  Checks: write
  Contents: write
  Deployments: write
  Discussions: write
  Issues: write
  Metadata: read
  Packages: write
  PullRequests: write
  RepositoryProjects: write
  SecurityEvents: write
  Statuses: write

Security

Staying with the security theme, there are a lot of security considerations around GITHUB_TOKEN in addition to being able to set granular permissions.

Expiration: A new GITHUB_TOKEN is generated when each job begins, and the token expires when the job is finished

Secure: The GITHUB_TOKEN secret will not be shown in logs and can not be extracted from the runner via HTTP (trust me, I’ve tried)

Available by default: This is important. GitHub Actions that you use can access the GitHub token even if you don’t pass it in as an input. They can access it through the github.token context, including setting it as a default input in their action.yml. You should make sure that you set the minimum permissions required using the permissions parameter.

Scope: The GITHUB_TOKEN is scoped to the repository running the workflow. It cannot be used to make changes to any other repositories.

These security considerations make the GITHUB_TOKEN the best choice when interacting with the GitHub API in your actions unless you have specific requirements that require a behaviour that the GITHUB_TOKEN can’t achieve.

When `GITHUB_TOKEN` isn’t enough

The number 1 question that I’ve seen around the GITHUB_TOKEN is “Why doesn’t it trigger new workflow runs?”. GitHub decided that any actions performed by the GitHub Actions bot should not trigger events, which means that you can’t use a workflow to trigger another workflow whilst using the GITHUB_TOKEN secret. This is to prevent circular dependencies that can cause your builds to get stuck in a loop.

The other question I frequently see is “Can we change the user shown for GITHUB_TOKEN?”. This can be useful when changes are committed to a repository, or a comment is added to an issue or pull request. Rather than showing github[bot] as the user, people would like to show a company branded account. This is possible when committing changes by setting the author email address, but not when adding an issue or pull request.

The GITHUB_TOKEN is limited to the current repository, which is great in most cases but prevents some workflows. If you want to make a change in another repository when a PR is merged, this is not possible with the default GITHUB_TOKEN. An example of this workflow is to automatically update a submodule pointer in repository B when main changes in repository A.

Fortunately there are ways to work around all of these limitations. Keep reading to understand the options and the pros and cons of each.

Bonus: It’s a GitHub App under the hood!

The GITHUB_TOKEN provided by actions isn’t something custom built especially for Actions. It leverages the existing GitHub Apps infrastructure, which is why the permissions list is a lot closer to how GitHub Apps handles permissions than how user accounts handle scopes.

Whilst the list of permissions is limited today, there may be a day when the full set of applications permissions is available to GITHUB_TOKEN. Imagine being able to control your Environments automatically using the provided GITHUB_TOKEN.

I think GitHub have made the correct decision today, where there are limited permissions available as people learn about token security with Actions, but I’m interested to see what else they open up in the future.

Authentication options

Now that we’ve covered GITHUB_TOKEN and the limitations you can face when using it, let’s take a look at the alternatives. Most of the workarounds you’ll find online recommend using a Personal Access Token (or PAT). There is another option though - GitHub Apps!

In this section we’ll take a look at both personal access tokens and GitHub Apps to help decide which is the correct option for you.

Personal Access Token (PAT)

A personal access token (PAT) is an authentication token scoped to a single GitHub user account. The scopes available are the same as the scopes for OAuth Apps. These tokens are typically used by an individual to work with their repositories and data, and as such the permissions are quite coarse. Granting the repo scope allows access to almost everything

Grants full access to repositories, including private repositories. That includes read/write access to code, commit statuses, repository and organization projects, invitations, collaborators, adding team memberships, deployment statuses, and repository webhooks for repositories and organizations. Also grants ability to manage user projects.

The only areas that you can’t modify with a repo scoped token are repo workflows and GitHub packages, in addition to some organization administration tasks.

If you don’t need total access, there are sub-permissions available, such as repo:status, public_repo and repo:invite. As always, selecting the minimum permissions required to achieve your task is key. If you don’t need access to private repositories, the public_repo scope might be the correct one for you. Alternatively, if you only need to read and write commit statuses, the repo:status permission may be all you need.

If you’re going to use a PAT for automation purposes, I recommend creating a dedicated GitHub account to use. This allows you to control which repositories that account has access to, and prevents any integrations performing actions as your personal user. This is a common pattern, and even the GitHub docs team use it with their Octomerger Bot.

Creating a PAT

To create a personal access token, you can visit the PAT page in settings whilst logged in. This will show all of your existing tokens and allows you to create a new token.

Make sure to add a good note for your new token. In 6 months time when you’re reviewing your tokens (you review regularly, right?) you’ll be thankful that you know why each token exists

Token expiration is a recent feature, which I recommend you take advantage of. Having an expired token cause your workflow to fail isn’t ideal, but it’s better than having a leaked token be valid forever. My recommendation is to set this value as low as possible, with 30 days being my personal maximum validity. Rotating this credential is easy if you use organization secrets to define it once and provide access to multiple repositories. If you’re not using an org and need to update multiple repositories under a user account you may find github-update-secret useful.

Finally, you have to choose your scopes. As mentioned above, try and minimise the scopes available. My personal workflow is to generate a token with repo scope whilst developing a workflow, then revoke that token and build a new token with minimal permissions once the action is working. Unfortunately, there’s no way to provide the issues permission without also allowing access to everything else.

Benefits

The biggest benefit to personal access tokens is how easy they are to get started with. You can switch from using GITHUB_TOKEN to a PAT in under 5 minutes. Once you’ve switched, all the limitations of GITHUB_TOKEN disappear.

You can now trigger a workflow from another workflow. I’ve used this to trigger automatic release generation whenever a pull request was merged to main.

You can also make changes across multiple repositories. Going back to an earlier example, you could now raise a pull request in repository B whenever main changes in repository A.

Finally, as your personal access token belongs to a user, any comments or commits added will show the username and profile image of your account. This can make the experience a little more personable, even though it’s still being automated.

Downsides

Although using a PAT makes it easy to get started, there are some downsides compared to using the GITHUB_TOKEN.

The biggest downside is that if your token is leaked, it can be used by people other than the GitHub Actions runner. If you set a long expiry time, this could go undetected for a while. If you set a short expiry time, you’ll spend all your time rotating credentials.

The available permissions are also less granular than those offered by the GITHUB_TOKEN. There is no way to provide access to just issues without also giving access to everything else in the repo scope.

This is changing! If you're interested in granular scopes for personal access tokens, follow this public roadmap item from GitHub

Secondly, people join and leave companies. If your PAT is owned by someone that no longer works there, and no longer has access to your repos (with good reason!) all your workflows will stop working.

If you use an automation account, it’s likely to be shared across multiple purposes on your team. This makes it more difficult to track who is making each change as these credentials can be used anywhere, not just within Actions.

Finally, if you work at a company with GitHub enterprise enabled you may start hitting compliance issues. Shared accounts are frowned upon, and it gets even harder when your GitHub login is done through single sign on with your IDP. Suddenly you now have to pay for a few additional (or lots of additional, depending on how they feel about shared accounts) GitHub seats, each of which is mapped to an identity in your IDP. It is possible (I’ve done it!), but the barrier to entry is much higher than the five minutes promised earlier.

GitHub Apps

If you don’t need to perform actions on behalf of a user, a GitHub Apps might be the right choice for you. Applications are how the majority of GitHub integrations are built, and is how people built custom workflows before Actions existed (usually using Probot).

Applications excel when it comes to security. They give you the fine grained permissions that GITHUB_TOKEN provides, time limited tokens (without the need to rotate credentials) and more!

Creating an application

Creating an application is a little more involved than creating a PAT. There are two types of application - GitHub Apps and OAuth apps. Make sure that you’re on the GitHub Apps page in your settings. An application can be owned by an individual user account, or an organization. If you’re using this for work, I’d recommend creating the application under your org.

The GitHub App name and description are usually critical when it comes to onboarding, but as this is intended to be an internal only application you can choose any name and description that you like. You’ll also need to provide a homepage URL, but this isn’t used by a callback workflow at all, so put in any URL you like.

You don’t need to provide a Callback URL or Setup URL, and you’ll want to make sure that webhooks are deactivated.

Finally, we’re on to Repository permissions. This is the important part. Each of the permissions shown can be granted with a none, read, write and in some cases, admin permission. You can click on the (i) next to each permission to learn more about which endpoints are covered by that permission. Hereis the list of endpoints accessible with the checks permission. It can be quite hard to read, so let me break it down for you.

If you grant the checks permission to your application, you’ll be able to call POST /repos/:owner/:repo/check-runs to create a check run, but only if you’ve granted write permission. You’ll also be able to call GET /repos/:owner/:repo/check-runs/:check_run_id if you have read or write permission.

It can be hard to match up each endpoint to what you’re trying to achieve, but you can click each request to learn more about each endpoint’s capabilities and parameters.

It’s important to note that the permissions you select when creating an application are the maximum permissions available to that application. You can request fewer permissions in the generated token, but you can’t ask for extra permissions. With that in mind, I’d spend some time thinking about what your actions need to achieve and set these permissions appropriately.

Right at the bottom there’s a User permissions section - we can ignore this as we’ll be making server to server requests rather than editing users.

Finally, you need to decide where the application can be installed. I tend to allow it only on my account and create new applications in each organization that needs to use application authentication.

Create your application and save your App ID and Private Key in a safe place as you’ll need them both in the next step. You’ll also need to install it on your account or organization before using it to create authentication tokens.

Using applications in a GitHub workflow

Now that you’ve created an application, it’s time to update your workflows to generate an authentication token using that app rather than using GITHUB_TOKEN or a PAT.

There are a couple of actions available, but I like this one from Peter Murray as it works for applications installed at both an organization and a repository level.

To use this action you’ll need to create two secrets in your repo or organization: APPLICATION_ID and APPLICATION_PRIVATE_KEY using the details you saved when creating an application.

Once that’s done, it’s time to update your workflow! Imagine that you have the following workflow that creates a release using the provided GITHUB_TOKEN:

jobs:
  create-release:
    runs-on: ubuntu-latest

    steps:
      - name: Use Application Token to create a release
        uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with: ...

This works, but you’d like to create a release as your company’s application rather than the GitHub bot. By adding an additional step to generate a token using your application, you can use the token output in the create-release action:

jobs:
  create-release:
    runs-on: ubuntu-latest

    steps:
      - name: Get Token
        id: get_workflow_token
        uses: peter-murray/workflow-application-token-action@v1
        with:
          application_id: ${{ secrets.APPLICATION_ID }}
          application_private_key: ${{ secrets.APPLICATION_PRIVATE_KEY }}

      - name: Use Application Token to create a release
        uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: ${{ steps.get_workflow_token.outputs.token }}
        with: ...

This will create the release with your application’s identity, rather than using the GitHub bot.

I mentioned earlier that you can request limited permissions from an application. The example above will return a token that has the maximum permissions available to an application. Here’s an example of a workflow that requests write access to issues and read access to deployments:

Support for permissions is a recent addition and is not available until this PR is merged

jobs:
  permission-demo:
    runs-on: ubuntu-latest

    steps:
      - name: Get Token
        id: get_workflow_token
        uses: peter-murray/workflow-application-token-action@v1
        with:
          application_id: ${{ secrets.APPLICATION_ID }}
          application_private_key: ${{ secrets.APPLICATION_PRIVATE_KEY }}
          permissions: "issues:write,deployments:read"

You’ve now got a solution that has all the benefits of GITHUB_TOKEN such as granular permissions and automatic expiry, but none of the downsides. Let’s dig in to the benefits and downsides of using a GitHub App for authentication.

Benefits

Let’s go back to the number 1 question that people have about GITHUB_TOKEN. “Why does my workflow not trigger other workflows?”. Using a GitHub App solves this problem, just like using a personal access token does. However, there are other benefits that applications bring over a PAT.

Application tokens are valid for a very short amount of time. Using this action, the token is valid for 60 seconds from the moment it’s created. This means that even if it’s leaked by an action, it will be useless almost immediately.

As this is an application and not an account, there’s no shared account for people to log in to. This means better accountability, and no SSO/IDP issues mentioned above if you’re using GitHub Enterprise.

Finally, the biggest benefit to using applications is how granular the permissions are. Here are all the different permissions that you can allow using applications:

Repository permissions

Actions
Administration
Checks
Content references
Contents
Deployments
Discussions
Environments
Issues
Metadata
Organization packages
Packages
Pages
Pull requests
Webhooks
Projects
Secret scanning alerts
Secrets
Security events
Single file
Commit statuses
Dependabot alerts
Workflows

Organization permissions:

Members
Administration
Events
Webhooks
Plan
Projects
Secrets
Self-hosted runners
Blocking users
Team discussions

Downsides

The biggest downside to using a GitHub App is that you need to edit every workflow to add an additional step where you generate a token for use later on. This can make your workflows harder to read for those that aren’t familiar with the application token workflow.

If you need to perform any actions as a user, this authentication mechanism won’t work for you. Whilst GitHub App do support user OAuth, the way we’ve configured it for use with Actions they’re not suitable for managing user profiles.

Finally, understanding all of the available permissions can be tough. Using applications for authentication has a lot of benefits even if you don’t use it to scope permissions to the minimum required, but you’re losing the biggest benefit if you don’t.

So which is the best?

There are three options for authentication when it comes to GitHub Actions:

GITHUB_TOKEN
Use a Personal Access Token (PAT)
Generate credentials with a GitHub App

Each of these options have pros and cons. If you can achieve everything you need using GITHUB_TOKEN, I’d stick with that for your workflows. It’s well understood by the community and reduces the number of moving parts in your workflows.

Given the choice between a PAT and a GitHub App, I’d choose a GitHub App unless you need to perform actions as a user. It solves the main problems with GITHUB_TOKEN (triggering new workflow runs, posting as an identity other than github[bot]) without any of the issues that a PAT introduces (long lived tokens, shared accounts).

That concludes the ultimate guide to GitHub Actions authentication. If you’ve got any questions or comments, I’m @mheap on Twitter and I’d love to hear them.

8 Common Request Transformation Policies

Michael Heap — Tue, 27 Jul 2021 13:00:17 +0000

API gateway request transformation policies are incredibly powerful. There are many situations when an API developer can take advantage of request transformations to adjust the shape and values of a request to cleanly fit their API.

Let’s say you’re deprecating a certain endpoint for your API, but you still need to support the old specification for a transition period. Request transformations let you accept requests according to the old specification, transform them to fit the new specification and then forward them.

Or maybe you discovered that incorrect documentation on an endpoint’s query parameter specification has been in the wild for far too long, which is why so many users have been encountering errors. Rather than changing your API to fit bad documentation, you can use request transformations to modify requests as they come in, shaping them according to how your API is supposed to work.

Or perhaps it’s simply time to implement basic security best practices, like stripping or obfuscating sensitive data in the headers before letting them continue upstream.

For these and many other reasons, request transformations can be your go-to solution.

This article will look at how we might use Kong Gateway, coupled with the Request Transformer plugin, to configure, intercept and transform requests as they make their way to an upstream route. Setup and configuration are incredibly simple. We’ll cover several common use cases:

Copying an API Key from the query string to the header
Removing a query string value
Moving an API key from a query string to the header
Adding a version number to a query string
Modifying the header token to Bearer Auth
Moving JWT from header to body
Sanitizing the body
Changing the HTTP method

This should give you enough foundation to craft your own transformations, custom-tailored for your application situation.

Overview of Core Concepts

Before we dive in, let’s quickly cover the technologies we’ll be using for our walkthrough.

Kong Gateway

Kong Gateway is a thin-layer, front-line “gateway” sitting in front of your system’s upstream services. Whether those upstream services are API servers, web servers or any other cloud microservices, Kong Gateway handles traffic control, authentication, load balancing and more.

Request Transformer Plugin

The Request Transformer plugin for Kong Gateway comes built in. As requests come through Kong, you can configure the plugin to transform those requests—mutating headers, query string parameters, the request body and so on—before forwarding those requests to their final destination. Transformations are highly configurable and extremely powerful, giving you a lot of control over the precise shape of requests before they hit your endpoint.

Mockbin

Mockbin is an online custom endpoint generator used for testing HTTP requests and tracking responses. Mockbin is exactly what we need for our walkthrough—as we set up transformations, send requests and then inspect the result.

Our Walkthrough Approach

To start, we’ll set up our Mockbin endpoint as our “upstream service.” We only need a single endpoint, and we’ll hit it with GET and POST requests. Then, we’ll make sure Kong Gateway is installed and configured properly.

We’ll look at configuring the Request Transformer plugin for each transformation that we want to demonstrate. Then, we’ll send our request (using curl). Finally, we’ll inspect the request at Mockbin. We want to see what the request looked like when it arrived at Mockbin after passing through Kong and the Request Transformer plugin.

Are you ready? Roll out!

Want to set up a request transformation for your API gateway with clicks instead of code? Try Konnect for free >>

Set Up Mockbin Endpoint

Mockbin is a simple and easy-to-use test endpoint generator. On the website, click on the Create Bin link to get started.

And, just like that, your endpoint has been created! From here, you will need your endpoint URL. This is just https://mockbin.org/bin/{BIN-IDENTIFIER}. But, for good measure, you can right-click on Visit in Browser and copy the link address.

To test it out, you can open a new tab in your browser and visit the link you just copied. Doing so will send a GET request to your Mockbin endpoint. To see the details for this request, go back to the browser tab with your Mockbin details and click on View History. You’ll see a running log of requests to this endpoint. You should see the GET request that you just sent:

Our Mockbin endpoint is up and running and ready to go.

Set Up Kong Gateway

Spinning up Kong Gateway is quite straightforward. First, you’ll need to install Kong on your local machine. There are many different installation options, so you can choose whichever best fits your environment.

After installing Kong, create a project folder on your local machine. For simplicity, I’m creating a sub-folder called “project” in my home folder. Then, in that folder, run the command to generate a declarative configuration file.

~$ mkdir project
~$ cd project
~/project$ kong config init
~/project$ tree
.
└── kong.yml

0 directories, 1 file

For our use of the Request Transformer plugin, we can put all of our service and route setup and plugin configurations in a single file. Then, start Kong. Kong does not need to write to a database, and we don’t need to do any further on-the-fly configuration as we go along. This is Kong’s DB-less and Declarative Configuration, and it’s sufficient for what we need.

The kong.yml file is a starter template for a declarative configuration file. Let’s open it and modify it to look like the following:

# ~/project/kong.yml
_format_version: "2.1"

services:
- name: mockbin
  url: https://mockbin.org/bin/REPLACE-WITH-YOUR-BIN-IDENTIFIER
routes:
- name: untouched
  service: mockbin
  paths:
    - /untouched

Let’s briefly go over what we’ve done here. The _format_version line, which is required, specifies the version number of the declarative configuration syntax we’re using. Next, we declare an upstream service, and we give it the arbitrary name “mockbin” and specify the URL for this upstream service. Make sure you use your unique URL for the Mockbin endpoint you created earlier.

Next, we create a route, which we will arbitrarily name “untouched.” This route listens on the Kong Gateway for requests that go to the path /untouched, and then it forwards those requests to our upstream service called “mockbin.” In this first example, we are not adding a Request Transformer plugin. Requests will proceed through Kong Gateway untouched, continuing to Mockbin.

We’re almost ready! The last thing we need to do is tell Kong where to look for our declarative configuration file when it starts up. To do this, we need a kong.conf file, copied from the default template provided to us upon installation:

~/project$ cd /etc/kong
/etc/kong$ cp kong.conf.default kong.conf
~/project$ sudo vi kong.conf

In the kong.conf file, there are two lines that we need to edit. At around line 922, we need to tell Kong that we won’t be using a database. And at around line 1106, we need to provide the absolute path to our declarative configuration file. That’s the kong.conf file in your project folder.

# PATH: /etc/kong/kong.conf

...

# AROUND LINE 922
# inherited from the corresponding main connection config described above but
# may be optionally overwritten explicitly using the `pg_ro_*` config below.

database = off # Determines which of PostgreSQL or Cassandra
                              # this node will use as its datastore.

# AROUND LINE 1106
                              # This value is only used during
                              # migrations.

declarative_config = /PATH/TO/YOUR/PROJECT/FOLDER/kong.yml
                              # The path to the declarative configuration
                              # file which holds the specification of all
                              # entities (Routes, Services, Consumers, etc.)

With the file saved, we’re ready to start up Kong.

~/project$ sudo kong start

Now that Kong is running, let’s send a request to localhost:8000, which is the port where Kong is listening. We’ll send a GET request to the /untouched endpoint, and we’ll tack on a query string parameter:

~/project$ curl -X GET 'http://localhost:8000/untouched?hello=world'

In your browser, refresh the page with your Mockbin endpoint history log. You should see a new entry for a GET request.

As you view the Request Details, you can see that the queryString array has a pair that matches the parameters we sent to Kong. It looks like Kong successfully forwarded our (untouched) request to Mockbin!

Just for good measure, let’s also send a POST request to the same endpoint at Kong. We’ll set our “Content-Type” header and tack on a request body like so:

~/project$ curl -X POST \
           -H 'Content-Type: application/json' \
           -d '{"hello":"world"}' \
           'http://localhost:8000/untouched'

Again, we refresh the Mockbin log, and we see our POST request. Here, we see our Request Body, which matches what we sent to Kong.

If we poke around at the Request Details, we also see the “Content-Type” value that we set in our header, along with our POST body data.

It looks like we have finished our setup. We’ve connected all the pieces. It’s time to start playing around with some common request transformations.

Common Request Transformations

1. Copy API key from query string to header

Let’s start with a common scenario. Your API users have been adding their API key as a query string parameter, but you’d like to transition them toward attaching it as a custom header value instead. Until you’re certain that all of your API users have gotten the memo that the key should be in the header, you want to accommodate the stragglers. What you need is a request transformation that copies the value from the query string parameter to a new header value.

Here is how our kong.yml file would look:

# ~/project/kong.yml
_format_version: "2.1"

services:
- name: mockbin
  url: https://mockbin.org/bin/REPLACE-WITH-YOUR-BIN-IDENTIFIER
routes:
- name: copy-query-to-header
  service: mockbin
  paths:
    - /copy-q2h
plugins:
- name: request-transformer
  route: copy-query-to-header
  config:
    add:
      headers:
        - api-key:$(query_params.api_key)

Similar to our first example, we’ve created a service, along with a route that forwards to this service. For this route, Kong will listen on the path /copy-q2h. Next, we add a plugin. The name of this plugin ( not arbitrary) is request-transformer. The plugin is for our specific route.

What kinds of request transformations should this plugin do? It will add a header. The new key for this header will be api-key. The value will be copied from the query string parameter called api_key. This part uses the plugin’s templating feature to grab a value that came in the query string

Don’t forget: Whenever we modify the kong.yml file, we need to restart Kong. Let’s restart Kong and send our request.

~/project$ sudo kong restart
~/project$ curl -X GET 'http://localhost:8000/copy-q2h?api_key=THISISMYAPIKEY'

We’ve sent a GET request to our /copy-q2h endpoint. We tacked on a query string parameter api_key=THISISMYAPIKEY. Let’s see how this request was transformed by refreshing the Mockbin log.

As we scroll down the Request Details, we see in the headers that there is an api-key header with the value THISISMYAPIKEY. It looks like our copy transformation worked.

You will notice that the api_key=THISISMYAPIKEY query string parameter is still in the request, though. That’s okay for now. We’ll deal with that in a little bit.

2. Remove query string value

Another common scenario involves the need to remove certain query string parameters completely. Perhaps for privacy reasons or security reasons, sanitizing query parameters is a common use case for request transformations.

In the following kong.yml example, we want to remove the key-value pairs for the api_key and password query string parameters. Similar to our previous example, we create a route (listening on /strip-q), and we create a plugin on that route that removes our undesirable parameters:

# ~/project/kong.yml
_format_version: "2.1"

services:
- name: mockbin
  url: https://mockbin.org/bin/REPLACE-WITH-YOUR-BIN-IDENTIFIER
routes:
- name: strip-query
  service: mockbin
  paths:
    - /strip-q
plugins:
- name: request-transformer
  route: strip-query
  config:
    remove:
      querystring:
        - api_key
        - password

Let’s send a request to this path, adding on a few query parameters. We’ll include the ones we want to strip away, along with one that we would like to keep. Don’t forget to restart Kong!

~/project$ sudo kong restart
~/project$ curl -X GET \
'http://localhost:8000/strip-q?api_key=THISISMYAPIKEY&username=johndoe&password=THISISMYPASSWORD'

Taking a glance at the Mockbin log, we can see that this most recent GET request received the query string parameter we wanted to keep (username=johndoe) but didn’t receive the undesirable ones. That’s a good sign.

A closer look at the query string array in Request Details shows that the plugin worked as expected, removing the api_key and password parameters before forwarding the request to Mockbin.

Just a note: You could write kong.yml with multiple routes and multiple plugins. In this article, our file always shows just a single route and a single plugin. That’s just to keep it simple, but you’re not restricted to do it this way.

3. Move API key from query string to header

Previously, we copied an API key from the query parameter to a header value, but we left the query parameter in the request. In the following example, let’s do something similar, but we’ll clean up after ourselves by removing the query parameter too. Our configuration for the plugin this time around: 1) adds a header based on the query parameter value, and then 2) removes the query parameter.

# ~/project/kong.yml
_format_version: "2.1"

services:
- name: mockbin
  url: https://mockbin.org/bin/REPLACE-WITH-YOUR-BIN-IDENTIFIER
routes:
- name: move-query-to-header
  service: mockbin
  paths:
    - /move-q2h
plugins:
- name: request-transformer
  route: move-query-to-header
  config:
    add:
      headers:
        - api-key:$(query_params.api_key)
    remove:
      querystring:
        - api_key

At this point, the keen observer might be asking: “Wait, if you remove the query parameter, how would you copy its value over to the header? Does the configuration order matter, where you have to copy it before you remove it?” The answer is… no! Kong’s documentation on template values explains it this way:

Note: The plugin creates a non-mutable table of request headers, query strings, and captured URIs before the transformation. Therefore, any update or removal of params used in a template does not affect the rendered value of a template.

Let’s restart Kong and send our request.

~/project$ sudo kong restart
~/project$ curl -X GET 'http://localhost:8000/move-q2h?api_key=THISISMYAPIKEY'

An inspection of the Request Details at the Mockbin log shows the value in our headers:

4. Add version number to query string

Another common case is simply adding a query string parameter to a request. In this example, we’ll add a fixed API version number to all requests that come through our /add-q route:

# ~/project/kong.yml
_format_version: "2.1"

services:
- name: mockbin
  url: https://mockbin.org/bin/REPLACE-WITH-YOUR-BIN-IDENTIFIER
routes:
- name: add-to-query
  service: mockbin
  paths:
    - /add-q
plugins:
- name: request-transformer
  route: add-to-query
  config:
    add:
      querystring:
        - api_version:2.0

We will add the parameter called api_version, and its value will be 2.0. Let’s restart Kong and send our request.

~/project$ sudo kong restart
~/project$ curl -X GET 'http://localhost:8000/add-q?username=johndoe'

While we only set one query parameter (username=johndoe), we inspect our transformed request at the Mockbin log. There we see in the Request Details that Mockbin received two parameters with the request:

It looks like our query parameter add was successful.

5. Modify header token to Bearer Auth

Now, let’s experiment with our headers a bit. Imagine the scenario where your API users are attaching their authorization token as a header called token, but you wrote your API to use the Bearer Auth scheme. The token value should be in a header called Authorization, following the word “Bearer!” Collin, the junior dev who wrote that erroneous API documentation, will get a poor performance review. In the meantime, you’ll use request transformation to fix Collin’s mess.

# ~/project/kong.yml
_format_version: "2.1"

services:
- name: mockbin
  url: https://mockbin.org/bin/REPLACE-WITH-YOUR-BIN-IDENTIFIER
routes:
- name: modify-header
  service: mockbin
  paths:
    - /token-to-auth
plugins:
- name: request-transformer
  route: modify-header
  config:
    add:
      headers:
        - Authorization:Bearer $(headers["token"])
    remove:
      headers:
        - token

Our configuration again takes advantage of template values, copying the token value from the token header and structuring a proper Bearer Auth header value. And, of course, we remove the undesirable token header after we get what we need.

We restart Kong and send our request.

~/project$ sudo kong restart
~/project$ curl -X GET \
-H 'token:thisisanopaquestringthatrepresentsajwt' \
'http://localhost:8000/token-to-auth'

For this request, we sent our token value in the header called
token. Let’s inspect the Request Details at our Mockbin log:

We see the Bearer Auth scheme in our header now. A further inspection of the details shows that the offending token header is not present. On a side note, you might notice above that we had configured our plugin to add a header with the name “Authorization” (capitalized), but what shows up in Mockbin is “authorized” (lowercase). It looks like this might be an issue with Mockbin—which lowercases all of its header names—and not an issue with the Request Transformer plugin (which addressed this specific issue in a pull request).

6. Move JWT from header (Bearer Auth) to body

Let’s do some request transformations that modify the request body. In this example, we’ll take the token in Bearer Auth format, and we’ll write it to our request JSON body as a value. While some upstream services look in the header for an authorization token, others might look to the request body. Request transformations provide flexibility, especially when modifying upstream services isn’t an option.

# ~/project/kong.yml
_format_version: "2.1"

services:
- name: mockbin
  url: https://mockbin.org/bin/REPLACE-WITH-YOUR-BIN-IDENTIFIER
routes:
- name: jwt-to-body
  service: mockbin
  paths:
    - /jwt2b
plugins:
- name: request-transformer
  route: jwt-to-body
  config:
    add:
      body:
        - jwt:$(headers["Authorization"]:gsub("^Bearer ",""))

The syntax for the above plugin configuration is a bit more complicated, but you can probably discern what’s happening. We want to add a key-value pair to our request body. The key is jwt, and the value will be taken with the Authorization header but with the initial “Bearer” (plus space) removed.

The plugin documentation notes that the placeholder is evaluated as Lua expression. So, if you know Lua, you can probably do some pretty powerful transformations.

Let’s restart Kong and send our POST request, along with headers and body data:

~/project$ sudo kong restart
~/project$ curl -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer thisisanopaquestringthatrepresentsajwt' \
-d '{"username":"johndoe" }' \
'http://localhost:8000/jwt2b'

When we look at our Mockbin log for this request, we immediately see the Request Body. It contains the original body we sent ("username":"johndoe"), but it also contains
jwt, with the token value that was in our Bearer Auth header.

You might notice, from our plugin configuration, that we decided to leave our Bearer Auth header in the request:

7. Sanitize body

Perhaps for sensitive data that might come through the request body, you will need a request transformation that sanitizes it but doesn’t remove it. This helps your upstream service know that the data did come through, but it’s just no longer available. For this type of transformation, your configuration might look like this:

# ~/project/kong.yml
_format_version: "2.1"

services:
- name: mockbin
  url: https://mockbin.org/bin/REPLACE-WITH-YOUR-BIN-IDENTIFIER
routes:
- name: sanitize-body
  service: mockbin
  paths:
    - /san-b
plugins:
- name: request-transformer
  route: sanitize-body
  config:
    replace:
      body:
      - last4: ****
      - api_key: ********
      - password: ********

In this request transformation, we’re looking in our JSON body for last4, api_key or password. For any of those keys, we want to replace the provided value with a redacted one. After restarting Kong, we send our request:

~/project$ sudo kong restart
~/project$ curl -X POST \
-H 'Content-Type: application/json' \
-d '{"api_key":"THISISMYAPIKEY", "username":"johndoe", "password":"THISISMYPASSWORD", "last4":9876}' \
'http://localhost:8000/san-b'

A quick glance at the Mockbin log shows our transformed Request Body. Recall that Kong transformed this body before it was sent to the upstream service, so we can be sure that none of this sensitive data got past our gateway.

8. Change HTTP method

For our final example, let’s demonstrate a request method transformation. Let’s assume that PUT requests to a given route need to be converted to POST requests, and instead, we’d add an "action":"PUT" key-value pair into the JSON request body.

In this configuration, we configure our route only to listen for PUT requests. Then, we configure the plugin to transform the http_method to POST. Lastly, we add a key-value pair to our body.

# ~/project/kong.yml
_format_version: "2.1"

services:
- name: mockbin
  url: https://mockbin.org/bin/REPLACE-WITH-YOUR-BIN-IDENTIFIER
routes:
- name: put-to-post
  service: mockbin
  methods:
    - PUT
  paths:
    - /put-to-post
plugins:
- name: request-transformer
  route: put-to-post
  config:
    http_method: POST
    add:
      body:
      - action:PUT

Restart Kong and send the PUT request.

~/project$ sudo kong restart
~/project$ curl -X PUT \
-H 'Content-Type: application/json' \
-d '{"username":"johndoe" }' \
'http://localhost:8000/put-to-post'

We see the successful result in our Mockbin log. The most recent request was a POST (not PUT) request. And, we see the action key-value pair added to our Request Body.

Conclusion

We’ve covered a lot of examples in this walkthrough. We’ve transformed query string parameters, headers, bodies and even request methods. The Request Transformer plugin offers several ways to transform parts of the request. While we’ve covered many of them, combining multiple transformations can yield powerful results that uniquely shape a request to fit your API.

We didn’t cover URI transformations, which allow you to transform the upstream request URI based on the incoming request. You can imagine taking a long REST-compliant URI, chock-full of a chain of resources, ids, sub-resources and more ids. Using URI capturing and template values, the Request Transformer plugin can capture all of that data in the URI and write it into the request body instead, sending the request upstream to a general all-purpose endpoint.

Ready for Advanced Request Transformations?

The Kong Konnect enterprise-level Request Transformer Advanced plugin provides even more targeted transformations with regular expression matching, variables and substitutions.

All in all, the ability to transform your requests at the gateway level before they hit your upstream service is critical. Whether it’s because of deprecated specs, documentation-reality misalignment or data privacy and security concerns, having the flexibility to shape incoming requests—and to do so quickly and simply—might be exactly what your DevOps team needs to save the day in a pinch.

Once you’ve successfully set up API gateway request transformation policies, you may find these other tutorials helpful:

The post 8 Common API Gateway Request Transformation Policies appeared first on KongHQ.

20 Lines of JavaScript to Create a Kong Gateway Plugin

Michael Heap — Wed, 26 May 2021 13:00:48 +0000

We recently sat down to discuss the language for the next Kong Gateway Plugin Development Kit (PDK). Given the number of JavaScript developers in the world and the variety of libraries and debugging tools available, there was only one logical choice. I’m excited to share that with the Kong Gateway (OSS) 2.4 release, that functionality is now available to you all!

To show the power of the new JavaScript PDK, we’re going to implement a plugin that adds X-Clacks-Overhead, a non-standardized HTTP header based on the work of Terry Pratchett to all responses.

Bootstrapping Your Development Environment

The JavaScript plugin support in Kong Gateway works by running a Node.js server on the same machine as Kong Gateway and passing messages back and forth using msgpack.

This means that we need a development environment that can run both the Kong Gateway and a Node.js process. You can configure this on your local machine, but to make things easier, I’ve put together a docker-based environment for you to use.

It might take a minute or two to download the images and build our Node.js environment. I recommend running it now in the background as you keep reading:

$ git clone https://github.com/Kong/docker-kong-js-pdk
$ cd kong-js-pdk-dev
$ docker-compose build

Creating Your First Plugin

The configuration provided in the environment we created reads all plugins from the plugins directory. It’s currently empty as we have not created our first plugin yet.

The JavaScript PDK uses the name of the JS file as the name of the plugin. Let’s go ahead and create a file called clacks.js in the plugins directory with the following contents:

class ClacksPlugin {
  async access(kong) {
    await kong.response.setHeader(`X-Clacks-Overhead`, "GNU Terry Pratchett");
  }
}

module.exports = {
  Plugin: ClacksPlugin,
  Version: "0.1.0"
};

The kong object passed into the access method is an instance of the JavaScript PDK provided by the plugin server. This means that we do not need to require kong-pdk in our plugins, as it is automatically made available.

There are five phases available for HTTP requests in the life-cycle of a Kong Gateway request:

-certificate – Executed once per request when the connection is SSL/TLS enabled
-rewrite – Performed before the API gateway does any routing
-access – All routing is done, and the plugin knows which service the request is bound to. This is the last phase before the API gateway makes a request to upstream
-response – Allows you to manipulate the response from the upstream. Implementing this phase has a performance penalty as it enables request buffering
-log – Executed after the request has been completed

Enable the Plugin

The environment we’re running uses Kong’s declarative config capability. That means that we need to update the config file to enable our new plugin. Open up config/kong.yml, and you should see a service defined that proxies to mockbin.org:

services:
  - name: example-service
    url: https://mockbin.org

As our file name was clacks.js, our plugin will be called clacks. Let’s enable the plugin in the definition now:

services:
  - name: example-service
    url: https://mockbin.org
    plugins:
      - name: clacks

Kong Gateway only allows you to use plugins that are on an allowlist for security purposes, so we’ll also need to add clacks to that list. Open up docker-compose.yml and edit the value of KONG_PLUGINS so that it looks like the following:

KONG_PLUGINS: bundled,clacks

Making a Request

At this point the API gateway is ready to run our new plugin, so let’s go ahead and start it:

$ docker-compose up

The docker-compose.yml file forwards the API gateway port to our local machine. That means we can make requests to localhost:8000 to test our service.

$ curl -I localhost:8000

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Connection: keep-alive
X-Clacks-Overhead: GNU Terry Pratchett
...snip...

I can see the X-Clacks-Overhead header in the response, which means that our plugin works as intended!

Making It Configurable

The custom JavaScript plugin we built today is a simple plugin that does one thing and does it well. I want to take a moment to show you how you can make that behavior customizable using plugin configuration too.

There is an ongoing discussion based on RFC 6648 about if custom headers need an X- prefix. Let’s make our plugin configurable so that people can decide if they want to use the X- prefix.

Plugin configuration is controlled using the Schema property in module.exports at the end of clacks.js. Let’s add an entry to define a use_prefix option that’s a boolean with a default value of true:

module.exports = {
  Plugin: ClacksPlugin,
  Schema: [{ use_prefix: { type: "boolean", default: true } }],
  Version: "0.1.0"
};

Any configuration provided to the plugin is passed in using the constructor. Let’s go ahead and capture that in clacks.js so that we can use it in our access method and update access so that it only adds the X- prefix if use_prefix is true:

class ClacksPlugin {
  constructor(config) {
    this.config = config;
  }

  async access(kong) {
    const prefix = this.config.use_prefix ? "X-" : "";
    await kong.response.setHeader(
    `${prefix}Clacks-Overhead`,
    "GNU Terry Pratchett"
    );
  }
}

If we run our plugin now, it will behave the same way as it did with a hardcoded X- prefix. Let’s update our API gateway config in config/kong.yml to set use_prefix to false.

services:
  - name: example-service
    url: https://mockbin.org
    plugins:
      - name: clacks
        config:
          use_prefix: false

If we restart our API gateway by pressing Ctrl+C then running docker-compose up again, we should now be able to make a request to localhost:8000 and see Clacks-Overhead header without the X- prefix:

$ curl -I localhost:8000

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Connection: keep-alive
Clacks-Overhead: GNU Terry Pratchett
...snip...

Conclusion

Just 20 lines of Javascript, and we have a working Kong Gateway plugin, complete with configuration options!

What we’ve built together is a trivial plugin, but using the environment provided and what you’ve learned about Kong’s configuration, you can go ahead and build plugins to your heart’s content.

If you’re looking for more plugin examples, take a look at some demo plugins:

If you have any questions, post them on Kong Nation .

To stay in touch, join the Kong Community.

Once you’ve successfully set up a custom Kong plugin with JavaScript, you may find these other tutorials helpful:

The post Building a Kong Gateway Plugin with JavaScript appeared first on KongHQ.

Dump Context Action

Michael Heap — Fri, 21 May 2021 18:01:06 +0000

This week's Action Spotlight introduces a new kind of action. It's the first time we're featuring a composite action, which allows you to include multiple workflow steps as a single uses statement.

Fact Sheet
Author	crazy-max
Contributors	1
Stars	9
Repo	https://github.com/crazy-max/ghaction-dump-context
Marketplace	https://github.com/marketplace/actions/dump-context

What does it do?

This action outputs the following items from the runner environment:

env
runner
github
job
steps
strategy
matrix

This allows you to see things like github.event in the output to debug the data available to your actions.

How does it work?

This is a composite action, which means that the whole thing is in a single action.yml file. It contains the fields that we'd expect to see, such as name, author and branding. However, it also has a value that we've not seen before; runs.using: composite.

This tells Actions that the action provides steps that should be run as though they were provided in the workflow itself.

There are seven steps, each dumping a different aspect of the environment. Each step uses the toJson function to convert the input to a string that can be rendered in the output and stores that in the environment. Storing it in the environment prevents quoting issues when echoing out the value later.

The characters before each heading (e.g. \033[31;1;4m) are ANSI escape codes, which tells the output to make that text red, bold and underlined.

Finally, each step has the shell set to bash. This makes the action usable on all operating systems. Without this, the action would default to Powershell on Windows and fail.

That's all there is to it - seven steps, all following the same pattern to output useful data in the logs.

Common use cases

There's only one use case - dump the current context to for debugging purposes:

name: Dump Context
on: [push, pull_request]
jobs:
  dump:
    runs-on: ubuntu-latest
    steps:
      - name: Dump context
        uses: crazy-max/ghaction-dump-context@v1

Auto-approve Workflow Action

Michael Heap — Fri, 14 May 2021 09:17:57 +0000

When GitHub disabled automatic workflow runs to prevent crypto miners it made some OSS maintainers lives harder, so I wrote a GitHub Action that automatically approves all pending workflow runs (so long as they don't edit .github/workflows)

Fact Sheet
Author	mheap
Contributors	2
Stars	6
Repo	https://github.com/mheap/automatic-approve-action
Marketplace	https://github.com/marketplace/actions/automatic-approve

What does it do?

When a pull request is raised by a first time contributor to a repo, the any workflows that would usually be triggered are set to pending. This is to prevent bad actors abusing actions for things like crypto mining.

This is a good thing in general, but it affects all pull requests, not just those that change executables. This was the fastest way to fix the issue as any code that executes could be used to start a mining process.

However, it also impacted projects such as the OctoPrint plugin repository which are primarily non-executable metadata.

This action is intended to run every 5 minutes and approve any pending workflow runs, allowing the maintainer to see all the information they need to review a PR such as linting and tests without having to wait for a build to run.

How does it work?

This action runs on a schedule, fetching any pending workflow runs and automatically approving them if some constraints are met. It requires a personal access token as shown in the GitHub API docs.

Working through the action:

Read a Personal Access Token from the token input
Create a list of allowed workflows to be automatically approved
Create a list of dangerous files and automatically add .github/workflows to it
Fetch the list of workflow runs with a status of action_required in the current repository
Filter down the list of pending workflows to those which exist in the list of allowed workflows
Remove any runs that edit a file that is in the dangerous_files list
Finally, approve any runs that are left in the list. These are runs that have an action of status_required, are listed in the workflows input and do not change any files in dangerous_files.

Common use cases

There's only one use case for this action, which is to approve safe workflows to run automatically. This typically involves running processes such as linting or static site generation.

name: Automatic Approve
on:
  schedule:
    - cron: "*/5 * * * *"
jobs:
  automatic-approve:
    name: Automatic Approve
    runs-on: ubuntu-latest
    steps:
      - name: Automatic Approve
        uses: mheap/automatic-approve-action@v1
        with:
          token: ${{ secrets.PAT }}
          workflows: "pr.yml,lint.yml"
          dangerous_files: "build.js"

Markdown Meta Action

Michael Heap — Fri, 07 May 2021 18:01:58 +0000

Fact Sheet
Author	mheap
Contributors	1
Stars	0
Repo	https://github.com/mheap/markdown-meta-action
Marketplace	https://github.com/marketplace/actions/markdown-meta

What does it do?

Content containing some YAML frontmatter is very common nowadays (in fact, you're reading a post that uses it right now).

markdown-meta allows you to read that metadata and makes it available as an output in your GitHub Actions workflow.

The frontmatter for this file is as follows:

title: Markdown Meta Action
description: Read the frontmatter from your markdown files and use the values in your workflows
slug: markdown-meta-action
date: "2021-05-07T19:01:58+01:00"
category: "Action Spotlight"
tags:
  - github-actions

Given that file we can run the following workflow that outputs the post title:

name: Get Post Meta
on: push
jobs:
  post-meta:
    name: Post Meta
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Markdown Meta
        uses: mheap/markdown-meta-action@v1
        id: meta
        with:
          file: ./_posts/markdown-meta-action.md
      - name: Output the post title
        run: echo "${{ steps.meta.outputs.title }}"

We use the id parameter to name the markdown-meta step meta and then access the data returned by it using steps.meta.outputs. Each key in the frontmatter is available:

steps.meta.outputs.title
steps.meta.outputs.description
steps.meta.outputs.slug
steps.meta.outputs.date
steps.meta.outputs.category
steps.meta.outputs.tags

How does it work?

This is a really tiny action, just 7 lines long:

It fetches the filename to read from the file input and reads the content into a string
Next, it uses the gray-matter library to extract the frontmatter
Then for each value in the frontmatter, it sets an output. The key name is run through slugify to remove special characters and whitespace
- a key with spaces becomes a-key-with-spaces
- t!tle becomes ttle
- 🚀 lift-off becomes lift-off

As it uses core.setOutput() any complex data types such as objects or arrays are JSON encoded before being output. This means that in the above example, tags will be ["github-actions"].

Common use cases

The best use case that I can think of for this action is automated blog post updates:

name: Get Post Meta
on: push
jobs:
  post-meta:
    name: Post Meta
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Get latest post
        run: |
          cd _posts
          echo "::set-output name=post_name::$(ls -rt | tail -n 1)"
        id: latest_post
      - name: Markdown Meta
        uses: mheap/markdown-meta-action@v1
        id: meta
        with:
          file: ./_posts/${{ steps.latest_post.outputs.post_name }}
      - uses: ethomson/send-tweet-action@v1
        with:
          status: "I just published! ${{ steps.meta.outputs.title }} https://michaelheap.com/${{ steps.meta.outputs.slug }}"
          consumer-key: ${{ secrets.TWITTER_CONSUMER_API_KEY }}
          consumer-secret: ${{ secrets.TWITTER_CONSUMER_API_SECRET }}
          access-token: ${{ secrets.TWITTER_ACCESS_TOKEN }}
          access-token-secret: ${{ secrets.TWITTER_ACCESS_TOKEN_SECRET }}

Generating OpenGraph images with Netlify On-demand builders

Michael Heap — Sat, 01 May 2021 16:08:35 +0000

A little while back I built an OpenGraph image generator on AWS Lambda for my Action Spotlight and TIL categories. I toyed with the idea of making them generate the images on demand, but decided that I didn’t want the potential traffic to a Lamba function and opted to pre-generate and store in S3 instead.

Then this week, I saw that Netlify On-demand builders are available in beta which solve all my problems. I don’t need to pre-generate any images, but they’re also only generated once per deploy and distributed via the Netlify CDN.

My requirements for the project were:

Each image should only be generated once (once per deploy is fine)
The function should support multiple templates for my OpenGraph image
It should be possible to pass in any data required

Overall, it was a success 🎉

If you’re looking for the code without an explanation, it’s available on GitHub

Structuring your function

Netlify functions live in the netlify/functions directory in your project. You can create files directly in there, or create a folder named after your function. I chose to create a folder as I have some additional files to package up with my JS file:

mkdir -p netlify/functions/ogtouch netlify/functions/og/og.js

I used my image generation via Netlify script as a starting point as I knew it worked to generate an image.

The first requirement is that each image should only be generated once. To enable this you use the builder decorator from @netlify/functions:

const { builder } = require("@netlify/functions");

exports.handler = builder(async function (event, context) {
  // Code
});

Make sure to install it into your project with npm install --save-dev @netlify/functions.

At this point the image will be generated on the first execution and then cached for any future requests.

The image so far looks like this:

Template support

Next, I wanted to add template support so that I didn’t have to hard-code the entire template in my function.

To do this I created a folder named templates and a template for my #til category:

mkdir -p netlify/functions/og/templatestouch netlify/functions/og/templates/til.html

To load this file I imported the fs module and read the file contents into a variable, then passed that string to page.setContent():

const fs = require("fs").promises;

exports.handler = builder(async function (event, context) {
  // ...snip...

  const template = "til";
  let htmlPage = (
    await fs.readFile(require.resolve(`./templates/${template}.html`))
  ).toString();

  const page = await browser.newPage();
  await page.setContent(htmlPage);

The contents of til.html can be anything you like. For testing purposes, I set it to the following:

<style>
  h1 { color: red }
</style>

<body>
  <h1>{title}</h1>
  <p>{description}</p>
</body>

The title and description placeholders don’t do anything yet, but we’ll use those later. For now, it’ll just render the page exactly as it is.

At this point you can deploy the function and it will render the HTML template provided as-is

Passing in data

Usually we’d use GET parameters to pass in the title and description to use in the image, but on-demand builders _ don’t provide access to HTTP headers or query parameters from incoming requests_.

This means that we have to make the parameters a part of the URI. I thought about the best way to achieve this, and decided on a URI structure that looks like the following:

/.netlify/functions/og/template=til/title=Demo Title/description=This is an example description that is a little longer to see how it works out

Everything after /og will be ignored, but it allows us to map over each segment in the URI and treat it as a key/value pair.

To build this mapping, add the following code to your function:

exports.handler = builder(async function (event, context) {
  const { template, ...params } = Object.fromEntries(
    event.path
      .split("/")
      .filter((p) => p.includes("="))
      .map(decodeURIComponent)
      .map((s) => s.split("=", 2))
  );

  // snip...
});

You’ll notice that we also read template from the path, so you can delete const template = "til"; from your function too.

Finally, we need to swap out the placeholders in the template for the values in params:

let htmlPage = (
  await fs.readFile(require.resolve(`./templates/${template}.html`))
).toString();

for (const k in params) {
  htmlPage = htmlPage.replace(`{${k}}`, params[k]);
}

After committing and deploying that, I can visit /.netlify/functions/og/template=til/title=Demo Title/description=This is an example description that is a little longer to see how it works out and see that it renders the image as expected

Conclusion

Under 45 lines of code and we have a Netlify function that generates OpenGraph images on the fly and caches them on a CDN for future requests. On-demand builders seem pretty great, and I’m looking forward to working with them more in the future.

If you're looking for the full code, it's available below or on GitHub

const chromium = require("chrome-aws-lambda");
const puppeteer = require("puppeteer-core");
const { builder } = require("@netlify/functions");
const fs = require("fs").promises;

exports.handler = builder(async function (event, context) {
  const { template, ...params } = Object.fromEntries(
    event.path
      .split("/")
      .filter((p) => p.includes("="))
      .map(decodeURIComponent)
      .map((s) => s.split("=", 2))
  );

  const browser = await puppeteer.launch({
    args: chromium.args,
    defaultViewport: { height: 630, width: 1200 },
    executablePath: await chromium.executablePath,
    headless: chromium.headless,
  });

  let htmlPage = (
    await fs.readFile(require.resolve(`./templates/${template}.html`))
  ).toString();

  for (const k in params) {
    htmlPage = htmlPage.replace(`{${k}}`, params[k]);
  }

  const page = await browser.newPage();
  await page.setContent(htmlPage);
  await page.waitForTimeout(1000);

  const buffer = await page.screenshot();

  return {
    statusCode: 200,
    headers: {
      "Content-Type": "image/png",
    },
    body: buffer.toString("base64"),
    isBase64Encoded: true,
  };
});

YAMLer Action

Michael Heap — Fri, 30 Apr 2021 09:40:13 +0000

When running your workflows, sometimes you need to read information from a file in your repository. YAMLer parses the provided YAML file and makes the values in the file available as output variables.

Fact Sheet
Author	juliojimenez
Contributors	1
Stars	4
Repo	https://github.com/juliojimenez/yamler
Marketplace	https://github.com/marketplace/actions/yamler

What does it do?

YAMLer takes each field in the provided YAML document and makes it available as an output variable. Nested resources are nested using a double underscore (__).

Take the following YAML file as an input:

summary: This is a description
contributor:
  name: Michael
  handle: mheap
projects:
  - actions-book
  - github-default-branch

These variables would be available as follows:

summary: This is a description
contributor__name: Michael
contributor__handle: mheap
contributor__projects__0: actions-book
contributor__projects__1: github-default-branch

The action works for deeply nested values and has been tested with scalars (strings, numbers, booleans), objects and arrays.

In addition to making nested properties available, the action also handles special characters.

Using the sample from the YAML.org test file, we can see that periods and parenthesis are replaced:

YAML Resources:
  YAML 1.2 (3rd Edition): http://yaml.org/spec/1.2/spec.html
  YAML 1.1 (2nd Edition): http://yaml.org/spec/1.1/
  YAML 1.0 (1st Edition): http://yaml.org/spec/1.0/
  YAML Issues Page: https://github.com/yaml/yaml/issues

Is made available as:

yaml_resources__yaml_1_2_3rd_edition: http://yaml.org/spec/1.2/spec.html
yaml_resources__yaml_1_1_2nd_edition: http://yaml.org/spec/1.1/
yaml_resources__yaml_1_0_1st_edition: http://yaml.org/spec/1.0/
yaml_resources__yaml_issues_page: https://github.com/yaml/yaml/issues

Notice how the periods are replaced with underscores, and the parenthesis are removed? Let’s take a look at the rules for replacement in the source!

How does it work?

The entire action is available in a single file which makes it easy to understand what’s going on.

The entry point reads the file provided in the yaml-file input and passes it to traverseObject to start building the output. This method iterates over the keys in the provided YAML file and decides how to process each entry.

If the value is a scalar (string, number or boolean) we’re at the end of a nested value (the leaf) and it’s time to add an output
If the value is an object or an array, we keep track of all the keys we saw whilst traversing to this depth and then call either traverseArray or traverseObject as required.
- Calling traverseArray loops over all values in the array and emits a new value if we detect a scalar
- Calling traverseObject is a recursive call which starts this set of bullet points again with the child value passed in as the argument

Whilst processing keys, the action applies the following rules:

The last two substitutions seem strange to me, but I guess the author had a use case where it made sense.

As mentioned earlier, the action has a single required input which is the path to the YAML file to read. It runs using the node12 runtime thanks to a compiled version of the action being available in the build directory.

Finally, the action uses semantic versioning. It’s currently at v0 whilst it’s in beta, and uses the release-github-actions action to automatically build and commit an updated build/index.js file when a release is created. Then the major and minor tags are updated to point at the new release commit.

GitHub Slug Action

Michael Heap — Fri, 23 Apr 2021 18:41:27 +0000

We're looking at a different kind of action today! This action doesn't actually do anything. Instead, it makes more information available in your workflow and the environment for other actions to use.

Fact Sheet
Author	rlespinasse
Contributors	9
Stars	106
Repo	https://github.com/rlespinasse/github-slug-action
Marketplace	https://github.com/marketplace/actions/github-slug-action

What does it do?

The github-slug-ref action provides information that’s commonly needed in workflows in a useful format. By default, variables such as GITHUB_REF are in the format refs/heads/main or refs/tags/v1.0.0. This catches people out as they’re not used to thinking about if what they’re referencing is a branch or a tag, and they’re definitely not used to the refs prefix.

Once the rlespinasse/github-slug-action action has been included in your workflow, some new environment variables will be available. To include it, add a uses entry within your steps key:

name: Slug Demo
on: push
jobs:
  demo:
    runs-on: ubuntu-latest
    steps:
      - uses: rlespinasse/github-slug-action@v3.x

If we think about GITHUB_REF from above, GITHUB_REF_SLUG is available after including this action. If GITHUB_REF was refs/heads/main, GITHUB_REF_SLUG will be main. If the input was refs/tags/v1.0.0, GITHUB_REF_SLUG will be v1.0.0. If you’d like to see a full list of transformations, see the slug variables docs. If you’re looking for slugs that are safe to use in a URL, you might be interested in the URL slug variables too.

Another feature of the action is short variables. In addition to the full sha (available in GITHUB_SHA), this action will make an 8 character prefix available in GITHUB_SHA_SHORT. This can be useful is you need a semi-unique identifier and want a shorter key than the full sha.

In addition to manipulating the existing environment variables, the action also makes some of the information from github.event available as an environment variable. For example, github.event.pull_request.head.sha is available as GITHUB_EVENT_PULL_REQUEST_HEAD_SHA_SHORT. This is useful when you’re writing bash scripts and can’t parse event.json.

How does it work?

Looking at the source code, this action is a large collection of regular expressions. It handles cases such as:

If you want to see all of the variables it’s creating in the source code, they’re all available in main.ts.

The action itself is compiled and pushed to the repo so that people can use it directly. This isn't a pattern I like personally (I prefer to use the build and tag action) but it means that consumers can use the javascript runtime so it's a reasonable trade off.

Create or Update PR Action

Michael Heap — Fri, 16 Apr 2021 16:45:23 +0000

Following on from our theme of actions to commit and push changes, today’s action can commit and push any local edits and raise a pull request automatically.

Fact Sheet
Author	gr2m
Contributors	8
Stars	31
Repo	https://github.com/gr2m/create-or-update-pull-request-action
Marketplace	https://github.com/marketplace/actions/create-or-update-pull-request

What does it do?

A GitHub Action to create or update a pull request based on local changes

You can use the action to add, commit and push changes to a remote branch and create a pull request for those changes automatically. It can add all your files in a single commit, add multiple commits to a single PR and automatically add labels and assignees to any pull requests that it raises.

Oh, and it’s built by Gregor which means I instantly trust it.

How does it work?

If there any uncommitted changes, files matching the pattern provided in the path input supplied are added and committed. You can customise the commit with the commit-message and author inputs
If there are any local commits (created by step 1, or by any other means) the action pushes changes to a remote branch with the name specified in the branch input
Search for any open pull requests with branch as the HEAD commit using the search query head:${inputs.branch} type:pr is:open repo:${process.env.GITHUB_REPOSITORY}
If there is an existing pull request, the action stops execution. Otherwise, a new pull request is created with the title and body inputs provided. Any labels and assignees provided as inputs are automatically added

Using the search API to check if there is already an open pull request for a branch is a fantastic solution. When I needed to do the same, I uses the pulls.list endpoint and passed in the head parameter like so:

let pr = ( await tools.github.pulls.list({ owner, repo, head: `${owner}:${automationBranchName}`, })).data[0];if (!pr) { // Create a PR}

What I find interesting about this action is that it only uses the GitHub API for actions that it cannot perform using the git binary. There is a runShellCommand function that is used to run git fetch, git commit etc on the runner directly. When automating updates I’ve used the GitHub API to get and modify file contents to remove the requirement to use actions/checkout as part of your workflow, but in this context you’re likely to have a workspace so it makes sense to interact directly with the files.

Another interesting choice is that the action does not configure a remote or add authentication details, instead opting to specify both values directly in the git commit like so:

await runShellCommand( `git push -f https://x-access-token:${process.env.GITHUB_TOKEN}@github.com/${process.env.GITHUB_REPOSITORY}.git HEAD:refs/heads/${inputs.branch}`);

There’s nothing in the commit history to explain why, but if I had to hazard a guess it’s due to the fact that other processes can interact with git config files, so by passing the details directly to the command it reduces the chances of anything interfering.

Finally, this action provides an example of how to provide lists of values in inputs. The action uses a comma-separated list of values for labels and assignees to provide multiple values. There still isn’t consensus how to provide multiple values (some actions provide a JSON list and deserialise), but this is another vote for the “comma-separated” camp.

Common use cases

This action is most useful when you’ve got a task running on a schedule that fetches and commits updated data to the repo. If there are no changes, no commit or pull request will be created.

The README itself shows that it’s being used to keep track of Chinese Starbucks stores, download JSON schema updates periodically and even by the Node project itself to keep the license file up to date.

If you’re interested in learning more about this pattern, there’s a great post by Simon Willison on git scraping as a concept.

GitHub Push Action

Michael Heap — Fri, 26 Mar 2021 19:59:46 +0000

Today we’re looking at ad-m/github-push-action, the third and final action related to pushing changes made during a GitHub Actions workflow run back to a repo.

What does it do?

Unlike git-auto-commit-action and add-and-push, github-push-action doesn’t handle committing files for you. It expects your workflow to add and commit any files you need and handles the act of pushing changes to GitHub.

You might be thinking that this seems like an odd action to build; surely it’s as simple as running git push and it works? Unfortunately not! The repository provided in your workspace doesn’t have permission to push changes back so you need to configure your repo to use the GITHUB_TOKEN provided in order to have write permission.

How does it work?

This action is an interesting one as it uses both javascript and bash components to get the job done. start.js is the main entry point, which allows the action to run start.sh on Linux, MacOS and Windows runners.

Let’s take a look at start.js first as it’s the main entry point:

The action accepts both branch and repository as inputs.
If repository isn’t provided it defaults to GITHUB_REPOSITORY in the environment. If it is provided, that will be used as the destination repository, allowing your workflow to push to other repositories.
If branch is provided it is used as-is. If it is not provided the script uses the GitHub API to fetch the default branch for the repo and uses that as the input value
Finally, it executes start.sh ensuring that both INPUT_BRANCH and INPUT_REPOSITORY have values

What’s interesting to note here is that start.js does not have any dependencies. It uses the http module for making HTTP requests and the child_process module to executestart.sh. actions/exec is typically used for this use case, but github-push-action does not use any dependencies so that there is no build step required for the JS action.

Now, on to start.sh:

We see some new inputs that have defaults set in the script

INPUT_FORCE (default false) which will run git push --force
INPUT_TAGS (default false) which will run git push --tags
INPUT_DIRECTORY (default ., the current directory) which controls which directory the push is run from
REPOSITORY, which is set to INPUT_REPOSITORY or GITHUB_REPOSITORY. This is a duplication of the logic in start.js
- The GITHUB_TOKEN secret is required to push to the repo, so we check that it’s been set as INPUT_GITHUB_TOKEN
- If INPUT_FORCE is true then add --force to the push options
- If INPUT_TAGS is set then add --tags to the push options
- Configure the remote URL using the user:password@github.com format
- Push the current HEAD commit to INPUT_BRANCH

Common use cases

As with the last post, this action is most useful for committing back changed files such as style fixes or build artefacts.

Run eslint and commit back:

name: Lint source code
on: push

jobs:
  run:
    name: Lint with ESLint
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v2

      - name: Set up Node.js
        uses: actions/setup-node@v1
        with:
          node-version: 12.x

      - name: Install dependencies
        run: npm install

      - name: Update source code
        run: eslint "src/**" --fix

      - name: Commit files
        run: |
          git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git config --local user.name "github-actions[bot]"
          git add src
          git commit -m "ESLint fixes"

      - name: Push changes
        uses: ad-m/github-push-action@master
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          branch: ${{ github.ref }}

Or build your project and commit back the files:

name: Automatic Compile
on: push

jobs:
  run:
    name: Compile
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v2

      - name: Set up Node.js
        uses: actions/setup-node@v1
        with:
          node-version: 12.x

      - name: Install dependencies
        run: npm install

      - name: Compile
        run: npm run build

      - name: Commit files
        run: |
          git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git config --local user.name "github-actions[bot]"
          git add lib
          git commit -m "Built files"

      - name: Push changes
        uses: ad-m/github-push-action@master
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          branch: ${{ github.ref }}

Useful links

Add and Commit action

Michael Heap — Fri, 19 Mar 2021 09:09:39 +0000

Add and Commit is the second (of three!) actions that can be used to push your changes to a repo during a GitHub Actions workflow.

What does it do?

Much like the last spotlight post, today’s action is focused on adding and committing files to a repo. The README does a good job explaining how it’s different to git-auto-commit-action:

This is heavily inspired by git-auto-commit-action (by Stefan Zweifel): that action automatically detects changed files and commits them. While this is useful for most situations, this doesn’t commit untracked files and can sometimes commit unintended changes (such as package-lock.json or similar, that may have happened during previous steps).

It’s also evolved from git-auto-commit and supports pulling changes if required before a push, removing files with git rm and makes features such as signoff an input rather than making you specify --signoff as a commit_option

How does it work?

add-and-commit is implemented in TypeScript rather than bash and is a single 388 line file named main.ts. It uses simple-git to interact with the underlying git repo and provides a compiled version of the action that includes all dependencies.

main.ts itself is reasonable easy to follow:

Add any files that match the pattern provided in add
Remove any files if remove was provided
If there are no staged files, the action stops execution
Otherwise it populates .git/config using the author_email and author_username provided
As GitHub Actions does a shallow clone, the action then runs git fetch to get all branches
This isn’t documented in the README, but the action then switches to a branch with the name specified in the branch input. This defaults to the branch that triggered the workflow run
Then it ensures that the branch is up to date. You can choose NO-PULL, --no-rebase, --no-ff or --rebase depending on which strategy you prefer
As the working branch may have changed, it then re-adds any changed files
Before creating a commit using the author_name provided and the --signoff flag if the signoff input was set
If the tag input was provided, the action also creates a tag named after the tag input
If the push input was set to true, it runs git push origin <branch> --set-upstream
If the push input provided is a string it runs git push <input string>
Finally, if a tag was created it runs git push --tags. This part is interesting as it deletes a remote tag and re-pushes when an error is encountered

There are a couple of other interesting things in the action to dig into.

One of the big questions in the Actions world is how to parse structured input. add-and-commit attempts to parse inputs that can be arrays as both JSON and YAML before falling back to treating it as a simple string.

The action also handles setting defaults in the code rather than using the default field in action.yml like git-auto-commit-action does.

Common use cases

Automatically committing changed files can be useful in a couple of situations. The example shown in the docs is to run eslint --fix to fix code styling before pushing the changes back to the repo:

name: Lint source code
on: push

jobs:
  run:
    name: Lint with ESLint
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v2

      - name: Set up Node.js
        uses: actions/setup-node@v1
        with:
          node-version: 12.x

      - name: Install dependencies
        run: npm install

      - name: Update source code
        run: eslint "src/**" --fix

      - name: Commit changes
        uses: EndBug/add-and-commit@v7
        with:
          author_name: Your Name
          author_email: mail@example.com
          message: "Your commit message"
          add: "*.js"

Another idea is to make sure that your lib folder for your action (like the one used in add-and-commit) is always compiled as expected on push:

name: Automatic Compile
on: push

jobs:
  run:
    name: Compile
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v2

      - name: Set up Node.js
        uses: actions/setup-node@v1
        with:
          node-version: 12.x

      - name: Install dependencies
        run: npm install

      - name: Compile
        run: npx ncc -o lib

      - name: Commit changes
        uses: EndBug/add-and-commit@v7
        with:
          author_name: Your Name
          author_email: mail@example.com
          message: "Your commit message"
          add: "lib"

DEV Community: Michael Heap

The ultimate guide to GitHub Actions authentication

Working with GITHUB_TOKEN

Token Permissions

Security

When GITHUB_TOKEN isn’t enough

Bonus: It’s a GitHub App under the hood!

Authentication options

Personal Access Token (PAT)

Creating a PAT

Benefits

Downsides

GitHub Apps

Creating an application

Using applications in a GitHub workflow

Benefits

Downsides

So which is the best?

8 Common Request Transformation Policies

Overview of Core Concepts

Kong Gateway

Request Transformer Plugin

Mockbin

Our Walkthrough Approach

Set Up Mockbin Endpoint

Set Up Kong Gateway

Common Request Transformations

1. Copy API key from query string to header

2. Remove query string value

3. Move API key from query string to header

4. Add version number to query string

5. Modify header token to Bearer Auth

6. Move JWT from header (Bearer Auth) to body

7. Sanitize body

8. Change HTTP method

Conclusion

Ready for Advanced Request Transformations?

20 Lines of JavaScript to Create a Kong Gateway Plugin

Bootstrapping Your Development Environment

Creating Your First Plugin

Enable the Plugin

Making a Request

Making It Configurable

Conclusion

Dump Context Action

What does it do?

How does it work?

Common use cases

Auto-approve Workflow Action

What does it do?

How does it work?

Common use cases

Markdown Meta Action

What does it do?

How does it work?

Common use cases

Generating OpenGraph images with Netlify On-demand builders

Structuring your function

Template support

Passing in data

Conclusion

YAMLer Action

What does it do?

How does it work?

GitHub Slug Action

What does it do?

How does it work?

Create or Update PR Action

What does it do?

How does it work?

Common use cases

GitHub Push Action

What does it do?

How does it work?

Common use cases

Useful links

Add and Commit action

What does it do?

How does it work?

Common use cases

Working with `GITHUB_TOKEN`

When `GITHUB_TOKEN` isn’t enough