Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 54 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
name: CI

# Third-party actions are pinned to a full commit SHA (the tag in a trailing
# comment), as in hadron-cli, so a moved upstream tag cannot change what runs.

on:
push:
branches: [main]
pull_request:

permissions:
contents: read

jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
- uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6
with:
go-version-file: go.mod
- name: Build
run: go build ./...
# The adapter runs wherever the hadron CLI runs.
- name: Cross-build
run: |
for t in linux/amd64 linux/arm64 darwin/amd64 darwin/arm64 windows/amd64; do
GOOS=${t%/*} GOARCH=${t#*/} go build -o /dev/null ./cmd/hadron-task-adapter-github
done
# Includes the conformance suite: the built adapter driven by the
# hadron-cli runner's rules against a fake GitHub.
- name: Test
run: go test -race ./...

lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
- uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6
with:
go-version-file: go.mod
- uses: golangci/golangci-lint-action@ba0d7d2ec06a0ea1cb5fa41b2e4a3ab91d21278a # v9
with:
skip-cache: true

vuln:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
- uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6
with:
go-version-file: go.mod
- name: govulncheck
run: go run golang.org/x/vuln/cmd/[email protected] ./...
8 changes: 8 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# A team's own adapter configuration (repositories, labels, team map) and any
# credential stay out of this public repository. Only config.example.json is
# committed.
/config.json
*.local.json
.env
/bin/
/dist/
25 changes: 25 additions & 0 deletions .golangci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
version: "2"

linters:
default: standard
enable:
- misspell
- unconvert
- unparam
settings:
errcheck:
exclude-functions:
- fmt.Fprint
- fmt.Fprintf
- fmt.Fprintln
- (io.ReadCloser).Close
- (*os.File).Close

# Formatting is a gate: `golangci-lint run` reports a gofmt diff as an issue.
formatters:
enable:
- gofmt

issues:
max-issues-per-linter: 0
max-same-issues: 0
21 changes: 21 additions & 0 deletions LICENSE
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
MIT License

Copyright (c) 2026 Hadron Memory

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
156 changes: 155 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -1 +1,155 @@
# hadron-task-adapter-github
# hadron-task-adapter-github

