Skip to main content
API docs by Redocly

Woodpecker CI API (dev)

Download OpenAPI specification:Download

URL: https://woodpecker-ci.org/

Woodpecker is a simple yet powerful CI/CD engine with great extensibility. To get a personal access token (PAT) for authentication, please log in your Woodpecker server, and go to you personal profile page, by clicking the user icon at the top right.

Agents

List agents

query Parameters
page
integer
Default: 1

for response pagination, page offset number

perPage
integer
Default: 50

for response pagination, max items per page

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new agent

Creates a new agent with a random token

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Request Body schema: application/json
required

the agent's data (only 'name' and 'no_schedule' are read)

backend
string
capacity
integer
created
integer
id
integer
last_contact
integer
name
string
no_schedule
boolean
owner_id
integer
platform
string
token
string
updated
integer
version
string

Responses

Request samples

Content type
application/json
{
  • "backend": "string",
  • "capacity": 0,
  • "created": 0,
  • "id": 0,
  • "last_contact": 0,
  • "name": "string",
  • "no_schedule": true,
  • "owner_id": 0,
  • "platform": "string",
  • "token": "string",
  • "updated": 0,
  • "version": "string"
}

Response samples

Content type
application/json
{
  • "backend": "string",
  • "capacity": 0,
  • "created": 0,
  • "id": 0,
  • "last_contact": 0,
  • "name": "string",
  • "no_schedule": true,
  • "owner_id": 0,
  • "platform": "string",
  • "token": "string",
  • "updated": 0,
  • "version": "string"
}

Delete an agent

path Parameters
agent
required
integer

the agent's id

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Get an agent

path Parameters
agent
required
integer

the agent's id

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
{
  • "backend": "string",
  • "capacity": 0,
  • "created": 0,
  • "id": 0,
  • "last_contact": 0,
  • "name": "string",
  • "no_schedule": true,
  • "owner_id": 0,
  • "platform": "string",
  • "token": "string",
  • "updated": 0,
  • "version": "string"
}

Update an agent

path Parameters
agent
required
integer

the agent's id

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Request Body schema: application/json
required

the agent's data

backend
string
capacity
integer
created
integer
id
integer
last_contact
integer
name
string
no_schedule
boolean
owner_id
integer
platform
string
token
string
updated
integer
version
string

Responses

Request samples

Content type
application/json
{
  • "backend": "string",
  • "capacity": 0,
  • "created": 0,
  • "id": 0,
  • "last_contact": 0,
  • "name": "string",
  • "no_schedule": true,
  • "owner_id": 0,
  • "platform": "string",
  • "token": "string",
  • "updated": 0,
  • "version": "string"
}

Response samples

Content type
application/json
{
  • "backend": "string",
  • "capacity": 0,
  • "created": 0,
  • "id": 0,
  • "last_contact": 0,
  • "name": "string",
  • "no_schedule": true,
  • "owner_id": 0,
  • "platform": "string",
  • "token": "string",
  • "updated": 0,
  • "version": "string"
}

List agent tasks

path Parameters
agent
required
integer

the agent's id

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Badges

Provide pipeline status information to the CCMenu tool

CCMenu displays the pipeline status of projects on a CI server as an item in the Mac's menu bar. More details on how to install, you can find at http://ccmenu.org/ The response format adheres to CCTray v1 Specification, https://cctray.org/v1/

path Parameters
repo_id
required
integer

the repository id

Responses

Get status of pipeline as SVG badge

path Parameters
repo_id
required
integer

the repository id

Responses

Process profiling and debugging

List available pprof profiles (HTML)

Only available, when server was started with WOODPECKER_LOG_LEVEL=debug

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Get pprof stack traces that led to blocking on synchronization primitives

Only available, when server was started with WOODPECKER_LOG_LEVEL=debug

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Get the command line invocation of the current program

Only available, when server was started with WOODPECKER_LOG_LEVEL=debug

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Get pprof stack traces of all current goroutines

Only available, when server was started with WOODPECKER_LOG_LEVEL=debug

query Parameters
debug
integer
Default: 1

Use debug=2 as a query parameter to export in the same format as an un-recovered panic

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Get pprof heap dump, a sampling of memory allocations of live objects

Only available, when server was started with WOODPECKER_LOG_LEVEL=debug

query Parameters
gc
string
Default: ""

You can specify gc=heap to run GC before taking the heap sample

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Get pprof CPU profile

Only available, when server was started with WOODPECKER_LOG_LEVEL=debug After you get the profile file, use the go tool pprof command to investigate the profile.

