DEV Community: Shunsuke Suzuki

Short-lived GitHub Access Token for secure local development by ghtkn

Shunsuke Suzuki — Sat, 13 Sep 2025 23:56:36 +0000

Are you still relying on long-lived GitHub tokens—like Personal Access Tokens (PATs) or OAuth tokens used with the GitHub CLI—stored on your local machine?
If so, you might be exposing yourself to unnecessary risks.
Enter ghtkn: a tool built to dramatically reduce those risks by using short-lived, secure tokens via GitHub Apps.

The Problem with Traditional Tokens

Many developers use PATs or GitHub CLI tokens that:

Remain dangerous if leaked
- Live indefinitely or for many months
- Have overly broad permissions
Are hard to rotate regularly

Any leak or compromise can lead to serious, lasting damage.

How ghtkn Solves This

ghtkn is designed to tackle these issues by introducing a more secure, manageable workflow:

Short-lived tokens — tokens expire after 8 hours, so leaks are less damaging.
No secrets required — you only need the GitHub App Client ID, which is not sensitive. No Private Key / Client Secret to guard.
User-attributed actions — actions are done as you, not under a generic app identity.
Automatic management — tokens are stored and reused securely via OS secret managers (Windows Credential Manager, macOS Keychain, GNOME Keyring). You don’t have to juggle them manually.

Getting Started

Here’s how you set up ghtkn:

Install ghtkn
Create a GitHub App with Device Flow enabled. Don’t bother with private keys or secrets. You only need a Client ID.
Initialize configuration via ghtkn init, to create a ghtkn.yaml, where you define what GitHub Apps you’ll use.
Use ghtkn get to generate your 8-hour user access token (via Device Flow). Approve via browser, use the code shown in terminal.

Extras & Advanced Use

Who Should Use ghtkn

ghtkn is especially compelling for:

Developers who want to minimize their risk exposure from token leaks.
Anyone who uses GitHub CLI or other tools locally and needs safe, manageable authentication.
Teams where multiple people or organizations share repos but want fine control over permissions.
Organizations wanting to standardize token policies internally.

Why ghtkn Might Be a Game Changer

By shifting away from long-lived, broad-scope tokens to short-lived, narrowly scoped user-attributed tokens, ghtkn helps you follow security best practices effortlessly.
It sidesteps many of the most common security pitfalls—like stale credentials or broad permissions—while integrating nicely into existing workflows.

If you care at all about securing your GitHub workflows—and especially if you work in teams or public projects—ghtkn is worth a look.
Give it a try, and make your access tokens safer by default.

https://github.com/suzuki-shunsuke/ghtkn

How to pin GitHub Actions to a full commit length SHA across all repositories in your organization

Shunsuke Suzuki — Mon, 17 Mar 2025 07:30:59 +0000

Last weekend, the popular GitHub Action tj-actions/changed-files was compromised.

The issue was solved, but similar incidents could happen again in the future.
To prevent such issues, pinning action versions by full commit hash is recommended.

👉 GitHub Docs:

Pin actions to a full length commit SHA
Pinning an action to a full length commit SHA is currently the only way to use an action as an immutable release.
Pinning to a particular SHA helps mitigate the risk of a bad actor adding a backdoor to the action's repository, as they would need to generate a SHA-1 collision for a valid Git object payload.
When selecting a SHA, you should verify it is from the action's repository and not a repository fork.

This post introduces how to pin GitHub Action versions across all repositories in your organization.

pinact

You can pin GitHub Actions using a CLI tool called pinact.
It's so easy to use:

pinact run

If you want to fix composite actions and documents, you can specify file paths.

pinact run action.yaml README.md

You can also update actions using the -u option:

pinact run -u

For more details, check out the pinact repository.

multi-gitter

You can apply pinact to all repositories using multi-gitter.

Create the following files:

config.yaml
run.sh
main.sh

config.yaml:

e.g.

git-type: cmd
branch: pin-github-actions
skip-forks: true
org:
  - szksh-lab # Update with your organization
# repo:
#   - szksh-lab/test-1 # For test
labels:
  - pin-github-actions
