# Jenkins

> Manage Jenkins jobs, builds, the build queue, nodes, views and plugins via the remote API.

Lets an agent drive a Jenkins controller through its remote access API - list and
configure jobs, trigger and watch builds, manage the queue and inspect nodes,
views and plugins.

## What it can do

| Method | What it does |
| --- | --- |
| `jenkins_who_am_i` | Get the authenticated Jenkins user; use to verify credentials. |
| `jenkins_get_crumb` | Get a CSRF crumb (the write actions fetch it automatically). |
| `jenkins_get_system_info` | Get controller top-level info (mode, executors, jobs, views). |
| `jenkins_list_jobs` | List jobs, optionally scoped to a folder. |
| `jenkins_get_job` | Get one job's metadata, builds and health. |
| `jenkins_get_job_config` | Get a job's raw config.xml. |
| `jenkins_create_job` | Create a job from config.xml. WRITE - confirm first. |
| `jenkins_copy_job` | Copy an existing job to a new name. WRITE - confirm first. |
| `jenkins_update_job_config` | Replace a job's config.xml. WRITE - confirm first. |
| `jenkins_delete_job` | Delete a job. WRITE - confirm first. |
| `jenkins_enable_job` | Enable a job. WRITE - confirm first. |
| `jenkins_disable_job` | Disable a job. WRITE - confirm first. |
| `jenkins_build_job` | Trigger a non-parameterized build. WRITE - confirm first. |
| `jenkins_build_with_parameters` | Trigger a parameterized build. WRITE - confirm first. |
| `jenkins_get_build` | Get build info (number or selector like lastBuild). |
| `jenkins_get_build_console` | Get a build's plain-text console log. |
| `jenkins_stop_build` | Stop a running build. WRITE - confirm first. |
| `jenkins_get_queue` | List the build queue. |
| `jenkins_get_queue_item` | Get one queue item. |
| `jenkins_cancel_queue_item` | Cancel a queued item. WRITE - confirm first. |
| `jenkins_list_computers` | List nodes (build agents) and their online state. |
| `jenkins_get_computer` | Get one node by name. |
| `jenkins_list_views` | List dashboard views. |
| `jenkins_get_view` | Get one view and its jobs. |
| `jenkins_list_plugins` | List installed plugins and versions. |
| `jenkins_restart` | Restart the controller (safe or immediate). WRITE - confirm first. |
| `jenkins_quiet_down` | Block or resume new builds. WRITE - confirm first. |

## How to get credentials

The agent authenticates with HTTP Basic auth using your Jenkins username and a
personal API token (not your password).

1. Open the [Jenkins remote access API docs](https://www.jenkins.io/doc/book/using/remote-access-api/)
   for reference.
2. In Jenkins, click your name (top right) and choose **Configure**.
3. Under **API Token**, click **Add new Token**, give it a name (e.g.
   *FlyMyAI Agent*) and **Generate**.
4. Copy the generated token - it is shown only once.
5. Note your Jenkins base URL (e.g. `https://ci.example.com`) and your login
   username.

## Fields to fill in FlyMyAI

| FlyMyAI field | Where it comes from |
| --- | --- |
| `JENKINS_BASE_URL` | Root URL of your Jenkins controller, e.g. `https://ci.example.com` |
| `JENKINS_USERNAME` | Your Jenkins login username |
| `JENKINS_API_KEY` | User → Configure → API Token → Add new Token |

## Troubleshooting

- **403 No valid crumb** - CSRF protection is on; the write actions fetch a
  crumb automatically, so confirm the token user has permission to read
  `crumbIssuer`.
- **401 / 403** - wrong username or token, or the user lacks the job/build
  permission. Use an API token, never your account password.
- **404** - check the job path; nested jobs use folder paths like
  `team/backend/deploy`.

## Links

- [Jenkins remote access API](https://www.jenkins.io/doc/book/using/remote-access-api/)
- [Jenkins API token](https://www.jenkins.io/doc/book/system-administration/authenticating-scripted-clients/)