query Parameters
seconds
required
integer

You can specify the duration in the seconds GET parameter.

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Get pprof program counters mapping to function names

Only available, when server was started with WOODPECKER_LOG_LEVEL=debug Looks up the program counters listed in the request, responding with a table mapping program counters to function names. The requested program counters can be provided via GET + query parameters, or POST + body parameters. Program counters shall be space delimited.

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Get pprof program counters mapping to function names

Only available, when server was started with WOODPECKER_LOG_LEVEL=debug Looks up the program counters listed in the request, responding with a table mapping program counters to function names. The requested program counters can be provided via GET + query parameters, or POST + body parameters. Program counters shall be space delimited.

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Get pprof stack traces that led to the creation of new OS threads

Only available, when server was started with WOODPECKER_LOG_LEVEL=debug

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Get a trace of execution of the current program

Only available, when server was started with WOODPECKER_LOG_LEVEL=debug After you get the profile file, use the go tool pprof command to investigate the profile.

query Parameters
seconds
required
integer

You can specify the duration in the seconds GET parameter.

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

System

Health information

If everything is fine, just a 204 will be returned, a 500 signals server state is unhealthy.

Responses

Incoming webhook from forge

Request Body schema: application/json
required

the webhook payload; forge is automatically detected

object

Responses

Request samples

Content type
application/json
{ }

Current log level

Endpoint returns the current logging level. Requires admin rights.

Responses

Response samples

Content type
application/json
{
  • "log-level": "string"
}

Set log level

Endpoint sets the current logging level. Requires admin rights.

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Request Body schema: application/json
required

the new log level, one of <debug,trace,info,warn,error,fatal,panic,disabled>

log-level
string

Responses

Request samples

Content type
application/json
{
  • "log-level": "string"
}

Response samples

Content type
application/json
{
  • "log-level": "string"
}

Get server's signature public key

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Get version

Endpoint returns the server version and build information.

Responses

Response samples

Content type
application/json
{
  • "source": "string",
  • "version": "string"
}

Organizations

Lookup an organization by full name

path Parameters
org_full_name
required
string

the organizations full name / slug

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
{
  • "forge_id": 0,
  • "id": 0,
  • "is_user": true,
  • "name": "string"
}

Orgs

List organizations

Returns all registered orgs in the system. Requires admin rights.

query Parameters
page
integer
Default: 1

for response pagination, page offset number

perPage
integer
Default: 50

for response pagination, max items per page

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete an organization

Deletes the given org. Requires admin rights.

path Parameters
id
required
string

the org's id

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Organization

Get an organization

path Parameters
org_id
required
string

the organziation's id

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Organization permissions

Get the permissions of the currently authenticated user for the given organization

path Parameters
org_id
required
string

the organziation's id

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Organization secrets

List organization secrets

path Parameters
org_id
required
string

the org's id

query Parameters
page
integer
Default: 1

for response pagination, page offset number

perPage
integer
Default: 50

for response pagination, max items per page

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create an organization secret

path Parameters
org_id
required
string

the org's id

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Request Body schema: application/json
required

the new secret

events
Array of strings (WebhookEvent)
Items Enum: "push" "pull_request" "pull_request_closed" "tag" "release" "deployment" "cron" "manual"
id
integer
images
Array of strings
name
string
org_id
integer
repo_id
integer
value
string

Responses

Request samples

Content type
application/json
{
  • "events": [
    ],
  • "id": 0,
  • "images": [
    ],
  • "name": "string",
  • "org_id": 0,
  • "repo_id": 0,
  • "value": "string"
}

Response samples

Content type
application/json
{
  • "events": [
    ],
  • "id": 0,
  • "images": [
    ],
  • "name": "string",
  • "org_id": 0,
  • "repo_id": 0,
  • "value": "string"
}

Delete an organization secret by name

path Parameters
org_id
required
string

the org's id

secret
required
string

the secret's name

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Get a organization secret by name

path Parameters
org_id
required
string

the org's id

secret
required
string

the secret's name

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
{
  • "events": [
    ],
  • "id": 0,
  • "images": [
    ],
  • "name": "string",
  • "org_id": 0,
  • "repo_id": 0,
  • "value": "string"
}

Update an organization secret by name

path Parameters
org_id
required
string

the org's id

secret
required
string

the secret's name

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Request Body schema: application/json
required

the update secret data

events
Array of strings (WebhookEvent)
Items Enum: "push" "pull_request" "pull_request_closed" "tag" "release" "deployment" "cron" "manual"
id
integer
images
Array of strings
name
string
org_id
integer
repo_id
integer
value
string

