utkuufuk/entrello

Sync your tasks from multiple sources in one Trello board

entrello

Table of Contents

• Features
• Service Configuration
• Runner Mode
• Server Mode
• Running With Docker
• Example entrello Services
• Trello Webhooks Reference

---

Features

• Synchronizes all your tasks from various sources in one Trello board.
• Lets you build automations that can be triggered when a card is archived.
• Can be used either as a server or a runner (e.g. a cronjob).

Synchronization

entrello synchronizes your tasks from one or more sources in one Trello board by:

1. Polling one or more of your custom HTTP services, each of which must return a JSON array of "tasks".
2. Creating a new card in your Trello board for each new task it has received from your services.
3. Optionally deleting any existing stale cards in your Trello board.

Synchronization feature is supported by both the runner and server modes.

Automation

entrello lets you build custom automations based on archived card events:

1. Whenever a Trello card is archived (i.e. done), it POSTs this event to the matching HTTP service, if any.
2. Your service may handle this POST request and take further actions, e.g. it could update some value in a spreadsheet.

Automation feature is supported only by the server mode, which listens for Trello webhooks.

---

Service Configuration

See config.example.json for reference.

Your custom HTTP services must each return a JSON array of Trello card objects upon GET requests.

Mandatory configuration parameters

• name — Service name.

• endpoint — Service endpoint URL.

• label_id — Trello label ID. A label ID can be associated with no more than one service.

• list_id — Trello list ID, i.e. where to insert new cards. The list must be in the board specified by the root-level board_id config parameter.

• period — Polling period. A few examples:

  // poll on 3rd, 6th, 9th, ... of each month, at 00:00
  "period": {
    "type": "day",
    "interval": 3
  }
  
  // poll every day at 00:00, 02:00, 04:00, ...
  "period": {
    "type": "hour",
    "interval": 2
  }
  
  // poll every hour at XX:00, XX:15, XX:30, XX:45
  "period": {
    "type": "minute",
    "interval": 15
  }
  
  // poll on each execution
  "period": {
    "type": "default"
  }

Optional configuration parameters

• secret — Alphanumeric API secret. If present, entrello will put it in the X-Api-Key HTTP header.

• strict — Whether stale cards should be deleted from the board upon synchronization. false by default.

---

Runner Mode

Create a service configuration file based on config.example.json. You can trigger a one-off synchronization by executing the runner:

# run this as a scheduled (cron) job
go run ./cmd/runner -c /path/to/config/file

If the -c flag is omitted, the runner looks for a file called config.json in the current working directory:

# these two are equivalent:
go run ./cmd/runner
go run ./cmd/runner -c ./config.json

---

Server Mode

Put your environment variables in a file called .env based on .env.example and start the server:

go run ./cmd/server

Synchronization

You can trigger a one-off synchronization by making a POST request to the server with the service configuration in the request body:

# run this as a scheduled (cron) job
curl <SERVER_URL> \
    -d @<path/to/config.json> \
    -H "Authorization: Basic <base64(<USERNAME>:<PASSWORD>)>"

Automation

To enable automation for one or more services:

1. Create a Trello webhook by setting the callback URL to <ENTRELLO_SERVER_URL>/trello-webhook
2. Set the SERVICES environment variable, a comma-separated list of service configuration strings:
   • A service configuration string must contain the Trello label ID and the service endpoint:

     <TRELLO_LABEL_ID>@<SERVICE_ENDPOINT_URL>

   • It may additionally contain an API secret – alphanumeric only – for authentication purposes:

     # the HTTP header "X-Api-Key" will be set to "SuPerSecRetPassW0rd" in each request
     <TRELLO_LABEL_ID>:SuPerSecRetPassW0rd@<SERVICE_ENDPOINT_URL>

---

Running With Docker

A new Docker image will be created upon each release.

1. Authenticate with the GitHub container registry (only once):

   echo $GITHUB_ACCESS_TOKEN | docker login ghcr.io -u GITHUB_USERNAME --password-stdin

2. Pull the latest Docker image:

   docker pull ghcr.io/utkuufuk/entrello/image:latest

3. Spawn & run a container:

   # server
   docker run -d \
       -p <PORT>:<PORT> \
       --env-file </absolute/path/to/.env> \
       --restart unless-stopped \
       --name entrello-server \
       ghcr.io/utkuufuk/entrello/image:latest
   
   # runner
   docker run --rm \
       -v </absolute/path/to/config.json>:/bin/config.json \
       ghcr.io/utkuufuk/entrello/image:latest \
       ./runner

