gh-tt

This utility supports the workflow used by the .tech that full-stack team within .the tech collective. It is designed as an opinionated flow. If you share our values and like our process, you can easily set this up for your own team.

Addendum

• The opinionated .tech that workflow
• How we work with mentorship over pull requests

More goodies in the discussions

• The Discussions on the repo contains a lot of additional perspective and reflections on how the get the most our of this gh tt utility.

Introduction

In short, gh-tt supports a workflow that

1. follows trunk-based development practices (main is the only long-lived branch)
2. does not rely on Pull Requests, wait states and bureaucracy
3. works with RESPONSIBLES (CODEOWNERS re-implemented for the PR-less team)

gh tt implements ideas from DevOps, GitOps and CI/CD, wrapped up into a sweet, highly configurable, workflow. It looks something like this:

1. gh tt workon -i 101 - start working on issue #101
   • Create a new development branch and switch to it
   • Move the issue to In Progress in a GitHub Project
2. Hackity hack clickity clack
3. git add .
4. gh tt wrapup -m "Rewrite everything in Rust"
   • Create and push a new commit to the development branch, automatically mentioning the issue
   • Parse and notify RESPONSIBLES
   • Run CI
5. gh tt deliver
   • Squash the development branch into one commit, create and push a new ready/<dev_branch_name> branch with that commit
   • Run CI
   • If CI passes, fast-forward merge the ready branch commit to main

Read about it in more detail in docs/workflow.md. See it in action in this repository, e.g. #206.

Feedback, discussions, contributing

Issues are open on the repo: thetechcollective/gh-tt. If you experience errors, misbehavior, or have feature requests, feel free to join the discussion.

For contributing, see CONTRIBUTING.md.

Getting started

Install

This utility is a GitHub Command Line extension.

Dependencies:

• python3 – any version, but developed and tested on v3.13. No additional Python dependencies (install Python)
• gh – the GitHub Command Line Interface (install GitHub CLI)

Once you have both dependencies installed, run:

gh extension install thetechcollective/gh-tt

The extension requires write access to GitHub Projects (scope project). If you don't have it, you'll be prompted with instructions.

Configure required values

Create a .tt-config.json in the root of your repository. You can take inspiration from the default configuration file, classes/tt-config.json.

Important

gh tt requires a GitHub Project to work with.

The minimal required configuration looks like:

{
    "project": {
        "owner": "your-github-organization",
        "number": 1 # The project number
    }
}

Configure optional values

You might also want to configure which Status issues are assigned when executing workon (start working on an issue) and deliver (finish and push to main if CI passes).

The defaults are

{
    "workon": {
        "status": "In Progress"
    },
    "deliver": {
        "status": "Delivery Initiated"
    }
}

Tip

There's many more configuration options laid out in classes/tt-config.json.

Add files to .gitignore

Our setup may pollute the workspace with two files you might want to add to .gitignore:

.tt_cache
_temp.token

• .tt_cache is used to optimize execution. If you change project settings in .tt-config.json, delete this cache.
• _temp.token is related to the optional configuration described below. It's created and used by gh-login.sh. You only need to add it to .gitignore if you use gh-login.sh.

Syntax

Run gh tt -h to see the syntax.

The extension provides four subcommands: workon, wrapup, and deliver, responsibles and semver. See the workflow for details.

Tip

Each subcommand supports the -h, --help option to display in-detail guidance for the specific subcommand, e.g. gh tt workon -h

For an overview, run gh tt -h

usage: gh tt [-h] [-v] [--version] {workon,wrapup,deliver,responsibles,semver} ...

A command-line tool to support a consistent team workflow. It supports a number of subcommands which
define the entire process: `workon`, `wrapup`, `deliver`. Use the `-h|--help` switch on each to learn
more. The extension utilizes the GitHub CLI tool `gh` to interact with GitHub and therefore it's
provided as a gh extension. GitHub Projects integration is supported. It enables issues to
automatically propagate through the columns in the (kanban) board. Please consult the README.md file
in 'thetechcollective/gh-tt' for more information on how to enable this feature - and many more neat
tricks.

positional arguments:
  {workon,wrapup,deliver,responsibles,semver}
    workon              Set the issue number context to work on
    wrapup              Commit the status of the current issue branch and push it to the remote
    deliver             Create a collapsed 'ready' branch for the current issue branch and push it to
                        the remote
    responsibles        List the responsibles for the current issue branch
    semver              Reads and sets the current version of the repo in semantic versioning format

options:
  -h, --help            show this help message and exit
  -v, --verbose         Enable verbose output
  --version             Print version information and exit

Workflow nice-to-haves

Next to gh-tt, we also use devcontainers. Here's some neat tricks that will make your life easier.

For inspiration, see devcontainer.json in this repo.

"initializeCommand": "./.devcontainer/initializeCommand.sh",
"postCreateCommand": "./.devcontainer/postCreateCommand.sh",

Both are designed as one-liners and are placed in separate files.

initializeCommand.sh

Uses gh-login.sh to generate a token from your host machine and prepare it for reuse in the container by postCreateCommand.sh. This allows your container to inherit your host's gh auth status.

postCreateCommand.sh

Expands the repo's .git/.gitconfig with some additional aliases defined in .gitconfig. Git does not natively support a .gitconfig file in the repository root. So we add it:

gh-tt/.devcontainer/postCreateCommand.sh

Lines 11 to 12 in 47ec72e

	echo "$PREFIX Setting up git configuration to support .gitconfig in repo-root"
	git config --local --get include.path | grep -e ../.gitconfig >/dev/null 2>&1 || git config --local --add include.path ../.gitconfig

We install the GitHub extension:

gh-tt/.devcontainer/postCreateCommand.sh

Line 25 in 47ec72e

gh extension install thetechcollective/gh-tt

And import some aliases

gh-tt/.devcontainer/postCreateCommand.sh

Line 27 in 47ec72e

gh alias import .gh_alias.yml --clobber

This creates shortcuts so you can run:

gh workon        # instead of gh tt workon
gh wrapup        # instead of gh tt wrapup
gh deliver       # instead of gh tt deliver
gh responsibles  # instead of gh tt responsibles
gh semver        # instead of gh tt semver

Your feedback - or request for help - is always welcome: Use the Issues or the Discussions to communicate.