Responses

Request samples

Content type
application/json
{
  • "events": [
    ],
  • "id": 0,
  • "images": [
    ],
  • "name": "string",
  • "org_id": 0,
  • "repo_id": 0,
  • "value": "string"
}

Response samples

Content type
application/json
{
  • "events": [
    ],
  • "id": 0,
  • "images": [
    ],
  • "name": "string",
  • "org_id": 0,
  • "repo_id": 0,
  • "value": "string"
}

Pipeline queues

List pipelines in queue

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get pipeline queue information

TODO: link the InfoT response object - this is blocked, until the swaggo/swag tool dependency is v1.18.12 or newer

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Block til pipeline queue has a running item

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Pause the pipeline queue

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Resume the pipeline queue

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Repositories

List all repositories on the server

Returns a list of all repositories. Requires admin rights.

query Parameters
active
boolean

only list active repos

page
integer
Default: 1

for response pagination, page offset number

perPage
integer
Default: 50

for response pagination, max items per page

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Activate a repository

query Parameters
forge_remote_id
required
string

the id of a repository at the forge

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
{
  • "active": true,
  • "allow_deploy": true,
  • "allow_pr": true,
  • "avatar_url": "string",
  • "cancel_previous_pipeline_events": [
    ],
  • "clone_url": "string",
  • "clone_url_ssh": "string",
  • "config_file": "string",
  • "default_branch": "string",
  • "forge_id": 0,
  • "forge_remote_id": "string",
  • "forge_url": "string",
  • "full_name": "string",
  • "gated": true,
  • "id": 0,
  • "name": "string",
  • "netrc_only_trusted": true,
  • "org_id": 0,
  • "owner": "string",
  • "pr_enabled": true,
  • "private": true,
  • "scm": "git",
  • "timeout": 0,
  • "trusted": true,
  • "visibility": "public"
}

Lookup a repository by full name

path Parameters
repo_full_name
required
string

the repository full name / slug

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
{
  • "active": true,
  • "allow_deploy": true,
  • "allow_pr": true,
  • "avatar_url": "string",
  • "cancel_previous_pipeline_events": [
    ],
  • "clone_url": "string",
  • "clone_url_ssh": "string",
  • "config_file": "string",
  • "default_branch": "string",
  • "forge_id": 0,
  • "forge_remote_id": "string",
  • "forge_url": "string",
  • "full_name": "string",
  • "gated": true,
  • "id": 0,
  • "name": "string",
  • "netrc_only_trusted": true,
  • "org_id": 0,
  • "owner": "string",
  • "pr_enabled": true,
  • "private": true,
  • "scm": "git",
  • "timeout": 0,
  • "trusted": true,
  • "visibility": "public"
}

Repair all repositories on the server

Executes a repair process on all repositories. Requires admin rights.

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Delete a repository

path Parameters
repo_id
required
integer

the repository id

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
{
  • "active": true,
  • "allow_deploy": true,
  • "allow_pr": true,
  • "avatar_url": "string",
  • "cancel_previous_pipeline_events": [
    ],
  • "clone_url": "string",
  • "clone_url_ssh": "string",
  • "config_file": "string",
  • "default_branch": "string",
  • "forge_id": 0,
  • "forge_remote_id": "string",
  • "forge_url": "string",
  • "full_name": "string",
  • "gated": true,
  • "id": 0,
  • "name": "string",
  • "netrc_only_trusted": true,
  • "org_id": 0,
  • "owner": "string",
  • "pr_enabled": true,
  • "private": true,
  • "scm": "git",
  • "timeout": 0,
  • "trusted": true,
  • "visibility": "public"
}

Get a repository

path Parameters
repo_id
required
integer

the repository id

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
{
  • "active": true,
  • "allow_deploy": true,
  • "allow_pr": true,
  • "avatar_url": "string",
  • "cancel_previous_pipeline_events": [
    ],
  • "clone_url": "string",
  • "clone_url_ssh": "string",
  • "config_file": "string",
  • "default_branch": "string",
  • "forge_id": 0,
  • "forge_remote_id": "string",
  • "forge_url": "string",
  • "full_name": "string",
  • "gated": true,
  • "id": 0,
  • "name": "string",
  • "netrc_only_trusted": true,
  • "org_id": 0,
  • "owner": "string",
  • "pr_enabled": true,
  • "private": true,
  • "scm": "git",
  • "timeout": 0,
  • "trusted": true,
  • "visibility": "public"
}