---

Example entrello Services

You may use these as references for developing your own services:

• utkuufuk/habit-service
• utkuufuk/github-service
• utkuufuk/goodreads-service

---

Trello Webhooks Reference

# create new webhook
curl -X POST -H "Content-Type: application/json" -d \
'{
  "key": "<TRELLO_API_KEY>",
  "callbackURL": "<ENTRELLO_SERVER_CALLBACK_URL>",
  "idModel": "<TRELLO_BOARD_ID>",
  "description": "<DESCRIPTION>"
}' https://api.trello.com/1/tokens/<TRELLO_API_TOKEN>/webhooks/


# list all webhooks
curl https://api.trello.com/1/members/me/tokens?webhooks=true&key=<TRELLO_API_KEY>&token=<TRELLO_API_TOKEN>

# delete existing webhook
curl -X DELETE https://api.trello.com/1/webhooks/<TRELLO_WEBHOOK_ID>?key=<TRELLO_API_KEY>&token=<TRELLO_API_TOKEN>

For more information on Trello webhooks:

• Trello Webhooks Guide
• Trello Webhooks Reference

entrello's Issues

Add new source: Daily habits retrieved from a Google Spreadsheet

Set the current date as the due date for habit cards

Account for the new duration row in habit spreadsheet

The habit spreadsheet format will be updated such that each habit will have an optional duration.

1. Spreadsheet parsing logic should be updated in order to preserve the existing functionality.
2. The optional duration values should be included in the Trello card description, without breaking the archive action handler.

Fix bug where habit cards point to the wrong cell in the spreadsheet once they get carried over a day

Get rid of config variables `todoListId` & `todayListId` and assign a list ID for each source

Instead of selecting which list to insert a card based on the due date, each source should be configured with its own target list ID.

Integrate Github Super-Linter

https://github.com/github/super-linter

Improve the concurrent fan-in implementation

Allow each source declare optional timing to get called via configuration

Some data sources might not need to be checked very frequently. For instance, it might be enough to check daily habits only once per day.

By setting an optional config parameter, we should be able to skip checking particular sources during some of the executions of entrello.

Stop hardcoding source names in configuration

Currently, only these sources are allowed in the config file:

• github_issues
• tododock
• habits

Users shouldn't have to use these hardcoded keys for configuring sources.

Update habit completion percentages every time the spreadsheet is accessed

Account for optional durations for TodoDock tasks

TodoDock tasks will contain optional duration information in the "Notes" field. The duration info, if any, should be parsed and included in the Trello card description.

Get rid of the unused "durations" row from spreadsheet layout

Integrate telegram notifications

Delete stale cards instead of archiving them

Fetching cards from each source & creating new cards should be done concurrently

Add some unit tests

Allow choosing different lists for different sources

Currently, all new cards are being created on the same list. We should be able to configure each source such that the cards created from different sources can be created on different lists.

Google Calendar Integration

Entrello should be able to fetch today's calendar events and create a card on the board for each one.

Get config file path as a program argument

Instead of always using the hardcoded "config.yml" in the current working directory, it should only be used as the default file if the config file isn't explicitly passed as a program argument.

Check status codes of responses from services and customize the error log accordingly

Replace username & password with a single secret for sever authentication

Prepend TodoDock task link to card description

Add Github issues as a data source

• Page to scrape issues: https://github.com/issues?q=is%3Aopen+is%3Aissue+archived%3Afalse+user%3Autkuufuk+assignee%3Autkuufuk
• Github API Client: https://github.com/google/go-github

Do not keep track of unconfigured labels while checking for duplicates

Avoid creating duplicate card after a GitHub issue has been renamed

Optionally delete stale cards for each source

Add a new boolean configuration flag for each source. If the flag is true, delete all existing cards with the source label if the card doesn't appear on the new list of cards to be created.

Example: If I rename a GitHub issue, there will be a card in the list on the next iteration with the new issue name. However, no card will be on the list with the old name. Therefore we should delete the existing Trello card from the board that has the old issue name.

Expose an HTTP endpoint to trigger a poll of all available sources

The request body should have the contents and structure of a valid JSON configuration file.

Make timezone configurable for habits

Add service authentication

Currently, there is no authentication between entrello and its services. Let's fix that.