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

Get agent list

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 with a random token so a new agent can connect to the server

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 agent information

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 agent information

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"
}

Get 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 badge, SVG format

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 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

Get all orgs

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 org

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 organization by id

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 current user in 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

Get the organization secret list

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
[
  • {
    }
]

Persist/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 the named secret from an organization

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 the named organization secret

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

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 pipeline queues

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 a pipeline queue

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

Insert your personal access token

Responses

Resume a 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. 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"
}

Get 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. 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 repository information

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"
}

Change 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 repository branches

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 one holding the 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
{
  • "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

Repository permission information

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

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

Get the cron job list

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
[
  • {
    }
]

Persist/creat 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 by id

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 by id

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_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 log

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

Log information

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
[
  • {
    }
]

Deletes step log

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

Log stream

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

Get pipelines, current running and past ones

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
[
  • {
    }
]

Run/trigger a pipelines

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_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 information by number

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_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_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": [
    ]
}

Start pipelines in gated repos

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_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": [
    ]
}

Cancels 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

Pipeline configuration

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 pipelines in gated repos

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_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

Get the registry list

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
[
  • {
    }
]

Persist/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 named registry

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 named registry

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 named registry

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

Get the secret list

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
[
  • {
    }
]

Persist/create a 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 named secret

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 named secret

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 named secret

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

Get the global secret list

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
[
  • {
    }
]

Persist/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

Event stream

event source streaming for compatibility with quic and http2

Responses

User

Returns 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
}

A feed entry for a build.

Feed entries can be used to display information on the latest builds.

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",
  • "commit": "string",
  • "created_at": 0,
  • "event": "string",
  • "finished_at": 0,
  • "id": 0,
  • "message": "string",
  • "number": 0,
  • "ref": "string",
  • "refspec": "string",
  • "repo_id": 0,
  • "started_at": 0,
  • "status": "string",
  • "title": "string"
}

Get user's repos

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

Get all 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
}

Change 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
}