Update a repository

path Parameters
repo_id
required
integer

the repository id

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Request Body schema: application/json
required

the repository's information

allow_deploy
boolean
allow_pr
boolean
cancel_previous_pipeline_events
Array of strings (WebhookEvent)
Items Enum: "push" "pull_request" "pull_request_closed" "tag" "release" "deployment" "cron" "manual"
config_file
string
gated
boolean
netrc_only_trusted
boolean
timeout
integer
trusted
boolean
visibility
string

Responses

Request samples

Content type
application/json
{
  • "allow_deploy": true,
  • "allow_pr": true,
  • "cancel_previous_pipeline_events": [
    ],
  • "config_file": "string",
  • "gated": true,
  • "netrc_only_trusted": true,
  • "timeout": 0,
  • "trusted": true,
  • "visibility": "string"
}

Response samples

Content type
application/json
{
  • "active": true,
  • "allow_deploy": true,
  • "allow_pr": true,
  • "avatar_url": "string",
  • "cancel_previous_pipeline_events": [
    ],
  • "clone_url": "string",
  • "clone_url_ssh": "string",
  • "config_file": "string",
  • "default_branch": "string",
  • "forge_id": 0,
  • "forge_remote_id": "string",
  • "forge_url": "string",
  • "full_name": "string",
  • "gated": true,
  • "id": 0,
  • "name": "string",
  • "netrc_only_trusted": true,
  • "org_id": 0,
  • "owner": "string",
  • "pr_enabled": true,
  • "private": true,
  • "scm": "git",
  • "timeout": 0,
  • "trusted": true,
  • "visibility": "public"
}

Get branches of a repository

path Parameters
repo_id
required
integer

the repository id

query Parameters
page
integer
Default: 1

for response pagination, page offset number

perPage
integer
Default: 50

for response pagination, max items per page

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
[
  • "string"
]

Change a repository's owner to the currently authenticated user

path Parameters
repo_id
required
integer

the repository id

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
{
  • "active": true,
  • "allow_deploy": true,
  • "allow_pr": true,
  • "avatar_url": "string",
  • "cancel_previous_pipeline_events": [
    ],
  • "clone_url": "string",
  • "clone_url_ssh": "string",
  • "config_file": "string",
  • "default_branch": "string",
  • "forge_id": 0,
  • "forge_remote_id": "string",
  • "forge_url": "string",
  • "full_name": "string",
  • "gated": true,
  • "id": 0,
  • "name": "string",
  • "netrc_only_trusted": true,
  • "org_id": 0,
  • "owner": "string",
  • "pr_enabled": true,
  • "private": true,
  • "scm": "git",
  • "timeout": 0,
  • "trusted": true,
  • "visibility": "public"
}

Move a repository to a new owner

path Parameters
repo_id
required
integer

the repository id

query Parameters
to
required
string

the username to move the repository to

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Check current authenticated users access to the repository

The repository permission, according to the used access token.

path Parameters
repo_id
required
integer

the repository id

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
{
  • "admin": true,
  • "created": 0,
  • "pull": true,
  • "push": true,
  • "synced": 0,
  • "updated": 0
}

List active pull requests of a repository

path Parameters
repo_id
required
integer

the repository id

query Parameters
page
integer
Default: 1

for response pagination, page offset number

perPage
integer
Default: 50

for response pagination, max items per page

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Repair a repository

path Parameters
repo_id
required
integer

the repository id

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Repository cron jobs

List cron jobs

path Parameters
repo_id
required
integer

the repository id

query Parameters
page
integer
Default: 1

for response pagination, page offset number

perPage
integer
Default: 50

for response pagination, max items per page

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a cron job

path Parameters
repo_id
required
integer

the repository id

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Request Body schema: application/json
required

the new cron job

branch
string
created_at
integer
creator_id
integer
id
integer
name
string
next_exec
integer
repo_id
integer
schedule
string

@weekly, 3min, ...

Responses

Request samples

Content type
application/json
{
  • "branch": "string",
  • "created_at": 0,
  • "creator_id": 0,
  • "id": 0,
  • "name": "string",
  • "next_exec": 0,
  • "repo_id": 0,
  • "schedule": "string"
}

Response samples

Content type
application/json
{
  • "branch": "string",
  • "created_at": 0,
  • "creator_id": 0,
  • "id": 0,
  • "name": "string",
  • "next_exec": 0,
  • "repo_id": 0,
  • "schedule": "string"
}

Delete a cron job

path Parameters
repo_id
required
integer

the repository id

cron
required
string

