Skip to main content

​
Prerequisites

  • A GitHub organization with at least one repository
  • A CI/CD pipeline that can send HTTP requests (GitHub Actions, Azure DevOps, Jenkins, etc.)

​
Step 1: Create your organization

1

Sign up

Go to app.periscope.sh and sign in with your work email. Periscope uses WorkOS for authentication — you can sign in with email, Google, or your company’s SSO provider.
2

Create an organization

After signing in, create a new organization. This is the top-level container for your team’s data. You can invite team members later from Settings.

​
Step 2: Connect GitHub

1

Install the GitHub App

Navigate to Settings > Connections and click Connect GitHub. This installs the Periscope GitHub App on your organization. You can scope it to specific repositories or grant access to all repos.
2

Select repositories to monitor

After installation, go to Settings > Repositories and toggle on the repositories you want Periscope to track. Only monitored repositories contribute to your metrics.
3

Verify PR data

Merge a pull request in one of your monitored repositories. Within a few seconds, you should see it appear in the Insights dashboard under PR activity.
Periscope captures pull_request webhook events from GitHub when a PR is closed and merged. Historical PR data is not backfilled — metrics begin from the moment you connect.

​
Step 3: Send deployment events

Deployment data is what unlocks DORA metrics. You send deployment events to Periscope from your CI/CD pipeline via a simple webhook.
1

Generate an API key

Go to Settings > Deployments and click Generate API Key. This creates an Unkey-managed API key scoped to your organization. Copy the key — you will not be able to see it again.
2

Add the webhook to your pipeline

Add an HTTP POST request to your CI/CD pipeline that fires after each deployment. Here is a minimal example:
curl -X POST https://app.periscope.sh/api/webhooks/deployments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deploymentId": "run-12345",
    "commitSha": "a1b2c3d4e5f60ab2c3d4e5f60ab2c3d4e5f60ab2",
    "environment": "production",
    "status": "success",
    "startedAt": "2024-01-15T10:30:00Z",
    "completedAt": "2024-01-15T10:35:00Z"
  }'
See the deployment webhook reference for the full payload schema and CI/CD-specific examples.
3

Verify in the dashboard

After sending a deployment, go to the Insights dashboard. You should see your deployment appear in the activity feed, and if the commitSha matches a merged PR, Periscope automatically computes lead time.

​
Step 4: Explore your metrics

With GitHub connected and deployments flowing, Periscope computes all metrics automatically:

DORA metrics

Deployment frequency, lead time, change failure rate, and MTTR.

SPACE metrics

Throughput, cycle time, and size vs time.

Insights

Contributor activity, service health, and risk signals.

MCP integration

Query metrics from your AI coding assistant.

​
Next steps