How connections work, wired by hand

Connect GitHub Issues, Jira or Trello, and the Create an issue button on a note files it as a real ticket. When the ticket is closed, the note on the page turns green by itself. Reopen the ticket, and the note opens again.

The round trip#

1. Someone presses Create an issue on a note.
2. Within seconds, the ticket appears in your tracker, with the note's words, the page and element it is about, a link back to the page, and its screenshots (attached in Jira and Trello).
3. The note shows the ticket's number, and stays open: raising a problem is not fixing it.
4. Your team works on the ticket as usual.
5. When the ticket is closed, the note is marked done on the page, for everyone. If the ticket is reopened, so is the note.

A note someone marked done by hand is left alone.

Why it runs on your server#

The page is public to anyone who can open it, so it must never hold a password or token for your tracker. Instead:

• The page only marks the note as waiting, on your store.
• A small program, the connector, runs on your server beside the store. It holds the tracker's token, files waiting notes, and checks on their tickets.

What you need#

• The store running, with your page's tag pointing at it.
• The connectors folder from the download, on the same server.
• Python 3.8 or newer.
• About ten minutes, and permission to create a token in your tracker.

1Turn on Create an issue

Add data-issues="queue" to the tag on your page:

<script src="/notefix/notefix-embed.js"
        data-api="/notefix-api"
        data-board="staging"
        data-issues="queue"></script>

2Give the store a secret

The connector changes notes, so the store should only accept those changes from it. Make up a long random secret:

python3 -c "import secrets; print(secrets.token_urlsafe(32))"

Restart the store with it:

NOTES_CONNECTOR_SECRET=paste-the-secret-here NOTES_DATA=/var/lib/notefix NOTES_BOARDS=staging python3 server/server.py

(With Docker, add -e NOTES_CONNECTOR_SECRET=... to docker run.)

3Set up your tracker

Follow the page for yours. Each one walks through making the token and starting the connector:

Or hand notes to an AI agent instead of a person: see Hand notes to an agent.

See what is connected#

Open All notes, then Settings, then Connected tools. Everyone on the page sees the same list:

Each connection has a state. Point at its row for more.

Nobody has to be looking at Settings to find out: a broken connection puts an amber dot on the Settings gear and a line at the top of All notes, and if Slack is set up, the team is told there.

Settings only ever shows what kind of problem it is. The exact error stays in the connector's log on the server, because anyone who can open the page can see Settings.

Adding or removing a connection happens on the server: start or stop that tracker's connector, or add Slack or email to the notifier. Settings updates on its own within a minute. Each row links to its setup guide.

Pause a connection#

Point at a connection in Settings → Connected tools and press Pause (the two bars). It is paused for everyone on the board, until somebody presses Resume.

• A paused tracker files nothing new: notes sent to it wait on the board, and nothing is lost. Tickets it already filed still close their notes. While it is paused, Create an issue does not offer it.
• Paused Slack or email is sent nothing, and what happens meanwhile is not saved up, so resuming does not flood the channel.
• Nobody is alerted about a paused connection.

Anyone who can open the page can pause and resume, the same as anyone can clear finished notes today. Once there are logins, it will be the project owner's.

Each running connection also has a link straight to its repository, project or board.

More than one tracker#

GitHub, Jira and Trello can all run on the same board. Each note goes to one of them:

• With one tracker running, Create an issue sends it there.
• With more than one, Create an issue asks Where should this issue go?, with a button for each.
• To stop being asked, pick one under Settings → Connected tools → Create issues in. That choice is kept in your browser only, so it never changes where anyone else's issues go.

Each connector only files the notes meant for it, so two trackers never make two tickets for one note.

Keep tokens safe#

Every tracker page ends with the same pattern: the settings go in a file only the connector's user can read, never in a command someone can see.

sudo mkdir -p /etc/notefix
sudo install -m 600 -o notefix /dev/null /etc/notefix/github.env
sudoedit /etc/notefix/github.env

And the connector runs as a service that reads that file:

# /etc/systemd/system/notefix-github.service
[Unit]
Description=Notefix GitHub connector
After=network.target

[Service]
User=notefix
EnvironmentFile=/etc/notefix/github.env
ExecStart=/usr/bin/python3 /opt/notefix/connectors/runner.py github
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now notefix-github
journalctl -u notefix-github -f      # watch what it does

Good to know#

• Nothing is filed twice. Each ticket carries a hidden marker, so a connector that crashes halfway picks up where it left off instead of making a second ticket.
• If your tracker is down, the connector keeps trying, waiting longer each time, and gives up on a note after 8 tries with a clear line in its log.
• Links back to the note, in tickets, Slack and email, open the page and land on the note.