the cron job id

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Get a cron job

path Parameters
repo_id
required
integer

the repository id

cron
required
string

the cron job id

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
{
  • "branch": "string",
  • "created_at": 0,
  • "creator_id": 0,
  • "id": 0,
  • "name": "string",
  • "next_exec": 0,
  • "repo_id": 0,
  • "schedule": "string"
}

Update a cron job

path Parameters
repo_id
required
integer

the repository id

cron
required
string

the cron job id

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Request Body schema: application/json
required

the cron job data

branch
string
created_at
integer
creator_id
integer
id
integer
name
string
next_exec
integer
repo_id
integer
schedule
string

@weekly, 3min, ...

Responses

Request samples

Content type
application/json
{
  • "branch": "string",
  • "created_at": 0,
  • "creator_id": 0,
  • "id": 0,
  • "name": "string",
  • "next_exec": 0,
  • "repo_id": 0,
  • "schedule": "string"
}

Response samples

Content type
application/json
{
  • "branch": "string",
  • "created_at": 0,
  • "creator_id": 0,
  • "id": 0,
  • "name": "string",
  • "next_exec": 0,
  • "repo_id": 0,
  • "schedule": "string"
}

Start a cron job now

path Parameters
repo_id
required
integer

the repository id

cron
required
string

the cron job id

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
{
  • "author": "string",
  • "author_avatar": "string",
  • "author_email": "string",
  • "branch": "string",
  • "changed_files": [
    ],
  • "commit": "string",
  • "created_at": 0,
  • "deploy_task": "string",
  • "deploy_to": "string",
  • "errors": [
    ],
  • "event": "push",
  • "finished_at": 0,
  • "forge_url": "string",
  • "id": 0,
  • "is_prerelease": true,
  • "message": "string",
  • "number": 0,
  • "parent": 0,
  • "pr_labels": [
    ],
  • "ref": "string",
  • "refspec": "string",
  • "reviewed_at": 0,
  • "reviewed_by": "string",
  • "sender": "string",
  • "started_at": 0,
  • "status": "skipped",
  • "timestamp": 0,
  • "title": "string",
  • "updated_at": 0,
  • "variables": {
    },
  • "workflows": [
    ]
}

Pipeline logs

Deletes all logs of a pipeline

path Parameters
repo_id
required
integer

the repository id

number
required
integer

the number of the pipeline

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Get logs for a pipeline step

path Parameters
repo_id
required
integer

the repository id

number
required
integer

the number of the pipeline

stepID
required
integer

the step id

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete step logs of a pipeline

path Parameters
repo_id
required
integer

the repository id

number
required
integer

the number of the pipeline

stepId
required
integer

the step id

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Stream logs of a pipeline step

path Parameters
repo_id
required
integer

the repository id

pipeline
required
integer

the number of the pipeline

stepID
required
integer

the step id

Responses

Pipelines

List repository pipelines

Get a list of pipelines for a repository.

path Parameters
repo_id
required
integer

the repository id

query Parameters
page
integer
Default: 1

for response pagination, page offset number

perPage
integer
Default: 50

for response pagination, max items per page

before
string

only return pipelines before this RFC3339 date

after
string

only return pipelines after this RFC3339 date

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Trigger a manual pipeline

path Parameters
repo_id
required
integer

the repository id

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Request Body schema: application/json
required

the options for the pipeline to run

branch
string
object

Responses

Request samples

Content type
application/json
{
  • "branch": "string",
  • "variables": {
    }
}

Response samples

Content type
application/json
{
  • "author": "string",
  • "author_avatar": "string",
  • "author_email": "string",
  • "branch": "string",
  • "changed_files": [
    ],
  • "commit": "string",
  • "created_at": 0,
  • "deploy_task": "string",
  • "deploy_to": "string",
  • "errors": [
    ],
  • "event": "push",
  • "finished_at": 0,
  • "forge_url": "string",
  • "id": 0,
  • "is_prerelease": true,
  • "message": "string",
  • "number": 0,
  • "parent": 0,
  • "pr_labels": [
    ],
  • "ref": "string",
  • "refspec": "string",
  • "reviewed_at": 0,
  • "reviewed_by": "string",
  • "sender": "string",
  • "started_at": 0,
  • "status": "skipped",
  • "timestamp": 0,
  • "title": "string",
  • "updated_at": 0,
  • "variables": {
    },
  • "workflows": [
    ]
}

Delete a pipeline

path Parameters
repo_id
required
integer

the repository id

number
required
integer

the number of the pipeline

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Get a repositories pipeline

