Skip to content
Merged
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
191 changes: 191 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,191 @@
name: CI

on:
pull_request:
branches: [main]
workflow_dispatch:

# The workflow needs nothing but the source; it never touches the GitHub API
# beyond checkout, and it needs no secrets, so pull requests from forks work.
permissions:
contents: read

# A new push to a pull request supersedes the run already in flight.
concurrency:
group: ci-${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true

jobs:
test:
name: Go tests
runs-on: ubuntu-latest
timeout-minutes: 15

# The PostgreSQL integration tests skip themselves when TEST_DATABASE_URL is
# unset. CI provides a real database so they actually run.
services:
postgres:
image: postgres:17-alpine
env:
POSTGRES_USER: devpulse
POSTGRES_PASSWORD: devpulse
POSTGRES_DB: devpulse_test
ports:
- 5432:5432
options: >-
--health-cmd "pg_isready -U devpulse -d devpulse_test"
--health-interval 5s
--health-timeout 5s
--health-retries 10

steps:
- name: Check out the repository
uses: actions/checkout@v4

- name: Set up Go
uses: actions/setup-go@v5
with:
go-version-file: go.mod
check-latest: true

- name: Check formatting
run: |
unformatted=$(gofmt -l .)
if [ -n "$unformatted" ]; then
echo "::error::These files are not gofmt-formatted. Run 'gofmt -w .':"
echo "$unformatted"
gofmt -d .
exit 1
fi
echo "All files are gofmt-formatted."

- name: Check that go.mod and go.sum are tidy
run: |
go mod tidy
if ! git diff --quiet --exit-code go.mod go.sum; then
echo "::error::go.mod or go.sum is out of date. Run 'go mod tidy' and commit the result."
git diff go.mod go.sum
exit 1
fi
echo "Module files are tidy."

- name: Build
run: go build ./...

- name: Vet
run: go vet ./...

- name: Test
env:
# Enables the PostgreSQL integration tests in internal/database and
# internal/http instead of letting them skip.
TEST_DATABASE_URL: postgres://devpulse:devpulse@localhost:5432/devpulse_test?sslmode=disable
run: go test -race -count=1 -coverprofile=coverage.out ./...

- name: Coverage summary
if: always()
run: |
if [ -f coverage.out ]; then
go tool cover -func=coverage.out | tail -1
fi

- name: Upload coverage profile
if: always()
uses: actions/upload-artifact@v4
with:
name: coverage
path: coverage.out
if-no-files-found: ignore
retention-days: 7

docker:
name: Docker image and stack
runs-on: ubuntu-latest
timeout-minutes: 20

steps:
- name: Check out the repository
uses: actions/checkout@v4

- name: Validate the Compose configuration
run: |
# `docker compose config` needs the env file to exist; the example
# values are placeholders and nothing is started by this step.
cp .env.example .env
docker compose config -q
echo "Compose configuration is valid."

- name: Write the smoke-test environment
run: |
# A placeholder token makes synchronization fail with 401, which is
# deliberate: the web application must keep serving regardless.
printf '%s\n' \
'GITHUB_TOKEN=placeholder-not-a-real-token' \
'GITHUB_ORG=devpulse-ci-smoke-test' \
'SYNC_INTERVAL=30m' \
'HISTORY_MONTHS=1' > .env

- name: Build the image
env:
VERSION: ci-${{ github.sha }}
run: docker compose build

- name: Start the stack
run: docker compose up -d

- name: Wait for the application to become healthy
run: |
for attempt in $(seq 1 60); do
if curl -fsS http://localhost:8080/health >/dev/null 2>&1; then
echo "Healthy after ${attempt} attempt(s)."
exit 0
fi
sleep 2
done
echo "::error::The application never became healthy."
exit 1

- name: Smoke test the running application
run: |
set -euo pipefail

echo "--- /health ---"
curl -fsS http://localhost:8080/health
echo
echo "--- /ready ---"
curl -fsS http://localhost:8080/ready
echo

# Migrations must have been applied before requests are served.
curl -fsS http://localhost:8080/ready | grep -q 'schema_version' \
|| { echo "::error::/ready does not report a schema version"; exit 1; }

echo "--- pages ---"
for path in "/" "/contributors" "/repositories" "/status" \
"/contributors?period=7d" "/repositories?period=custom&from=2026-01-01&to=2026-03-31"; do
code=$(curl -s -o /dev/null -w '%{http_code}' "http://localhost:8080${path}")
printf '%-70s %s\n' "${path}" "${code}"
[ "${code}" = "200" ] || { echo "::error::${path} returned ${code}"; exit 1; }
done

echo "--- PDF report ---"
curl -fsS -o report.pdf "http://localhost:8080/report.pdf?period=30d"
head -c 5 report.pdf | grep -q '%PDF-' \
|| { echo "::error::/report.pdf did not return a PDF"; exit 1; }
echo "report.pdf is $(wc -c < report.pdf) bytes"

- name: Check that the token never leaks into the logs
run: |
if docker compose logs 2>&1 | grep -q 'placeholder-not-a-real-token'; then
echo "::error::The GitHub token appeared in the application logs."
exit 1
fi
echo "The token does not appear in any log line."

- name: Show container logs on failure
if: failure()
run: docker compose logs --no-color

- name: Tear down
if: always()
run: docker compose down -v
24 changes: 24 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# DevPulse

[![CI](https://github.com/relaxart/dev-pulse/actions/workflows/ci.yml/badge.svg)](https://github.com/relaxart/dev-pulse/actions/workflows/ci.yml)

GitHub engineering analytics for **one** organization.

DevPulse collects commits, pull requests and reviews from the GitHub GraphQL
Expand Down Expand Up @@ -473,6 +475,9 @@ Reports are built from the same PostgreSQL aggregates as the dashboard, honour

The file is named `devpulse-<org>-<from>-to-<to>.pdf`.

Before the first successful synchronization the report is still a valid document;
it renders empty and says so, rather than returning an error.

### Limitation

The PDF uses the standard built-in fonts, which cover Latin-1. A display name in
Expand Down Expand Up @@ -690,6 +695,25 @@ an end-to-end check that neither rendering a page nor generating a report ever
calls GitHub. Collector tests run
against recorded GraphQL responses — no network access required.

### Continuous integration

`.github/workflows/ci.yml` runs on every pull request against `main`, and can be
started by hand from the Actions tab. It needs no secrets, so pull requests from
forks work.

**Go tests** — `gofmt` check, `go mod tidy` check (fails if `go.mod`/`go.sum`
would change), `go build`, `go vet`, then `go test -race` against a PostgreSQL
service container, so the integration tests actually run instead of skipping.
The coverage profile is uploaded as a build artifact.

**Docker image and stack** — validates `docker compose config`, builds the image,
starts the full stack with a placeholder token and checks that `/health` and
`/ready` answer, that `/ready` reports an applied schema version, that every page
and a PDF report return `200`, and that the token never appears in the container
logs. The placeholder token makes synchronization fail on purpose: the web
application must keep serving regardless. Container logs are dumped if anything
fails.

Building the image:

```bash
Expand Down
33 changes: 18 additions & 15 deletions internal/http/handlers.go
Original file line number Diff line number Diff line change
Expand Up @@ -537,22 +537,25 @@ func (s *Server) handleReport(w http.ResponseWriter, r *http.Request) {
if !ok {
return
}
// Before the first successful synchronization there is no organization row
// and nothing to query. Produce an empty but valid report that says so,
// rather than a 404: every other page renders in that state too.
var data *report.Data
if pc.Org == nil {
s.notFound(w, r, pc.Layout,
"There is nothing to report yet - the first synchronization has not produced any data.")
return
}

data, err := report.Collect(r.Context(), s.db, report.Request{
Organization: s.cfg.GitHubOrg,
Filter: pc.Filter,
Range: pc.Layout.Range,
SortKey: r.URL.Query().Get("sort"),
LastSync: pc.Org.LastSyncedAt,
})
if err != nil {
s.serverError(w, r, err)
return
data = report.Empty(s.cfg.GitHubOrg, pc.Layout.Range)
} else {
var err error
data, err = report.Collect(r.Context(), s.db, report.Request{
Organization: s.cfg.GitHubOrg,
Filter: pc.Filter,
Range: pc.Layout.Range,
SortKey: r.URL.Query().Get("sort"),
LastSync: pc.Org.LastSyncedAt,
})
if err != nil {
s.serverError(w, r, err)
return
}
}

pdf, err := report.Render(data)
Expand Down
26 changes: 26 additions & 0 deletions internal/http/handlers_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -456,3 +456,29 @@ func TestReportMenuIsOfferedOnEveryPage(t *testing.T) {
t.Error("the report link should preserve the selected sort key")
}
}

// A deployment whose first synchronization has not produced data yet must still
// return a readable report rather than a 404: every other page renders in that
// state, and a fresh install is exactly when someone clicks around.
func TestReportBeforeTheFirstSyncIsAnEmptyDocumentNotAnError(t *testing.T) {
ts := newTestServer(t)
if _, err := ts.db.Pool.Exec(context.Background(),
`TRUNCATE contributor_daily_stats, pull_request_reviews, pull_requests, commits,
repositories, contributors, sync_runs, organizations RESTART IDENTITY CASCADE`); err != nil {
t.Fatal(err)
}

w := ts.get(t, "/report.pdf?period=30d")
if w.Code != http.StatusOK {
t.Fatalf("GET /report.pdf on an unsynchronized instance = %d, want 200", w.Code)
}
if !bytes.HasPrefix(w.Body.Bytes(), []byte("%PDF-")) {
t.Error("an unsynchronized instance did not return a PDF")
}
if ct := w.Header().Get("Content-Type"); ct != "application/pdf" {
t.Errorf("Content-Type = %q", ct)
}
if *ts.githubHits != 0 {
t.Fatal("an empty report must not reach for GitHub to fill itself in")
}
}
9 changes: 9 additions & 0 deletions internal/report/pdf.go
Original file line number Diff line number Diff line change
Expand Up @@ -130,6 +130,15 @@ func (r *renderer) title() {
"", 1, "L", false, 0, "")
}

if r.data.NoData {
p.SetFont(fontFamily, "B", 9)
r.setColor(colorDel)
p.CellFormat(contentW, 5,
"No data has been synchronized yet, so this report is empty. "+
"Check the status page for synchronization errors.",
"", 1, "L", false, 0, "")
}

p.Ln(2)
r.rule()
p.Ln(3)
Expand Down
21 changes: 21 additions & 0 deletions internal/report/report.go
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,27 @@ type Data struct {
// Truncated reports say so on the page rather than silently cutting off.
ContributorsTruncated bool
RepositoriesTruncated bool

// NoData marks a report for an organization that has never been
// synchronized, so the document can say so instead of looking like a period
// with genuinely zero activity.
NoData bool
}

// Empty builds a report for an organization that has not been synchronized yet.
// A fresh deployment should still produce a readable document rather than an
// error, exactly as the dashboard renders with a "no data yet" banner.
func Empty(organization string, rng metrics.Range) *Data {
return &Data{
Organization: organization,
Range: rng,
Previous: rng.PreviousRange(),
Sort: metrics.ResolveSort(""),
GeneratedAt: time.Now().UTC(),
Granularity: rng.Granularity(),
Metrics: metrics.RankingMetrics(),
NoData: true,
}
}

// Collect assembles the report data from PostgreSQL.
Expand Down
23 changes: 23 additions & 0 deletions internal/report/report_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -415,3 +415,26 @@ func TestDiffCountersRenderZeroPlainly(t *testing.T) {
}
}
}

func TestEmptyReportIsStillAValidDocument(t *testing.T) {
rng, _ := metrics.ResolveRange(metrics.Period30d, "", "", time.Date(2026, 9, 20, 12, 0, 0, 0, time.UTC))
data := Empty("acme", rng)

if !data.NoData {
t.Error("an unsynchronized report must be flagged, so it is not mistaken for a quiet period")
}
if data.Sort.Key != metrics.DefaultSort {
t.Errorf("Sort = %q, want the default", data.Sort.Key)
}
if !strings.HasPrefix(data.Filename(), "devpulse-acme-") {
t.Errorf("Filename() = %q", data.Filename())
}

out, err := Render(data)
if err != nil {
t.Fatalf("an empty report must still render: %v", err)
}
if !bytes.HasPrefix(out, []byte("%PDF-")) {
t.Error("the empty report is not a PDF")
}
}
Loading