Go Makefile PLpgSQL Shell SQLPL Ruby
michaelkleinhenz feat(boardview): Board View for WIT. (#2111)
* fix(boarddef): First board definition in template.

* feat(template): Added meta state attribute to base work item type.

* feat(templates): Added board definitions to space templates.

* Added board_view.md document

to keep track of changes to the description. This can be moved to another place once this PR is ready to be merged

* fix(boards): Database layer and YAML importer completed.

* use proper highlighting

* use proper highlighting again

* fix(doc): Added description on WI retrieval.

* fix(doc): New column response.

* feat(API): Added API integration.

* fix(API): JSONAPI complete.

* fix(workitem): Added column relationship to workitems.

* fix(query): Added columnID and boardID to query language.

* Add table join for board and boardcolumns

This extends the expression compiler to find work items based on their
position in a board. All you have to do is construct a search query
based on the `board.id` or `board.name`. We then take a look at a work
item's `system.boardcolumns` fields and try to find those work items
where one of the columns is in the board you're looking for.

The constructed SQL search query operates similar to this construct:

SELECT wis.id wi_id
FROM work_items wis
	(SELECT id, board_id, jsonb_agg(id::text) AS colids FROM work_item_board_columns GROUP BY 1,2) cols
	cols.id::text IN (SELECT jsonb_array_elements_text(wis.fields->'system.boardcolumns'))
	work_item_boards board
	board.id = cols.board_id
WHERE board.id='6b930155-5d49-41f9-90a6-fe5b60be98c0' OR goo= ob;

* make format-go-code

* Fixed spacetemplate/importer Test_ImportHelper_Validate


- using correct YAML indentation
- using correct JSON keys from struct tags
- using deterministic board columns IDs derived from the board ID

* fix some of controller/TestSearchController


$ go test -v ./controller/ -run TestSearchController -update

to update the golden files.

* Update golden files

* Fix search for work items by board ID

A table join is now not only validated by the actual columns a table has
but by the columns that are explicitly allowed by a user. This allowed
us to have the board columns joined to each work item as a virtual
table in which we re-defined the "id" column to not be the ID of the
column but the ID of the board itself.

* Fix workitem/event: TestRunEventRepoBlackBoxTest

* Disable stupid checks on some search queries

* Fixup

* Fix test controller TestRunSpaceAreaREST/TestListAreasNotModifiedUsingIfNoneMatchHeader

* Make board names unique within a space template and columns unique within a board

* Fix typos and split controller tests into their own files

* some cleanup and sub tests

* Use subtests and use proper test var

* Fixup

* fix(template): Added board to agile template.

* Use workitem.SystemBoardcolumns instead of string and build map of UUID's instead of strings

* Improved tests

* fix(template): Fixed board definition for scrum, agile template.

* fix(tests): New golden files.

* fix(fixes): More fixes.

* Delete board_view.md

As requested here: #2111 (review)

* fix(fixes): More fixes.

* fix(wis): Removed non-pr code.

* fix(tests): Fixed tests.

* Run scenario tests as sub-tests for better debugging

* Ignore order of listing board in test

* Sort boards by name when listing and use numbered board names in fixture

* fixup golden files

* Use WI create environment to test board creation

See also

* Wrap errors and augment them with more information

* Added test to check on board and column lifecycle equalness

* Remove lifecycle equality checks from WILT and board and add column equality tests

* Remove lifecycle equality checks from WILC and WIL

* Remove .vs/slnx.sqlite and added .vs/ to .gitignore

* fix(typos): Fixed typos.

* Remove not needed test suite functions

from controller/logout_test.go

* Fix column order and add unique index

#2111 (comment)

* Fix Test_ImportHelper_Validate

* Rebuilt golden files

* Not letting SQL stop us from using "order" as a board column attribute

* fixup

* Make contextType an enum (for now)

See #2111 (comment)

* Fix type group IDs


* fix(fixs): More fixes.

* Update golden files to match the context values in legacy.yaml

* fix(json): Fixes json values in board definitions.

* fix(template): Removed rewritable values flag from metastate.
Latest commit a4d9061 Jul 13, 2018
Failed to load latest commit information.
.github Fix minor typos and grammar in contributing.md (#2120) Jun 18, 2018
.make Change test file exclude pattern (#2135) Jun 28, 2018
account Integrate call to analytics for cve-scanning (#2144) Jul 9, 2018
application feat(boardview): Board View for WIT. (#2111) Jul 13, 2018
area Refactor DB Test Suite (#2137) Jul 3, 2018
auth Fix space creation (#2027) Apr 19, 2018
closeable Fix nil pointer dereference when closing resource (OSIO#2986) (#2001) Apr 12, 2018
codebase Don't check response body in gemini client (#2159) Jul 10, 2018
comment Refactor DB Test Suite (#2137) Jul 3, 2018
configuration Integrate call to analytics for cve-scanning (#2144) Jul 9, 2018
controller feat(boardview): Board View for WIT. (#2111) Jul 13, 2018
convert Cleanup using gosimple (#1489) Jul 19, 2017
criteria search in foreign tables (#1912) Feb 26, 2018
design feat(boardview): Board View for WIT. (#2111) Jul 13, 2018
docs feat(boardview): Board View for WIT. (#2111) Jul 13, 2018
errors Fix for "url.Error: Delete http://f8tenant:80/api/tenant?remove=false… May 15, 2018
examples WIP: Space templates (#1148) Apr 22, 2018
goamiddleware Some cleanups suggested by golint (#1778) Nov 21, 2017
goasupport Work item events (#1959) May 25, 2018
gormapplication feat(boardview): Board View for WIT. (#2111) Jul 13, 2018
gormsupport WIP: Space templates (#1148) Apr 22, 2018
gormtestsupport Refactor DB Test Suite (#2137) Jul 3, 2018
id feat(childcomments): Added child comments feature. (#2101) May 28, 2018
iteration Iteration.Root() no longer returns an iteration if it doesn't actuall… Jul 3, 2018
jsonapi 'errors.DataConflictError' for duplicate iteration creation causes 50… Apr 24, 2018
kubernetes Consider all builds when looking for deployment config name (#2139) Jul 4, 2018
label Refactor DB Test Suite (#2137) Jul 3, 2018
log fix format specifiers in errors (#2048) Jun 14, 2018
login feat(childcomments): Added child comments feature. (#2101) May 28, 2018
metric Add goa-middleware to record metric for WIT requests (#1903) Mar 27, 2018
migration feat(boardview): Board View for WIT. (#2111) Jul 13, 2018
minishift Use container images from quay.io instead of docker hub (#2145) Jul 4, 2018
models Cleanup using gosimple (#1489) Jul 19, 2017
notification Forward X-Request-ID header to Notification call (#1988) Apr 8, 2018
openshift Integrate call to analytics for cve-scanning (#2144) Jul 9, 2018
path WIP: Space templates (#1148) Apr 22, 2018
ptr Save Create Iteration with Force Active (#1978) Apr 5, 2018
query Revert "List work items part of child iterations (#2146)" (#2168) Jul 13, 2018
remoteworkitem Refactor DB Test Suite (#2137) Jul 3, 2018
rendering GH-style checkboxes for markdown (#2071) May 4, 2018
resource WIP: Space templates (#1148) Apr 22, 2018
rest Switch permission check from Keycloak to Auth service (#2129) Jun 27, 2018
search feat(boardview): Board View for WIT. (#2111) Jul 13, 2018
sentry Use appropriate user id in sentry (#1970) Apr 10, 2018
space Refactor DB Test Suite (#2137) Jul 3, 2018
spacetemplate feat(boardview): Board View for WIT. (#2111) Jul 13, 2018
test feat(boardview): Board View for WIT. (#2111) Jul 13, 2018
token Migrate to `dep` for dependency management (OSIO#2873) (#2011) Apr 16, 2018
tool/wit-cli Renamed ENV vars to use F8 prefix and binary from alm to wit (#1451) Jun 29, 2017
workitem feat(boardview): Board View for WIT. (#2111) Jul 13, 2018
.codecov.yml /apps API implementation (#1655) (deployments page API - initial vers… Jan 15, 2018
.dockerignore Migrate to `dep` for dependency management (OSIO#2873) (#2011) Apr 16, 2018
.gitignore feat(boardview): Board View for WIT. (#2111) Jul 13, 2018
.gofmt_exclude WIP: Space templates (#1148) Apr 22, 2018
.golint_exclude WIP: Space templates (#1148) Apr 22, 2018
.pre-push Fix #856 Use .git/hooks/pre-push hook to check for correctly formatt… Aug 14, 2017
Dockerfile.builder Remove build dependency on `hg`/`mercurial` (#2023) (#2025) Apr 18, 2018
Dockerfile.deploy move COPY cmds in Dockerfile.deploy to end (#1905) Feb 28, 2018
Dockerfile.deploy.rhel Move to Quay.io (#2116) Jun 15, 2018
Gopkg.lock feat(spacetemplates): New Agile template (#2109) Jun 12, 2018
Gopkg.toml Tenant Service 404 cause 500 in Core API #2866 (#2022) May 4, 2018
LICENSE Initial commit Mar 19, 2016
Makefile Changed SHA checksum for dep-darwin-amd64 and setting UNAME_S variable ( Jul 11, 2018
README.adoc docs: update go dependency tool from glide to dep (#2042) Apr 24, 2018
check_hosts.sh Isolated setup & ability to use tags from snapshots for WIT & AUTH (#… Nov 30, 2017
cico_build_deploy.sh Build on RHEL (#2004) Apr 27, 2018
cico_run_coverage.sh Use Go 1.10 version from upstream when running tests with coverage (#… Feb 19, 2018
cico_run_go_benchmarks.sh Added ci job to run golang benchmarks (#1551) Aug 1, 2017
cico_run_tests.sh Snapshot docker image per PR push (#2020) Apr 23, 2018
cico_setup.sh Move to Quay.io (#2116) Jun 15, 2018
config.yaml Add multicluster support to /deployments API (#1883) Apr 23, 2018
docker-compose.macos.yml Use container images from quay.io instead of docker hub (#2145) Jul 4, 2018
docker-compose.yml Use container images from quay.io instead of docker hub (#2145) Jul 4, 2018
main.go feat(boardview): Board View for WIT. (#2111) Jul 13, 2018
pcp.repo BIOHAZARD WARNING - PMCD IMPLANT (#1157) Apr 12, 2017
runner.conf Go vendoring with glide (#15) Jul 13, 2016
test-keeper.yaml Build on RHEL (#2004) Apr 27, 2018
test-keeper.yml Migrate to `dep` for dependency management (OSIO#2873) (#2011) Apr 16, 2018
wit+pmcd.sh fix pcp pmdaprometheus configuration line (#1975) Apr 4, 2018


Fabric8 Work Item Tracker

Jenkins Go Report Card GoDoc Codecov.io

Work Items describe and keep track of work that needs to be done. A user can be assigned to a Work Item. Each Work Item must be attached to a Collaboration Space and an Area (assigned by default). This can be used to model bugs, tasks, features, ideas, and more.

1. Building from source

The following guide is mainly targeted towards a Linux or Mac OSX development machine. If you are on Windows, we recommend to take a look at Getting started with fabric8-wit development on Windows.

1.1. Prerequisites

You need to install:

  • go (>= v1.8)

  • git

  • mercurial

  • make

1.1.1. Check your Go version

Run the following command to find out your Go version.

$ go version

You must at least have Go version 1.8.

See Fetch dependencies to see an explanaition on how we deal with dependencies.

1.1.2. Install dep

This project uses dep as a package manager for Go. Running the make deps command will install dep in $GOPATH/bin if it’s not already available on your system.

1.2. Get the code

Assuming you have Go installed and configured (have $GOPATH setup and pointing to a single directory) here is how to build.

Check out the code

$ git clone https://github.com/fabric8-services/fabric8-wit $GOPATH/src/github.com/fabric8-services/fabric8-wit

1.3. Build

Like most other projects, this one depends on various other projects that need to be downloaded.

We also generate some code from design files that shall make it into our final artifacts.

To fetch the dependencies, generate code and finally build the project you can type make in a freshly clone repository of this project.

$ cd $GOPATH/src/github.com/fabric8-services/fabric8-wit
$ make

1.3.1. Special make targets

There is no need to fetch the dependencies, or re-generate code every time you want to compile. That’s why we offer special make targets for these topics:

Fetch dependencies

This will download all the dependencies for this project inside a directory called vendor. This way we can ensure that every developer and our CI system is using the same version.

$ cd $GOPATH/src/github.com/fabric8-services/fabric8-wit
$ make deps

For dependency management of go packages we use dep. The file Gopkg.toml contains all dependencies. If you want to understand the format for this file, look here.

Generate GOA sources

You need to run this command if you just checked out the code and later if you’ve modified the designs.

$ cd $GOPATH/src/github.com/fabric8-services/fabric8-wit
$ make generate

If you want to just build the ALM server and client, run make build.

$ cd $GOPATH/src/github.com/fabric8-services/fabric8-wit
$ make build

This removes all downloaded dependencies, all generated code and compiled artifacts.

$ cd $GOPATH/src/github.com/fabric8-services/fabric8-wit
$ make clean

Here’s how to run all available tests. All tests will check all Go packages except those in the vendor/ directory. Make sure you have docker and docker-compose available.

Setting up test environment - make integration-test-env-prepare

Tear test environment down - make integration-test-env-tear-down


Unit tests have the minimum requirement on time and environment setup.

$ cd $GOPATH/src/github.com/fabric8-services/fabric8-wit
$ make test-unit

Integration tests demand more setup (i.e. the PostgreSQL DB must be already running) and probably time. We recommend that you use docker-compose up -d db.

$ cd $GOPATH/src/github.com/fabric8-services/fabric8-wit
$ make test-integration

To run both, the unit and the integration tests you can run

$ cd $GOPATH/src/github.com/fabric8-services/fabric8-wit
$ make test-all

To visualize the coverage of unit, integration, or all tests you can run these commands:

  • $ make coverage-unit

  • $ make coverage-integration

  • $ make coverage-all

If the tests (see Tests) have not yet run, or if the sources have changed since the last time the tests ran, they will be re-run to produce up to date coverage profiles.

Each of the above tests (see Tests) produces a coverage profile by default. Those coverage files are available under


Here’s how the <placeholders> expand


something like github.com/fabric8-services/fabric8-wit/models


unit or integration


Sets the mode for coverage analysis for the packages being tested. Possible values for <mode> are set (the default), count, or atomic and they directly relate to the output of go test --help.

  • set: bool: does this statement run?

  • count: int: how many times does this statement run?

  • atomic: int: count, but correct in multithreaded tests; significantly more expensive.

In addition to all individual coverage information for each package, we also create three more files:


This file collects all the coverage profiles for all unit tests.


This file collects all the coverage profiles for all integration tests.


This file is the merge result of the two afore mentioned files and thus gives coverage information for all tests.

2. Build through minishift

There is a separate documentation for building WIT using minishift

3. Configuration file

If no configuration file is specified when the core is started, these are the defaults.

# Postgres configuration

postgres.host: localhost
postgres.port: 5432
postgres.user: postgres
postgres.password: mysecretpassword
postgres.database: postgres
postgres.sslmode: disable
# The amount of time in seconds before the connection times out
postgres.connection.timeout: 5
# Duration to wait before trying to connect again
postgres.connection.retrysleep: 1s

# HTTP configuration


# Misc.

# Enable development related features, e.g. token generation endpoint
developer.mode.enabled: false

# Whether you want to create the common work item types such as bug, feature, ...
populate.commontypes: true

# -----------------------------
# Authentication configuration
# -----------------------------

token.privatekey : >
                    -----BEGIN RSA PRIVATE KEY-----
                    -----END RSA PRIVATE KEY-----

token.publickey : >
                    -----BEGIN PUBLIC KEY-----
                    -----END PUBLIC KEY-----

# ----------------------------
# Github OAuth2 configuration
# ----------------------------

github.client.id : 875da0d2113ba0a6951d
github.secret : 2fe6736e90a9283036a37059d75ac0c82f4f5288

Although this is a YAML file, we highly suggest to stick to this rather lenghty notation instead of nesting structs.

To override configuration values using environment variables, use the prefix F8_ and replace the dots in the variables names with underscores.

For example to override postgres.password, set the environment variable F8_POSTGRES_PASSWORD to the value of you liking.

config.yaml is not processed by default. In order to use it, the following environment variable must be set export F8_CONFIG_FILE_PATH="config.yaml"
Environment variables override the default values and the ones you’ve set in your config file.

3.1. Development

Only files ./*.go, ./design/*.go, ./models/*.go and ./tool/wit-cli/main.go should be edited.

These files and directory are generated:

  • ./app/

  • ./assets/js/

  • ./client/

  • ./swagger/

  • ./tool/cli/

  • ./bindata_asstfs.go

4. Developer setup

Start up dependent docker services using docker-compose and runs auto reload on source change tool fresh.

$ cd $GOPATH/src/github.com/fabric8-services/fabric8-wit
$ make dev

The above steps start the API Server on port 8080.

Test out the build by executing CLI commands in a different terminal.

The CLI needs the API Server which was started on executing make dev to be up and running. Please do not kill the process. Alternatively if you haven’t run make dev you could just start the server by running ./bin/alm.

Generate a token for future use.

./bin/wit-cli generate login -H localhost:8080 --pp

You should get Token in response, save this token in your favourite editor as you need to use this token for POST API calls

Create a work item type (using above token).

./bin/wit-cli create workitemtype --key "<GENERATED TOKEN>" --payload '{"fields":{"system.owner":{"type":{"kind":"user"},"required":true},"system.state":{"type":{"kind":"string"},"required":false}},"name":"Epic"}' -H localhost:8080 --pp

Note: Work Item Type Name is unique. If one tries to create another work item type with same name, error will be trown.

Retrieve the work item type.

$ ./bin/wit-cli show workitemtype --name "Epic" -H localhost:8080

List all available work item types.

$ ./bin/wit-cli list workitemtype -H localhost:8080 --pp

Create a work item.

Based on WorkItemType created above, we can create WorkItem. We need to use name of work item type in the type field below.

$ ./bin/wit-cli create workitem --key "<GENERATED TOKEN>" --payload '{"type": "Epic", "fields": { "system.owner": "tmaeder", "system.state": "open" }}' -H localhost:8080

Retrieve the work item.

$ ./bin/wit-cli show workitem --id 1 -H localhost:8080 --pp

4.1. Reset Database

The database are kept in a docker container that gets reused between restarts. Thus restarts will not clear out the database.

To clear out the database kill the database like this:

$ docker kill fabric8wit_db_1 && docker rm fabric8wit_db_1

In case you have mulitple fabric8* running use docker ps to locate the container name.

5. Debugging

System defined Work Item Types are

  • userstory

  • valueproposition

  • fundamental

  • experience

  • feature

  • bug

Use any one of above to create Work Item based on that type. Following example creates a Work Item of type userstory

$ ./bin/wit-cli create workitem --key "<GENERATED TOKEN>" --payload '{ "data": { "attributes": { "system.owner": "tmaeder", "system.state": "open", "system.title": "Example of an Epic", "version": "1" }, "relationships": { "baseType": { "data": { "id": "Epic", "type": "workitemtypes" } } }, "type": "workitems" } }' -H localhost:8080

In response you should get ID of created item, using that you can retrieve the work item.

$ ./bin/wit-cli show workitem --id <ID> -H localhost:8080 --pp

6. Swagger API

A browsable documentation for our API is available with goa Swagger Generator. It reflects the latest state of the master branch.

7. Prod preview setup

In order to setup wit to work against prod preview the following environment variables must be set:


  • export F8_OPENSHIFT_TENANT_MASTERURL="https://console.free-stg.openshift.com/"

  • export F8_KEYCLOAK_REALM="fabric8"

  • export F8_CONFIG_FILE_PATH="config.yaml"

Also, F8_TENANT_SERVICEURL env var must be set and point to the prod-preview fabric8-tenant endpoint. However, there is no publicly available route for it and one should oc login to the prod-preview OpenShift Dedicated cluster and use port forwarding for fabric8-tenant pod:

$ oc port-forward <f8tenant-pod> <local-port>:8080
  • export F8_TENANT_SERVICEURL="http://localhost:<local-port>/"

8. che-starter setup

che-starter endpoint can be configure via the following environment variable:

  • export F8_CHESTARTERURL="http://localhost:10000/"