path Parameters
repo_id
required
integer

the repository id

number
required
integer

the number of the pipeline, OR 'latest'

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
{
  • "author": "string",
  • "author_avatar": "string",
  • "author_email": "string",
  • "branch": "string",
  • "changed_files": [
    ],
  • "commit": "string",
  • "created_at": 0,
  • "deploy_task": "string",
  • "deploy_to": "string",
  • "errors": [
    ],
  • "event": "push",
  • "finished_at": 0,
  • "forge_url": "string",
  • "id": 0,
  • "is_prerelease": true,
  • "message": "string",
  • "number": 0,
  • "parent": 0,
  • "pr_labels": [
    ],
  • "ref": "string",
  • "refspec": "string",
  • "reviewed_at": 0,
  • "reviewed_by": "string",
  • "sender": "string",
  • "started_at": 0,
  • "status": "skipped",
  • "timestamp": 0,
  • "title": "string",
  • "updated_at": 0,
  • "variables": {
    },
  • "workflows": [
    ]
}

Restart a pipeline

Restarts a pipeline optional with altered event, deploy or environment

path Parameters
repo_id
required
integer

the repository id

number
required
integer

the number of the pipeline

query Parameters
event
string

override the event type

deploy_to
string

override the target deploy value

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
{
  • "author": "string",
  • "author_avatar": "string",
  • "author_email": "string",
  • "branch": "string",
  • "changed_files": [
    ],
  • "commit": "string",
  • "created_at": 0,
  • "deploy_task": "string",
  • "deploy_to": "string",
  • "errors": [
    ],
  • "event": "push",
  • "finished_at": 0,
  • "forge_url": "string",
  • "id": 0,
  • "is_prerelease": true,
  • "message": "string",
  • "number": 0,
  • "parent": 0,
  • "pr_labels": [
    ],
  • "ref": "string",
  • "refspec": "string",
  • "reviewed_at": 0,
  • "reviewed_by": "string",
  • "sender": "string",
  • "started_at": 0,
  • "status": "skipped",
  • "timestamp": 0,
  • "title": "string",
  • "updated_at": 0,
  • "variables": {
    },
  • "workflows": [
    ]
}

Approve and start a pipeline

path Parameters
repo_id
required
integer

the repository id

number
required
integer

the number of the pipeline

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
{
  • "author": "string",
  • "author_avatar": "string",
  • "author_email": "string",
  • "branch": "string",
  • "changed_files": [
    ],
  • "commit": "string",
  • "created_at": 0,
  • "deploy_task": "string",
  • "deploy_to": "string",
  • "errors": [
    ],
  • "event": "push",
  • "finished_at": 0,
  • "forge_url": "string",
  • "id": 0,
  • "is_prerelease": true,
  • "message": "string",
  • "number": 0,
  • "parent": 0,
  • "pr_labels": [
    ],
  • "ref": "string",
  • "refspec": "string",
  • "reviewed_at": 0,
  • "reviewed_by": "string",
  • "sender": "string",
  • "started_at": 0,
  • "status": "skipped",
  • "timestamp": 0,
  • "title": "string",
  • "updated_at": 0,
  • "variables": {
    },
  • "workflows": [
    ]
}

Cancel a pipeline

path Parameters
repo_id
required
integer

the repository id

number
required
integer

the number of the pipeline

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Get configuration files for a pipeline

path Parameters
repo_id
required
integer

the repository id

number
required
integer

the number of the pipeline

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Decline a pipeline

path Parameters
repo_id
required
integer

the repository id

number
required
integer

the number of the pipeline

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
{
  • "author": "string",
  • "author_avatar": "string",
  • "author_email": "string",
  • "branch": "string",
  • "changed_files": [
    ],
  • "commit": "string",
  • "created_at": 0,
  • "deploy_task": "string",
  • "deploy_to": "string",
  • "errors": [
    ],
  • "event": "push",
  • "finished_at": 0,
  • "forge_url": "string",
  • "id": 0,
  • "is_prerelease": true,
  • "message": "string",
  • "number": 0,
  • "parent": 0,
  • "pr_labels": [
    ],
  • "ref": "string",
  • "refspec": "string",
  • "reviewed_at": 0,
  • "reviewed_by": "string",
  • "sender": "string",
  • "started_at": 0,
  • "status": "skipped",
  • "timestamp": 0,
  • "title": "string",
  • "updated_at": 0,
  • "variables": {
    },
  • "workflows": [
    ]
}

Repository registries

List registries

path Parameters
repo_id
required
integer