The GitHub **intake adapter** for [Hadron](https://hadronmemory.com) teams. The
`hadron` CLI runs it to find the GitHub issues no task of the team tracks yet,
and to mark the issues a task claims. Hadron itself never calls GitHub: the
adapter runs on the team's host with the team's own GitHub credential.

The adapter implements the public, versioned intake adapter contract
(`cor:agt:120:04` in the Hadron specs), contract version **1**, in the
invocation format of the hadron CLI's adapter runner
([hadron-cli#1961](https://github.com/hadron-memory/hadron-cli/issues/1961)).

## Install

```sh
go install github.com/hadron-memory/hadron-task-adapter-github/cmd/hadron-task-adapter-github@latest
```

It needs a `hadron` CLI that has `team task find-untracked --adapter`
(hadron-cli#1961).

## Use

```sh
export GITHUB_TOKEN=… # the team's own GitHub token, never a Hadron one
export TASK_ADAPTER_GITHUB_CONFIG=~/.config/hadron-task-adapter-github/config.json

hadron team task find-untracked --adapter hadron-task-adapter-github # list
hadron team task find-untracked --adapter hadron-task-adapter-github --track # claim and mark
```

`HADRON_INTAKE_ADAPTER=hadron-task-adapter-github` saves passing `--adapter`.

You can also call the adapter directly to try a configuration:

```sh
echo '{"contractVersion":1}' | hadron-task-adapter-github check
echo '{"contractVersion":1,"limit":5}' | hadron-task-adapter-github list-untracked
```

## Configuration

The configuration is a JSON file, read from `$TASK_ADAPTER_GITHUB_CONFIG`, or
by default from `hadron-task-adapter-github/config.json` under the user
configuration directory (`~/.config` on Linux, `~/Library/Application Support`
on macOS). It holds the team's label model and no credential. **Keep it out of
this repository**, and out of any public one: it names the team's repositories,
labels and workers. [`config.example.json`](config.example.json) shows every
key.

| Key | Meaning |
|---|---|
| `repositories` | `"owner/name"`, 1 to 20. Their **open issues** are the intake (pull requests are not). |
| `readyLabel` | The label that marks an issue ready for intake. |
| `ready` | `only` (list only ready issues; the default when `readyLabel` is set), `exclude`, or `any` (the default without one). |
| `excludeLabels` | An issue carrying any of these is never listed. |
| `teams` | Maps the CLI's `--for X` to a team: `{"for": ["Name", "<worker URN>"], "label": "team-x"}` lists the issues carrying `team-x`; `{"for": [...], "noTeam": true}` lists the issues carrying no team's label. A `--for` that no team maps is refused. Without `--for`, the list is not narrowed by team. |
| `trackedLabel` | The adapter's mark. Default `hadron-tracked`. |
| `comment` | `true` also posts a comment on mark naming the task (and its portal link, as the server printed it) and the worker. Off by default: on a public repository it publishes the team's worker names. |
| `tokenEnv` | The environment variable holding the token. Default: `GITHUB_TOKEN`, then `GH_TOKEN`. |
| `apiUrl`, `graphqlUrl`, `webHost` | For GitHub Enterprise Server: `https://HOST/api/v3`, `https://HOST/api/graphql`, `HOST`. Default github.com. Only `https` is accepted (plain `http` only to the loopback interface). |

Labels are compared without regard to case. Unknown keys are refused, so a
misspelt key fails loudly instead of widening the intake.

### The credential

The adapter reads the team's GitHub token from the environment. It is sent only
in the `Authorization` header to the configured API, and never printed: error
text from GitHub is scrubbed of it. The hadron CLI never passes its own
`HADRON_*` credentials to an adapter, so a `HADRON_` variable cannot be the
token.

A fine-grained token needs, on each configured repository: **Issues: read and
write** (to read issues and to add or remove the mark) and **Metadata: read**.

Create the `trackedLabel` in each repository before the first claim
(`gh label create hadron-tracked -R owner/name`). `check` reports a repository
where it is missing.

## The calls

Every call is `hadron-task-adapter-github <call>`, one argument and no shell.
The request is one JSON object on stdin, always with `"contractVersion": 1`;
the answer is one JSON object on stdout and exit 0. A refusal is a non-zero
exit, a one-line reason on stderr and nothing on stdout.

| Call | Request | Answer |
|---|---|---|
| `describe` | (nothing else) | `name`, `version`, `contractVersion` (1), `calls`, `filters` (`["for"]`), `order` (`created-asc`). Answered whatever version the caller speaks. |
| `list-untracked` | `limit` (1 to 100, default 20), `cursor`, `for` | `items`: `[{externalId, title}]`; `nextCursor`, or `null` at the end of the list. |
| `mark-tracked` | `externalId`, `task` {`id`, `handle`, `portalUrl`}, `worker` {`id`, `name`, `role`, `model`} | `{"marked": true, …}` |
| `untrack` | `externalId` | `{"untracked": true, …}`. An issue with no mark is not an error. |
| `get` | `externalId` | `item`: `externalId` (as asked), `title`, `body`, `state` (`open`/`closed`), `url` (GitHub's canonical URL now), `tracked`. |
| `normalize` (optional) | `ref`: an issue URL, `owner/name#N`, or `#N` with one repository configured | `externalId`: GitHub's canonical issue URL. |
| `check` (optional) | (nothing else) | `ok`, and `checks`: the configuration, the credential, and for each repository that it is readable and has the `trackedLabel`. Always exit 0. |

The optional calls `report` and `changed-since` are not answered yet.

- **The external id** is the issue's canonical URL exactly as GitHub prints it,
for example `https://github.com/hadron-memory/hadron-server/issues/4084`:
one spelling for one issue, every time. The CLI writes it as given, and hands
the same string back to `mark-tracked`, `get` and `untrack`, which accept
only that shape and only for a configured repository.
- **The list's order** is oldest first across all repositories, then
repository, then issue number.
- **The cursor** is opaque. It records, for each repository, GitHub's own
position, and the query it belongs to: a cursor from another `--for` or from
before the configuration changed is refused, not resumed somewhere wrong. The
set of open issues does not change when an issue is marked (the mark is a
label, and filtering happens in the adapter), so a cursor taken before others
claimed still resumes at the right place and skips nothing.
- **The mark** is the `trackedLabel`, and optionally a comment. It never makes
or decides a claim: the claim is the CLI's task create. A second mark of the
same issue (after a reassignment) is an ordinary call, never a refusal. Once
the label is on, the call succeeds: a comment that then fails is answered as
`"commented": false` with a `commentError`, not as a refusal, since the issue
is marked and no longer lists.
- **Never partial.** A GitHub error, a rate limit, or an answer the adapter
does not understand refuses the whole call; a list is never cut short and
presented as whole. Labels past GitHub's first page of 100 are read too,
since they decide the filters.
- **Labels never reach Hadron.** No answer carries an issue's labels.

### Exit codes

| Code | Meaning |
|---|---|
| 0 | answered |
| 1 | GitHub refused, failed, or answered something unusable |
| 2 | the request: an unknown call, not one JSON object, another contract version, a bad argument or cursor |
| 3 | the configuration or the credential |

The hadron CLI reads any non-zero exit as the adapter's refusal.

## Development

```sh
go test -race ./... # includes the conformance suite
golangci-lint run # the CI lint, gofmt included
```

[`conformance/`](conformance) builds the adapter and drives it the way the
hadron CLI's runner does, against a fake GitHub
([`internal/fakegithub`](internal/fakegithub)), checking every answer against
the runner's rules. Those rules are copied from hadron-cli (its runner package
is internal to the CLI module), and `conformance/runner_rules.go` names the
hadron-cli revision they were copied from. When the runner changes a bound,
change it there too.

The design, and the decisions it rests on, is in [`docs/design.md`](docs/design.md).

## License

MIT, as hadron-cli.
27 changes: 27 additions & 0 deletions cmd/hadron-task-adapter-github/main.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
// Command hadron-task-adapter-github is the GitHub intake adapter for Hadron
// teams: the hadron CLI runs it to list a team's GitHub issues that no task
// tracks yet, and to mark the ones a task claims (cor:agt:120:04). See the
// README for the calls, the configuration and the credential.
package main

import (
"context"
"os"
"os/signal"
"syscall"

"github.com/hadron-memory/hadron-task-adapter-github/internal/adapter"
)

func main() {
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
code := adapter.Run(ctx, adapter.Env{
Args: os.Args[1:],
Stdin: os.Stdin,
Stdout: os.Stdout,
Stderr: os.Stderr,
Getenv: os.Getenv,
})
stop()
os.Exit(code)
}
12 changes: 12 additions & 0 deletions config.example.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
{
"repositories": ["your-org/your-repo", "your-org/another-repo"],
"readyLabel": "ready",
"ready": "only",
"excludeLabels": ["epic", "wontfix"],
"teams": [
{ "for": ["WorkerName", "hrn:worker:example.com:your-team-app:workername"], "label": "team-a" },
{ "for": ["AnotherWorker"], "noTeam": true }
],
"trackedLabel": "hadron-tracked",
"comment": false
}
Loading
Loading