pr-title: "ci: Pin versions of GitHub Actions to full commit hash"
pr-body: |
  ## What?

  This PR pins versions of GitHub Actions to full commit hash by pinact.
  In general, this PR doesn't change the behavior of the workflows, so you can merge this safely.

  ## Why?

  Last weekend, the popular GitHub Action tj-actions/changed-files action was compromised.

  - https://semgrep.dev/blog/2025/popular-github-action-tj-actionschanged-files-is-compromised/
  - https://www.stepsecurity.io/blog/harden-runner-detection-tj-actions-changed-files-action-is-compromised

  All tags were tampered and they pointed to a revision with malicious code.

  The issue was solved, but similar issues could happen again.
  To avoid this kind of issues, we should pin versions of GitHub Actions.
  This is a common practice of GitHub Actions.

  https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#using-third-party-actions

  > Pin actions to a full length commit SHA
  > Pinning an action to a full length commit SHA is currently the only way to use an action as an immutable release.
  > Pinning to a particular SHA helps mitigate the risk of a bad actor adding a backdoor to the action's repository, as they would need to generate a SHA-1 collision for a valid Git object payload.
  > When selecting a SHA, you should verify it is from the action's repository and not a repository fork.

  ## How was this pull request created?

  This pull request was created by [pinact](https://github.com/suzuki-shunsuke/pinact) and [multi-gitter](https://github.com/lindell/multi-gitter).

  ## Due Date

  Please merge this pull request by 2025-03-31.
  If it's difficult, please ask at the Slack channel #sre.

  ## Contact

  If you have any question, please ask at the Slack channel #sre.

run.sh:

#!/usr/bin/env bash

set -eu

export GITHUB_TOKEN=$(gh auth token)

multi-gitter run ./main.sh \
    --config config.yaml

main.sh:

#!/usr/bin/env bash

set -eu

pinact run

Make main.sh executable:

chmod +x main.sh

Before running it across all repositories, test it on one repository:

config.yaml:

# org:
#   - szksh-lab
repo:
  - szksh-lab/test-1 # Please fix

Run run.sh to create a pull request:

bash run.sh

Once confirmed, apply it to all repositories.

bash run.sh

Example Pull Request: https://github.com/szksh-lab/test-1/pull/23

For more details of multi-gitter, please see the multi-gitter repository.

Continuous Updates

You can update actions by Dependabot or Renovate.

Dependabot:

https://github.blog/news-insights/product-news/dependabot-now-updates-your-actions-workflows/

Renovate:

helpers:pinGitHubActionDigestsToSemver

You can also run pinact in CI using pinact-action.

Conclusion

To improve security, you should pin GitHub Action versions to a full-length commit hash.
You can pin GitHub Actions across all repositories in your GitHub Organizations using pinact and multi-gitter.

Fix Code Via GitHub Actions By Verified Commits

Shunsuke Suzuki — Sat, 15 Feb 2025 03:45:50 +0000

This post introduces a GitHub Action to fix code by verified commits.

https://github.com/suzuki-shunsuke/commit-action

It's useful to fix pull requests via GitHub Actions.
Or it's also useful to fix code on a base branch after merging pull requests.
For instance, you can format code, and generate document from source codes automatically.

To achieve this, you need to create and push commits in CI.
commit-action is an action for this.

Why Use commit-action?

Unlike similar actions, commit-action creates and pushes commits by GitHub API instead of Git commands.
So you can create verified commits using GitHub Actions token ${{github.token}} or a GitHub App installation access token.

Commit signing is so important for security.

https://docs.github.com/en/authentication/managing-commit-signature-verification

To create verified commits using Git, a GPG key or SSH key is required.
It's bothersome to manage GPG keys and SSH keys properly for automation, so it's awesome that commit-action can create verified commits without them.

How To Use

commit-action is so easy to use.
All inputs are optional.

You only need to run commit-action after fixing code in workflows.
Then it creates and pushes a commit to a remote branch.

name: Example
on:
  pull_request: {}
jobs:
  example:
    runs-on: ubuntu-24.04
    steps:
      - name: Checkout
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
          persist-credentials: false

      # Fix files
      # ...

      - name: Push changes to the remote branch
        uses: suzuki-shunsuke/commit-action@db754eb4adb44fb5aee5879a3bd08785efec198e # v0.0.4

commit-action fails if it pushes a commit.
If no change is pushed, commit-action does nothing and exits successfully.

By default, commit-action pushes a commit to ${GITHUB_HEAD_REF:-${GITHUB_REF_NAME}} in $GITHUB_REPOSITORY, but you can change them.
${{github.token}} is used by default, but we don't recommend it because ${{github.token}} doesn't trigger a new workflow run.
We recommend GitHub App installation access tokens.
You can create a GitHub App installation access token and pass it to commit-action yourself, but you can also pass a pair of GitHub App ID and private key.
Then commit-action creates a GitHub App installation access token with minimum repositories and permissions.

- uses: suzuki-shunsuke/commit-action@db754eb4adb44fb5aee5879a3bd08785efec198e # v0.0.4
  with:
    app_id: ${{secrets.APP_ID}}
    app_private_key: ${{secrets.APP_PRIVATE_KEY}}

commit-action commits all created, updated, and deleted files by default, but you can also commit only specific files.
And you can also change the commit message.

- uses: suzuki-shunsuke/commit-action@db754eb4adb44fb5aee5879a3bd08785efec198e # v0.0.4
  with:
    commit_message: "style: format code"
    files: |
      README.md
      package-lock.json

Refactor Terraform Resource Names By One Command

Shunsuke Suzuki — Mon, 23 Dec 2024 14:55:15 +0000

This post introduces tfmv, a CLI tool that simplifies refactoring Terraform resource names with just one command.
For instance, to replace hyphens (-) with underscores (_), you can run:

tfmv -r '-/_'

Then resource are renamed:

-resource "github_repository" "example-1" {
+resource "github_repository" "example_1" {
   name = "example-1"
 }

 data "github_branch" "example" {
-  repository = github_repository.example-1.name
+  repository = github_repository.example_1.name
   branch     = "example"
 }

And a moved block is created:

moved {
  from = github_repository.example-1
  to   = github_repository.example_1
}

Features of tfmv

Rename Terraform Resources, Data Sources, and Modules
Modify resource references
Generate moved blocks
Easy to install
- tfmv is a single binary written in Go. You only need to put tfmv into $PATH
- Cross platform: Windows, macOS, and Linux
Flexible Resource Filtering with Regular Expressions
- Use --include <regexp> to rename only resources matching a specific pattern
- Use --exclude <regexp> to skip renaming for resources matching a specific pattern
Support for Multiple Renaming Methods
- Fixed String Replacement: Use --replace (-r) to specify straightforward string substitutions
- Regular Expression: Use --regexp to perform pattern-based renaming
- Jsonnet: Use --jsonnet (-j) for advanced, programmatically controlled renaming logic

These features make tfmv a powerful and flexible tool for refactoring Terraform configurations.

Quick start

Install tfmv according to the guide
Create main.tf and make a backup of it as main.tf.bak:

echo 'resource "github_repository" "example-1" {
  name = "example-1"
}

data "github_branch" "example-2" {
  repository = github_repository.example-1.name
  branch     = "example"
}' > main.tf
cp main.tf main.tf.bak

Run tfmv to replace - with _:

tfmv -r '-/_'

Then check the result:

diff main.tf main.tf.bak

1c1
< resource "github_repository" "example_1" {
---
> resource "github_repository" "example-1" {
5,6c5,6
< data "github_branch" "example_2" {
<   repository = github_repository.example_1.name
---
> data "github_branch" "example-2" {
>   repository = github_repository.example-1.name

moved.tf:

moved {
  from = github_repository.example-1
  to   = github_repository.example_1
}

Congratulations! 🎉 You’ve successfully refactored Terraform resource names with just one command.

Conclusion

In this post I introduced tfmv, a powerful Terraform refactoring tool.
Using tfmv, you can efficiently rename Terraform resources and generate moved blocks.
For more details, check out the README.md on GitHub.

Lock Mechanism on GitHub Actions

Shunsuke Suzuki — Thu, 14 Nov 2024 13:41:31 +0000

Sometimes, a lock mechanism is useful in CI workflows, like when you need to prevent simultaneous deployments or block deployments during maintenance.
In this post, I’ll introduce a GitHub Action for implementing a lock mechanism.

https://github.com/suzuki-shunsuke/lock-action

Features

No dependencies on external services like AWS or GCP
No reliance on shell or external commands such as git
Achieves locking using GitHub branches
Manage branches via GitHub API without git command. You don't have to checkout repositories by actions/checkout
Records lock and unlock histories
Supports waiting until a lock is released

How to Use

This action requires two inputs: key and mode.

key: an explicit identifier for the lock, which you can adjust by service and environment.
mode: the action’s operational mode, which can be one of these:
- lock: Acquires a lock
- unlock: Releases a lock
- check: Checks the lock status

mode: lock:

steps:
  - name: Acquire a lock for a key `foo` before deploying an application
    uses: suzuki-shunsuke/lock-action@latest
    with:
      mode: lock
      key: foo
  - run: bash deploy.sh foo

mode: unlock:

steps:
  - name: Release a lock
    uses: suzuki-shunsuke/lock-action@latest
    with:
      mode: unlock
      key: foo

mode: check:

steps:
  - name: Check if a key is being locked
    id: check
    uses: suzuki-shunsuke/lock-action@latest
    with:
      mode: check
      key: foo
  - run: bash deploy.sh foo
    if: steps.check.outputs.already_locked != 'true'

You can also use post_unlock: "true" to release a lock automatically in a post step.

  - uses: suzuki-shunsuke/lock-action@latest
    with:
      mode: lock
      key: foo
      post_unlock: "true"

By default, mode: lock will fail if the key is already locked.
Set ignore_already_locked_error: "true" to avoid this.

- uses: suzuki-shunsuke/lock-action@latest
  with:
    key: foo
    mode: lock
    ignore_already_locked_error: "true"

To force mode: check to fail if a key is locked, use fail_if_locked: "true".

# This step fails if the key `foo` is being locked.
- uses: suzuki-shunsuke/lock-action@latest
  with:
    mode: check
    key: foo
    fail_if_locked: "true"

To wait until a lock is released, use max_wait_seconds and wait_interval_seconds.

- uses: suzuki-shunsuke/lock-action@latest
  with:
    mode: lock
    key: default
    # Try to acquire a lock every 10 seconds until acquiring a lock or 60 seconds pass.
    max_wait_seconds: "60"
    wait_interval_seconds: "10"

These inputs are also available for mode: check.

- uses: suzuki-shunsuke/lock-action@latest
  with:
    mode: check
    key: default
    # Check a lock every 5 seconds until the lock is released or 60 seconds pass
    max_wait_seconds: "30"
    wait_interval_seconds: "5"

How It Works

This action manages locks by creating and updating GitHub branches.
Each lock’s state is tracked in the commit message of a branch named ${{inputs.key_prefix}}${{inputs.key}} (default prefix: lock__, which can be customized with key_prefix).

Commit message format:

unlock by suzuki-shunsuke: test
{
  "message": "test",
  "state": "unlock",
  "actor": "suzuki-shunsuke",
  "github_actions_workflow_run_url": "https://github.com/suzuki-shunsuke/test-github-action/actions/runs/11545637203?pr=237",
  "pull_request_number": 237
}

From these commit messages, you can see when and who (actor, workflow run, pull request number) acquired or released the lock.

Example links:

Conclusion

In this post, I introduced my GitHub Action for a lock mechanism. For more details, please visit the repository:

https://github.com/suzuki-shunsuke/lock-action

aqua Now Supports Node.js

Shunsuke Suzuki — Sun, 01 Sep 2024 08:05:27 +0000

aqua is a CLI version manager written in Go.

https://aquaproj.github.io/

As of August 24, 2024, aqua now supports Node.js!

https://aquaproj.github.io/docs/reference/nodejs-support/

How to Manage Node.js Using aqua

You'll need aqua-registry v4.216.0 or later.
To get started, add nodejs/node to your aqua.yaml file.

aqua g -i nodejs/node
aqua i -l

Then you can run commands such as node and npm.

node -v
npm -v

Configure npm `preset` config

To install tools globally using npm i -g, you need to configure the npm preset config and update the PATH environment variable.

export NPM_CONFIG_PREFIX=${XDG_DATA_HOME:-$HOME/.local/share}/npm-global # Feel free to change this path
export PATH=$NPM_CONFIG_PREFIX/bin:$PATH

Once configured, you can install tools by npm i -g.

npm i -g zx
zx -v

Even if you change the version of Node.js, you'll still be able to execute tools installed by npm i -g.

aqua up node@v20.16.0
zx -v

Why do we need to configure npm `preset` config?

For more details, check out the related issue.

By default, npm i -g installs tools in the same directory as Node.js, meaning the installation path depends on the Node.js version.
Currently, aqua can't dynamically update the PATH environment variable.
We've considered dynamically updating the PATH environment variable for Node.js, but this feature is highly dependent on the environment (shell), making it difficult to maintain.

Bash: $PROMPT_COMMAND
Zsh: hook function
Fish: ???
Powershell: ???
etc

We prefer not to implement such a feature.

Moreover, dynamically updating the environment variable works only on interactive shells, not in shell scripts.
For example, changing the Node.js version within a shell script wouldn’t update the PATH variable correctly.

Therefore, we decided to fix the installation directory using npm preset config rather than updating dynamically the PATH environment variable.
This approach has several benefits.

It doesn't depend on the environment (shell)
It doesn't require adding any feature to aqua itself

Gathering GitHub Issues and Pull Requests Across Repositories into GitHub Projects Automatically

Shunsuke Suzuki — Sun, 04 Aug 2024 13:21:45 +0000

This post explains how to gather GitHub Issues and Pull Requests across GitHub repositories into GitHub Projects automatically.
This post is based on my post written in Japanese. 自分が管理する全 OSS の Issue や Pull Request を 1 つの GitHub Project に集約

Managing GitHub Issues and Pull Requests across multiple repositories can be challenging.
By adding all of them to GitHub Projects, you can manage them in one place.
To do this, you need to add them to GitHub Projects somehow.

There are several ways to add them to GitHub Projects automatically.

Using the built-in automations
Running GitHub Actions by issues and pull requests' opened events
(Recommendation) Running GitHub Actions by schedule event to search issues and pull requests and add them to projects

I recommend the third approach and will describe it in detail.

1. Using the built-in automations

GitHub provides the built-in automations, but this feature has several limitations.

You have to configure workflows for each repository, which is cumbersome

You can create only five auto-add workflows. To create more workflows, you have to upgrade your plan

2. Running GitHub Actions by issues and pull requests' opened events

You can add issues and pull requests to projects using GitHub Actions.

https://docs.github.com/en/issues/planning-and-tracking-with-projects/automating-your-project/automating-projects-using-actions

GitHub provides an official action for this.

https://github.com/marketplace/actions/add-to-github-projects

However, I don't recommend this approach because you have to add workflows for each repository, which makes it hard to maintain.

3. Running GitHub Actions by schedule event to search issues and pull requests and add them to projects

You can run GitHub Actions by schedule event to search issues and pull requests and add them to projects.
The benefit of this approach is that you only have to maintain a single workflow.

I've developed a command-line tool for this purpose.

https://github.com/suzuki-shunsuke/ghproj

This tool performs the following tasks.

Reads a configuration file
Searches issues and pull requests using GitHub GraphQL API
Excludes some issues and pull requests based on an expression
Adds issues and pull requests to projects

ghproj init # Scaffold a configuration file ghproj.yaml
ghproj add [-config (-c) <configuration file path>] # Add issues and pull requests to GitHub Projects

Here is an example of a configuration file ghproj.yaml.

entries:
  # query: The query of GitHub GraphQL API to search issues and pull requests which are added to GitHub Projects
  - query: |
      is:open
      -project:suzuki-shunsuke/5
      archived:false
      owner:suzuki-shunsuke
      owner:aquaproj
      owner:lintnet
      is:public
    # expr: An expression filtering the search result.
    # The expression is evaluated using github.com/expr-lang/expr.
    # The expression is evaluated per item in the search result.
    # The evaluation result must be a boolean.
    # If the result is false, the item is excluded.
    # expr is optional. If expr isn't set, all search results are used.
    expr: |
      (! Item.Repo.IsFork) &&
      (Item.Title != "Dependency Dashboard")
    # project_id: GitHub Project id where issues and pull requests are added.
    # You can get the id by GitHub CLI's gh project list command.
    project_id: PVT_kwHOAMtMJ84AQCf4

For more information on the query syntax, please see the GitHub documentation:

https://docs.github.com/en/issues/tracking-your-work-with-issues/filtering-and-searching-issues-and-pull-requests#about-search-terms

You can test queries using the search box on GitHub: https://github.com

GitHub Access Token

A GitHub access token is needed to add issues and pull requests to projects.
There are several types of GitHub access tokens.

GitHub Actions token: This token doesn't support adding items to GitHub Projects
GitHub App: This token doesn't support managing GitHub Users' Projects
OAuth App (GitHub CLI)
Personal Access Token (PAT)
- classic PAT: This token is insecure because you can't restrict permissions and scopes flexibly
- fine-grained PAT: This token doesn't support GitHub Projects

Fine-grained PAT doesn't support GitHub Projects.

https://github.com/orgs/community/discussions/36441

There are also some APIs that do not yet support the fine-grained permission model, that we'll be adding support for in time:

Packages

Projects

Notifications

So there are two options.

Pull together issues and pull requests to GitHub Users' Projects using a classic PAT
(Recommendation) Pull together issues and pull requests to GitHub Organizations' Projects using a GitHub App

GitHub App is more secure than classic PAT, so I recommend the second option.
Even if you want to manage your personal issues and pull requests, I recommend creating a GitHub Organization and adopting the second option.

1. Using a classic PAT

You should configure the expiration date.
The required scopes are read:org and project.

2. Using a GitHub App

Create a GitHub App

The required permissions are

Repository permissions: metadata: read-only
Organization permissions: Projects: Read and write

Install the GitHub App into a repository where GitHub Actions is run
Create an installation access token using an action such as tibdex/github-app-token or actions/create-github-app-token

To create an installation token, you have to install the GitHub App to repositories.
To do this, you have to grant any Repository permissions to the GitHub App.

If you want to manage issues and pull requests of private repositories, you have to grant Pull Requests: read-only and Issues: read-only permissions to the GitHub App and install it to private repositories.

Archiving GitHub Projects Items Based on Conditions

You can add only 1,200 items in each project.
To add more items to a project, you have to archive existing items.
GitHub Project supports workflows to archive items automatically.

https://docs.github.com/en/issues/planning-and-tracking-with-projects/automating-your-project/archiving-items-automatically

Archiving items will help you stay below the limit of 1,200 items in each project.

This feature is useful, but sometimes you may want to archive items based on specific conditions.
For example, you may want to archive issues and pull requests if their repositories are archived.

The above tool ghproj supports archiving them.

e.g. ghproj.yaml

entries:
  - expr: |
      (Item.Open && Item.Repo.IsArchived) ||
      (Item.Title == "Dependency Dashboard")
    action: archive
    project_id: PVT_kwHOAMtMJ84AQCf4

GitHub GraphQL API can't query GitHub Project items, so ghproj retrieves all items and filter them using expr-lang/expr.

Automation with GitHub Actions

You can gather issues and pull requests into GitHub Projects automatically by running ghproj periodically via GitHub Actions schedule events.

This is the workflow I actually use.

https://github.com/szksh-lab/.github/blob/main/.github/workflows/update-project.yaml

This workflow pulls together all issues and pull requests to the GitHub Project:

https://github.com/orgs/szksh-lab/projects/1

Sorting issues and pull requests to multiple projects

The tool ghproj supports multiple projects, so you can sort issues and pull requests to different projects.

e.g. ghproj.yaml

entries:
  # Add issues and pull requests with the label team/sre to the project of the SRE team
  - query: |
      is:open archived:false -project:szksh-lab/2
      owner:szksh-lab label:team/sre
    project_id: PVT_SRE0000000000000
  # Add issues and pull requests whose repositories are managed by SER team to the project of the SRE team
  - query: |
      is:open archived:false -project:szksh-lab/2
      repo:szksh-lab/k8s-clusters
      repo:szksh-lab/aws-org
    project_id: PVT_SRE0000000000000
  # Add issues and pull requests which are assigned to the security team to the project of the Security team
  - query: |
      is:open archived:false -project:szksh-lab/2
      owner:szksh-lab is:pr
      team-review-requested:szksh-lab/security
    project_id: PVT_SECURITY00000000

Conclusion

In this post, I explained how to automatically gather GitHub Issues and Pull Requests across multiple GitHub repositories into GitHub Projects.
I'm maintaining a lot of OSS projects, and managing their issues and pull requests has been challenging.
Using this approach, I could manage them all in one GitHub Project, which was incredibly helpful.

https://github.com/orgs/szksh-lab/projects/1/views/1

I hope this post helps you improve the management of your issues and pull requests.

Set GitHub Actions timeout-minutes

Shunsuke Suzuki — Wed, 03 Jul 2024 02:46:43 +0000

In this article I introduce a GitHub Actions' setting timeout-minutes and tools related to timeout-minutes.

What's timeout-minutes?
Why should you set timeout-minutes?
Linters to enforce timeout-minutes
A command line tool to set timeout-minutes to all GitHub Actions jobs
Set timeout-minutes to your all repositories

What's timeout-minutes?

timeout-minutes is the maximum number of minutes to let a job run before GitHub automatically cancels it.
The default value is 360.

Why should you set timeout-minutes?

The default value of timeout-minutes is 360, but this is too long for most GitHub Actions jobs.
Even if processes are stuck for some reason, jobs keeps running until the timeout.
This wastes resources uselessly.
By setting timeout-minutes properly, you can notice the issue and resolve it by retrying jobs quickly.

https://exercism.org/docs/building/github/gha-best-practices#h-set-timeouts-for-workflows

Linters to enforce timeout-minutes

There are linters to enforce timeout-minutes.

ghalint is a GitHub Actions linter
lintnet is a general purpose linter powered by Jsonnet

ghalint

From ghalint v0.2.12, ghalint enforces timeout-minutes.

https://github.com/suzuki-shunsuke/ghalint/blob/main/docs/policies/012.md

lintnet

ghalint is ported to lintnet as a module.

https://github.com/lintnet-modules/ghalint

So you can enforce timeout-minutes using the module.

https://github.com/lintnet-modules/ghalint/tree/main/workflow/job_timeout_minutes_is_required

A command line tool to set timeout-minutes to all GitHub Actions jobs

It is very bothersome to set timeout-minutes to a lot of jobs by hand.
But you can do it easily using a command line tool ghatm.
It finds GitHub Actions workflows and adds timeout-minutes to jobs which don't have the setting.
It edits workflow files while keeping YAML comments, indents, empty lines, and so on.

For details, please see https://github.com/suzuki-shunsuke/ghatm .

Set timeout-minutes to your all repositories

ghatm is useful, but it is very bothersome to run ghatm and create and merge pull requests to a lot of repositories by hand.
But you can do it easily using ghatm and multi-gitter.

Create pull requests by multi-gitter run

multi-gitter run ./ghatm-set.sh \
    --config config.yaml \
    -O "$org" \
    -t "ci: set timeout-minutes using ghatm" \
    --skip-forks \
    -b "$body" \
    -B ci-set-timeout-minutes-by-ghatm

ghatm-set.sh

ghatm set

config.yaml

git-type: cmd # Use git to sign commits

Merge pull requests by multi-gitter merge

multi-gitter merge \
    -O "$org" \
    -B ci-set-timeout-minutes-by-ghatm \
    --skip-forks

Prevent malicious Terraform Providers

Shunsuke Suzuki — Sun, 05 Nov 2023 04:30:00 +0000

In this blog post, I describe how tfprovidercheck prevents malicious Terraform Providers from being executed.

To run Terraform securely, we should prevent malicious Terraform Providers from being executed.
tfprovidercheck is a simple command line tool for this.
Using tfprovidercheck, you can define the allow list of Terraform Providers and their versions, and check if disallowed providers aren't used.

# Only google provider and azurerm provider are allowed
$ cat .tfprovidercheck.yaml
providers:
  - name: registry.terraform.io/hashicorp/google
    version: ">= 4.0.0"
  - name: registry.terraform.io/hashicorp/azurerm

# tfprovidercheck fails because aws provider is disallowed
$ terraform version -json | tfprovidercheck
FATA[0000] tfprovidercheck failed                        error="this Terraform Provider is disallowed" program=tfprovidercheck provider_name=registry.terraform.io/hashicorp/aws tfprovidercheck_version=0.1.0

Using tfprovidercheck in Terraform CI, you can improve the security of Terraform CI.

Install

tfprovidercheck is a single binary written in Go. So you only need to install an execurable file into $PATH.

Please see Install.

How to use

Prepare tfprovider's configuration
Run terraform init to update the list of Terraform Providers
Run terraform version -json | tfprovidercheck

To prevent malicious codes from being executed, you should run tfprovidercheck before running other Terraform commands such as terraform validate, terraform plan, and terraform apply.

Configuration

There are several ways to configure tfprovidercheck.
In order of priority, they are as follows.

The command line option -config [-c], which is the configuration file path
The environment variable TFPROVIDERCHECK_CONFIG_BODY, which is the configuration itself (YAML)
The environment variable TFPROVIDERCHECK_CONFIG, which is the configuration file path
The configuration file .tfprovidercheck.yaml on the current directory

The field providers lists allowed providers and their versions.

e.g.

providers:
  - name: registry.terraform.io/hashicorp/aws
    version: ">= 3.0.0" # Quotes are necessary because '>' is a special character for YAML
  - name: registry.terraform.io/hashicorp/google
    # version is optional

name (Required, string): name must be equal to the provider name. Regular expression and glob aren't supported
version (Optional, string): The version constraint of Terraform Provider. version is evaluated as hashicorp/go-version' Version Constraints. If version is empty, any version is allowed

💡 Prevent configuration from being tampered

It's important to prevent configuration from being tamperd.
If you run tfprovidercheck on GitHub Actions, pull_request_target event is useful to prevent workflows from being tampered.

Secure GitHub Actions by pull_request_target

tfprovidercheck supports configuring with the environment variable TFPROVIDERCHECK_CONFIG_BODY, so you can define the configuraiton in a workflow file.

e.g.

- run: terraform version -json | tfprovidercheck
  env:
    TFPROVIDERCHECK_CONFIG_BODY: |
      providers:
        - name: registry.terraform.io/hashicorp/aws
          version: ">= 3.0.0"

Then you can prevent configuration from being tampered by pull_request_target event.

Conclusion

In this blog post, I described how tfprovidercheck prevents malicious Terraform Providers from being executed.

Please try tfprovidercheck and give me your feedback!

Secure GitHub Actions by pull_request_target

Shunsuke Suzuki — Mon, 23 Oct 2023 01:34:11 +0000

In this post, I describe how to build secure GitHub Actions workflows by pull_request_target event instead of pull_request event.
This post is based on my post written in Japanese. pull_request_target で GitHub Actions の改竄を防ぐ

GitHub Actions is one of the most popular CI platform.
GitHub Actions is powerful, but has a security concern that workflow files .github/workflows/*.yaml can be tampered and malicious codes can be executed with secrets and permissions in CI.
To solve the issue, I propose using GitHub Actions' pull_request_target event instead of pull_request event.

Note that in this post I talk about the enterprise software development on private repositories rather than OSS activities on public repositories, and I assume pull requests aren't sent from Fork repositories.

Before using `pull_request_target`

Before using pull_request_target, you should utilize GitHub features such as Branch protection rules, code owners, and OIDC, and so on for security.
In this post I assume you are utilizing them properly already. Using pull_request_target is a more advanced topic.

What and Why pull_request_target?

pull_request_target is one of the events triggering GitHub Actions workflows.
One of the differences between pull_request_target and pull_request is that pull_request_target triggers workflows based on the latest commit of the pull request's base branch.
Even if workflow files are modified or deleted on feature branches, workflows on the default branch aren't affected so you can prevent malicious code from being executed in CI without code review.

Example of pull_request_target

If you aren't familiar with pull_request_target and you can't understand how it prevents tampering, please add the following workflow to your repository's default branch.

name: test
on:
  pull_request_target: # Use pull_request_target
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - run: echo "$EVENT"
        env:
          EVENT: ${{toJSON(github)}}

Then please modify the workflow file and create a pull request to the default branch.
The workflow would be run based on the workflow file of the base branch and your modification wouldn't affect to the workflow run.
And even if you remove the workflow from the feature branch, the workflow would be run.
So malicious codes can't be run in CI unless they are merged into the default branch.

This is one of the diffrences between pull_request and pull_request_target.

Don't execute actions and scripts of feature branches

You shouldn't execute actions and scripts of feature branches because they can be tampered.
If you want to execute them, you should get them from safe other repositories or branches such as the default branch.

Secure OIDC Settings

To access Cloud Providers such as AWS and Google Cloud, you should use OIDC rather than secrets in terms of security.

https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect

GitHub supports various OIDC claims.

You can prevent malicious authentication to OIDC with the following claims.

repo
event_name
base_ref
ref

If you want to allow the authentication only on the specific workflows, you can use the claim workflow too.

I describe OIDC settings on AWS and Google Cloud.

AWS

https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services

You create two IAM Roles.

IAM Role for the default branch can create, read, update, and delete resources
IAM Role for pull requests can read resources

You can restrict the authentication to those IAM Roles by the following IAM Role's trust policy.

For the default branch

"Condition": {
  "StringEquals": {
    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
    "token.actions.githubusercontent.com:sub": "repo:octo-org/octo-repo:event_name:push:base_ref::ref:refs/heads/main"
  }
}

For pull_request_target

"Condition": {
  "StringEquals": {
    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
  },
  "StringLike": {
    "token.actions.githubusercontent.com:sub": "repo:octo-org/octo-repo:event_name:pull_request_target:base_ref:main:*"
  }
}

Then you can prevent the following attacks.

Assume the IAM Role for the default branch on pull request
- This is impossible because only push event to the default branch is allowed
Assume the IAM Role for pull requests by running malicious workflows with pull_request event
- This is impossible because only pull_request_target event is allowed
Assume the IAM Role for pull requests by adding malicious workflows to any feature branches and sending pull requests with pull_request_target event to the branches
- This is impossible because base_ref must be main

In case of AWS, you need to set the customization template for an OIDC subject claim for the GitHub repository.
Otherwise, the authentication would fail.

gh api \
  --method PUT \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  "/repos/$REPO/actions/oidc/customization/sub" \
  -F use_default=false \
  -f "include_claim_keys[]=repo" \
  -f "include_claim_keys[]=event_name" \
  -f "include_claim_keys[]=base_ref" \
  -f "include_claim_keys[]=ref"

Google Cloud

You create two Service Accounts.

Service Account for the default branch can create, read, update, and delete resources
Service Account for pull requests can read resources

You can restrict the authentication to those Service Accounts by the following Attribute mappings and Attribute conditions.

Attribute mapping

attribute.repository = assertion.repository
attribute.event_name = assertion.event_name
attribute.base_ref   = assertion.base_ref
attribute.ref        = assertion.ref
attribute.workflow   = assertion.workflow

Attribute conditions

For CI on Pull Request

attribute.repository == "kouzoh/microservices-terraform" && 
  attribute.event_name == "pull_request_target" &&
  attribute.base_ref == "master"

For CI on the default branch

attribute.repository == "octo-org/octo-repo" && 
  attribute.event_name == "push" &&
  attribute.ref == "refs/heads/main"

Then you can prevent attacks same with AWS.
Unlike AWS, you don't have to set the customization template for an OIDC subject claim for the repository.

Secret Management

To access secrets securely in CI, you should manage them in secrets management services such as AWS Secrets Manager and Google Secret Manager and access them via OIDC so that you can restrict access to them with OIDC claims.
GitHub's Environment Secrets can also restrict the access but it supports only the restriction based on branches, so malicious workflows can access secrets for pull request CI.
As I described in the previous section, OIDC supports more flexible restrictions, so they are better than GitHub Secrets in terms of security.

Modify workflows for pull_request_target

The GitHub Actions built in environment variables and Context of pull_request_target event are different from those of pull_request event.
For example, the following environment variables and context are different.

event_name, GITHUB_EVENT_NAME
ref, GITHUB_REF
sha, GITHUB_SHA
ref_name, GITHUB_REF_NAME

You may need to fix scripts and actions so that they work well on pull_request_target events.
For example, if you use tfcmt and github-comment, which are my OSS, you need to set the merge commit hash to the environment variables TFCMT_SHA and GH_COMMENT_SHA1.
You also need to check if third party actions support the pull_request_target event.

Checkout merge commits

To checkout the merged commit with actions/checkout on pull_request_target event, you need to get the pull request by GitHub API and set the merge commit hash to actions/checkout input ref.

- uses: actions/github-script@v6
  id: pr
  with:
    script: |
      const { data: pullRequest } = await github.rest.pulls.get({
        ...context.repo,
        pull_number: context.payload.pull_request.number,
      });
      return pullRequest
- uses: actions/checkout@v4
  with:
    ref: ${{fromJSON(steps.pr.outputs.result).merge_commit_sha}}

I created a small action for this.

- uses: suzuki-shunsuke/get-pr-action@v0.1.0
  id: pr
- uses: actions/checkout@v4
  with:
    ref: ${{steps.get-pr.outputs.merge_commit_sha}}

It is useless to call the GitHub API to get the merge commit hash everytime you run actions/checkout, so it's good to get the merge commit hash in one job and pass the merge commit hash by the job's output.

jobs:
  get-pr:
    outputs:
      merge_commit_sha: ${{steps.prs.outputs.merge_commit_sha}}
    runs-on: ubuntu-latest
    steps:
      - uses: suzuki-shunsuke/get-pr-action@v0.1.0
        id: pr
  foo:
    runs-on: ubuntu-latest
    needs:
      - get-pr
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{needs.get-pr.outputs.merge_commit_sha}}

Note that the context value ${{github.event.pull_request.merge_commit_sha}} isn't the latest merge commit hash.

Test of workflow changes

One of the drawbacks of pull_request_target is that it's difficult to test changes of GitHub Actions workflows in CI because changes aren't reflected until they are merged to the default branch.
Especially, if pull requests by Renovate are merged automatically, workflows may be broken suddenly.

To solve the issue, maybe you can run workflows with test files when workflow files are modified.
By separating workflows as reusable workflows, maybe you can test workflow changes with test inputs.

About Renovate, disabling auto-merge of actions updates is also one of options.

Conclusion

In this post, I described how to build secure GitHub Actions workflows by pull_request_target event instead of pull_request event.
Using pull_request_target, you can prevent malicious codes from being executed in CI.
And by managing secrets in secrets management services such as AWS Secrets Manager and Google Secret Manager and access them via OIDC, you can restrict the access to secrets securely.
To migrate pull_request to pull_request_target, several modifications are needed.
And pull_request_target has a drawback that it's difficult to test changes of workflows, so it's good to introduce pull_request_target to repositories that require strong permissions in CI.
For example, a Terraform Monorepo tends to require strong permissions for CI, so it's good to introduce pull_request_target to it.

Terraform's Drift Detection by tfaction

Shunsuke Suzuki — Mon, 05 Jun 2023 00:28:41 +0000

In this article I describe the overview of Terraform's Drift Detection by tfaction.

https://suzuki-shunsuke.github.io/tfaction/docs/feature/drift-detection

What's tfaction?

https://suzuki-shunsuke.github.io/tfaction/docs/

tfaction is a framework for Monorepo to build high level Terraform Workflows by GitHub Actions. You don't have to run terraform apply in your laptop, and don't have to reinvent the wheel for Terraform Workflows anymore.

What's drift?

In the context of IaC, drift means the divergence between the code and infrastructure.
Drift harms not only the reliability of the code but also the productivity.
So you should detect and resolve the drift as soon as possible.

In case of Terraform, the drift causes the unexpected changes of terraform plan. Unexpected changes confuse you and let you handle them.

What's tfaction's Drift Detection?

From tfaction v0.6.0, tfaction supports Drift Detection.
tfaction enables you to detect the drift periodically and manage the drift as GitHub Issues.

This feature is disabled by default. To enable, please see the document.

tfaction creates an Issue per working directory.
tfaction checks if the drift exists at the following timing.

apply workflow
- apply workflow is run when the pull request is merged
- If the job succeeds, the issue is closed.
- If the job fails, the issue is reopened.
schedule-detect-drifts workflow
- schedule-detect-drifts is run periodically
- If terraform plan has no change, the issue is closed
- If the job fails or terraform plan has change, the issue is reopened.

tfaction reopens the issue when the drift is detected, and closes the issue when the drift is resolved.
tfaction posts a comment and updates the issue description according to the result of the drift detection.

Example 1. An Issue is closed because terraform apply succeeds and the drift is resolved

Example 2. An Issue is opened because terraform apply fails

Example 3. Drift is checked by schedule-detect-drifts periodically

Example 4. The latest comment is reflected to the issue description

Good point

If you already use GitHub Issues for your task management, you can add drift handling into your task management naturally.
You don't have to create issues yourself. You can manage issues in GitHub Projects, adjust the priority, and assign someone to issues.

Issue's comments become the history, so you can track when the drift is raised and which pull request caused the drift.
And comments tell you not only the existence of the drift but also the content of the drift.

You can adjust the frequency of the drift detection, and select workfing directories where the dirft detection is enabled.

Conclusion

In this article I described the overview of Terraform's Drift Detection by tfaction.
About the details, please see the document.

https://suzuki-shunsuke.github.io/tfaction/docs/feature/drift-detection

Improve OSS issue management with GitHub Issue/Discussion template and actions

Shunsuke Suzuki — Sun, 07 May 2023 04:03:39 +0000

In this post, I describe how I improved some OSS's issue management.

e.g. https://github.com/suzuki-shunsuke/tfcmt/pull/764

Enforce users to use Discussion instead of Issue

I set up GitHub Actions to close issues created by users automatically.

e.g. https://github.com/suzuki-shunsuke/tfcmt/blob/4a164485908ee216cd9534900dea82e652c00b38/.github/workflows/close-issue.yaml

Users have to use GitHub Discussions instead. Only maintainers can create issues. This keeps issues maintainable and actionable.

In many projects, the distinction between the use of Issue and Discussion is ambiguous and varies from person to person.
This ambiguousness often raises friction and frustration.
By enforcing users to use Discussion, the ambiguousness would be solved.

Before creating an issue, users would be able to understand the rule by issue template's warning.
By disabling blank issues, users can't ignore templates.

e.g. https://github.com/suzuki-shunsuke/tfcmt/issues/new/choose

And the header of issue templates guides this rule to users.

Discussion template

I provide various templates for various use cases.

e.g. https://github.com/suzuki-shunsuke/tfcmt/discussions/new/choose

If the type of categories isn't enough, users would not be able to choose appropriate category and use general purpose category which isn't well-formatted.

And GitHub's form schema enforces users to write required information and the schema unifies the format of discussions.
This would improve the quality of discussions.
This reduces the miscommunication, the communication to ask required information, and the burden of maintainers.

e.g. https://github.com/suzuki-shunsuke/tfcmt/discussions/new?category=bug-report

The non structured category is also provided for general purpose, but the template header encourage users to use other categories.

All categories are Answers enabled, so we can make the conclusion easy to understand and clarify the status without closing the discussion.

DEV Community: Shunsuke Suzuki

Short-lived GitHub Access Token for secure local development by ghtkn

The Problem with Traditional Tokens

How ghtkn Solves This

Getting Started

Extras & Advanced Use

Who Should Use ghtkn

Why ghtkn Might Be a Game Changer

How to pin GitHub Actions to a full commit length SHA across all repositories in your organization

pinact

multi-gitter

Continuous Updates

Conclusion

Fix Code Via GitHub Actions By Verified Commits

Why Use commit-action?

How To Use

Refactor Terraform Resource Names By One Command

Features of tfmv

Quick start

Conclusion

Lock Mechanism on GitHub Actions

Features

How to Use

How It Works

Conclusion

aqua Now Supports Node.js

How to Manage Node.js Using aqua

Configure npm preset config

Why do we need to configure npm preset config?

Gathering GitHub Issues and Pull Requests Across Repositories into GitHub Projects Automatically

1. Using the built-in automations

2. Running GitHub Actions by issues and pull requests' opened events

3. Running GitHub Actions by schedule event to search issues and pull requests and add them to projects

GitHub Access Token

1. Using a classic PAT

2. Using a GitHub App

Archiving GitHub Projects Items Based on Conditions

Automation with GitHub Actions

Sorting issues and pull requests to multiple projects

Conclusion

Set GitHub Actions timeout-minutes

What's timeout-minutes?

Why should you set timeout-minutes?

Linters to enforce timeout-minutes

ghalint

lintnet

A command line tool to set timeout-minutes to all GitHub Actions jobs

Set timeout-minutes to your all repositories

Prevent malicious Terraform Providers

Install

How to use

Configuration

💡 Prevent configuration from being tampered

Conclusion

Secure GitHub Actions by pull_request_target

Before using pull_request_target

What and Why pull_request_target?

Example of pull_request_target

Don't execute actions and scripts of feature branches

Secure OIDC Settings

AWS

Google Cloud

Secret Management

Modify workflows for pull_request_target

Checkout merge commits

Test of workflow changes

Conclusion

Terraform's Drift Detection by tfaction

What's tfaction?

What's drift?

What's tfaction's Drift Detection?

Good point

Conclusion

Improve OSS issue management with GitHub Issue/Discussion template and actions

Enforce users to use Discussion instead of Issue

Discussion template

Configure npm `preset` config

Why do we need to configure npm `preset` config?

Before using `pull_request_target`