the repository id

query Parameters
page
integer
Default: 1

for response pagination, page offset number

perPage
integer
Default: 50

for response pagination, max items per page

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a registry

path Parameters
repo_id
required
integer

the repository id

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Request Body schema: application/json
required

the new registry data

address
string
id
integer
password
string
username
string

Responses

Request samples

Content type
application/json
{
  • "address": "string",
  • "id": 0,
  • "password": "string",
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "address": "string",
  • "id": 0,
  • "password": "string",
  • "username": "string"
}

Delete a registry by name

path Parameters
repo_id
required
integer

the repository id

registry
required
string

the registry name

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Get a registry by name

path Parameters
repo_id
required
integer

the repository id

registry
required
string

the registry name

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
{
  • "address": "string",
  • "id": 0,
  • "password": "string",
  • "username": "string"
}

Update a registry by name

path Parameters
repo_id
required
integer

the repository id

registry
required
string

the registry name

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Request Body schema: application/json
required

the attributes for the registry

address
string
id
integer
password
string
username
string

Responses

Request samples

Content type
application/json
{
  • "address": "string",
  • "id": 0,
  • "password": "string",
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "address": "string",
  • "id": 0,
  • "password": "string",
  • "username": "string"
}

Repository secrets

List repository secrets

path Parameters
repo_id
required
integer

the repository id

query Parameters
page
integer
Default: 1

for response pagination, page offset number

perPage
integer
Default: 50

for response pagination, max items per page

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a repository secret

path Parameters
repo_id
required
integer

the repository id

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Request Body schema: application/json
required

the new secret

events
Array of strings (WebhookEvent)
Items Enum: "push" "pull_request" "pull_request_closed" "tag" "release" "deployment" "cron" "manual"
id
integer
images
Array of strings
name
string
org_id
integer
repo_id
integer
value
string

Responses

Request samples

Content type
application/json
{
  • "events": [
    ],
  • "id": 0,
  • "images": [
    ],
  • "name": "string",
  • "org_id": 0,
  • "repo_id": 0,
  • "value": "string"
}

Response samples

Content type
application/json
{
  • "events": [
    ],
  • "id": 0,
  • "images": [
    ],
  • "name": "string",
  • "org_id": 0,
  • "repo_id": 0,
  • "value": "string"
}

Delete a repository secret by name

path Parameters
repo_id
required
integer

the repository id

secretName
required
string

the secret name

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Get a repository secret by name

path Parameters
repo_id
required
integer

the repository id

secretName
required
string

the secret name

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
{
  • "events": [
    ],
  • "id": 0,
  • "images": [
    ],
  • "name": "string",
  • "org_id": 0,
  • "repo_id": 0,
  • "value": "string"
}

Update a repository secret by name

path Parameters
repo_id
required
integer

the repository id

secretName
required
string

the secret name

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Request Body schema: application/json
required

the secret itself

events
Array of strings (WebhookEvent)
Items Enum: "push" "pull_request" "pull_request_closed" "tag" "release" "deployment" "cron" "manual"
id
integer
images
Array of strings
name
string
org_id
integer
repo_id
integer
value
string

Responses

Request samples

Content type
application/json
{
  • "events": [
    ],
  • "id": 0,
  • "images": [
    ],
  • "name": "string",
  • "org_id": 0,
  • "repo_id": 0,
  • "value": "string"
}

Response samples

Content type
application/json
{
  • "events": [
    ],
  • "id": 0,
  • "images": [
    ],
  • "name": "string",
  • "org_id": 0,
  • "repo_id": 0,
  • "value": "string"
}

Secrets

List global secrets

query Parameters
page
integer
Default: 1

for response pagination, page offset number

perPage
integer
Default: 50

for response pagination, max items per page

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a global secret

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Request Body schema: application/json
required

the secret object data

events
Array of strings (WebhookEvent)
Items Enum: "push" "pull_request" "pull_request_closed" "tag" "release" "deployment" "cron" "manual"
id
integer
images
Array of strings
name
string
org_id
integer
repo_id
integer
value
string

Responses

Request samples

Content type
application/json
{
  • "events": [
    ],
  • "id": 0,
  • "images": [
    ],
  • "name": "string",
  • "org_id": 0,
  • "repo_id": 0,
  • "value": "string"
}

Response samples

Content type
application/json
{
  • "events": [
    ],
  • "id": 0,
  • "images": [
    ],
  • "name": "string",
  • "org_id": 0,
  • "repo_id": 0,
  • "value": "string"
}

Delete a global secret by name

path Parameters
secret
required
string

the secret's name

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Get a global secret by name

path Parameters
secret
required
string

the secret's name

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
{
  • "events": [
    ],
  • "id": 0,
  • "images": [
    ],
  • "name": "string",
  • "org_id": 0,
  • "repo_id": 0,
  • "value": "string"
}

Update a global secret by name

path Parameters
secret
required
string

the secret's name

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Request Body schema: application/json
required

the secret's data

events
Array of strings (WebhookEvent)
Items Enum: "push" "pull_request" "pull_request_closed" "tag" "release" "deployment" "cron" "manual"
id
integer
images
Array of strings
name
string
org_id
integer
repo_id
integer
value
string

Responses

Request samples

Content type
application/json
{
  • "events": [
    ],
  • "id": 0,
  • "images": [
    ],
  • "name": "string",
  • "org_id": 0,
  • "repo_id": 0,
  • "value": "string"
}

Response samples

Content type
application/json
{
  • "events": [
    ],
  • "id": 0,
  • "images": [
    ],
  • "name": "string",
  • "org_id": 0,
  • "repo_id": 0,
  • "value": "string"
}

Events

Stream events like pipeline updates

With quic and http2 support

Responses

User

Get the currently authenticated user

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
{
  • "admin": true,
  • "avatar_url": "string",
  • "email": "string",
  • "forge_id": 0,
  • "id": 0,
  • "login": "string",
  • "org_id": 0
}

Get the currently authenticaed users pipeline feed

The feed lists the most recent pipeline for the currently authenticated user.

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get user's repositories

Retrieve the currently authenticated User's Repository list

query Parameters
all
boolean

query all repos, including inactive ones

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Reset a token

Reset's the current personal access token of the user and returns a new one.

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Return the token of the current user as string

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Users

List users

Returns all registered, active users in the system. Requires admin rights.

query Parameters
page
integer
Default: 1

for response pagination, page offset number

perPage
integer
Default: 50

for response pagination, max items per page

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a user

Creates a new user account with the specified external login. Requires admin rights.

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Request Body schema: application/json
required

the user's data

admin
boolean

Admin indicates the user is a system administrator.

NOTE: If the username is part of the WOODPECKER_ADMIN environment variable, this value will be set to true on login.

avatar_url
string

the avatar url for this user.

email
string

Email is the email address for this user.

required: true

forge_id
integer
id
integer

the id for this user.

required: true

login
string

Login is the username for this user.

required: true

org_id
integer

OrgID is the of the user as model.Org.

Responses

Request samples

Content type
application/json
{
  • "admin": true,
  • "avatar_url": "string",
  • "email": "string",
  • "forge_id": 0,
  • "id": 0,
  • "login": "string",
  • "org_id": 0
}

Response samples

Content type
application/json
{
  • "admin": true,
  • "avatar_url": "string",
  • "email": "string",
  • "forge_id": 0,
  • "id": 0,
  • "login": "string",
  • "org_id": 0
}

Delete a user

Deletes the given user. Requires admin rights.

path Parameters
login
required
string

the user's login name

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Get a user

Returns a user with the specified login name. Requires admin rights.

path Parameters
login
required
string

the user's login name

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Responses

Response samples

Content type
application/json
{
  • "admin": true,
  • "avatar_url": "string",
  • "email": "string",
  • "forge_id": 0,
  • "id": 0,
  • "login": "string",
  • "org_id": 0
}

Update a user

Changes the data of an existing user. Requires admin rights.

path Parameters
login
required
string

the user's login name

header Parameters
Authorization
required
string
Default: Bearer <personal access token>

Insert your personal access token

Request Body schema: application/json
required

the user's data

admin
boolean

Admin indicates the user is a system administrator.

NOTE: If the username is part of the WOODPECKER_ADMIN environment variable, this value will be set to true on login.

avatar_url
string

the avatar url for this user.

email
string

Email is the email address for this user.

required: true

forge_id
integer
id
integer

the id for this user.

required: true

login
string

Login is the username for this user.

required: true

org_id
integer

OrgID is the of the user as model.Org.

Responses

Request samples

Content type
application/json
{
  • "admin": true,
  • "avatar_url": "string",
  • "email": "string",
  • "forge_id": 0,
  • "id": 0,
  • "login": "string",
  • "org_id": 0
}

Response samples

Content type
application/json
{
  • "admin": true,
  • "avatar_url": "string",
  • "email": "string",
  • "forge_id": 0,
  • "id": 0,
  • "login": "string",
  • "org_id": 0
}