GitHub Action for trigger jenkins jobs.
In many organizations, different teams operate on different CI/CD platforms. While legacy systems continue to run on Jenkins, modern platforms like GitHub Actions and Gitea Actions offer superior features and developer experience. This creates a dilemma: teams want to modernize their workflows, but can't afford to abandon existing Jenkins infrastructure.
Jenkins Action bridges this gap. It provides seamless integration between modern CI/CD platforms and Jenkins, enabling teams to:
- Migrate at your own pace - Start using GitHub Actions or Gitea Actions today while still leveraging existing Jenkins jobs, no immediate rewrite required
- Work across platforms - Different teams can use their preferred tools while maintaining interoperability
- Remove adoption barriers - Eliminate the "all-or-nothing" problem that prevents teams from modernizing
By connecting modern GitHub Actions or Gitea Actions workflows with existing Jenkins infrastructure, this action provides organizations with a practical, low-risk path toward CI/CD modernization.
Check out Connecting Your Worlds: A Guide to Integrating GitHub Actions and Jenkins for more details.
Trigger New Jenkins Job.
name: trigger jenkins job
on: [push]
jobs:
build:
name: Build
runs-on: ubuntu-latest
steps:
- name: trigger single Job
uses: appleboy/jenkins-action@v1
with:
url: "http://example.com"
user: "example"
token: ${{ secrets.TOKEN }}
job: "foobar"Setup the Jenkins server using the docker command:
docker run \
--name jenkins-docker \
-d --restart always \
-p 8080:8080 -p 50000:50000 \
-v /data/jenkins:/var/jenkins_home \
jenkins/jenkins:ltsPlease make sure that you create the /data/jenkins before starting the Jenkins.
Go to user profile and click on Configure:
CSRF (Cross-Site Request Forgery) protection uses a token called crumb in Jenkins. This crumb is created by Jenkins and sent to the user. Any form submissions or actions resulting in modifications (like triggering builds or changing configuration) require that the crumb be provided. The crumb contains information identifying the user it was created for, so submissions with another user's token would be rejected. All of this happens in the background and has no visible impact except in rare circumstances, such as after a user's session expired and they logged in again.
For more details, see the Jenkins CSRF Protection documentation.
This action supports two authentication methods:
- name: trigger with user authentication
uses: appleboy/jenkins-action@v1
with:
url: http://example.com
user: example
token: ${{ secrets.TOKEN }}
job: job_1How it works:
- Authenticates using Jenkins username and API token
- Automatically handles CSRF protection by fetching and including the crumb token
- The action will make an additional API call to
/crumbIssuer/api/jsonto obtain the crumb - The crumb is then included in all subsequent requests
- More secure and recommended for most use cases
When to use:
- Standard Jenkins installations with CSRF protection enabled (default)
- When you need full API access and security
- Production environments
- name: trigger with remote token
uses: appleboy/jenkins-action@v1
with:
url: http://example.com
remote_token: ${{ secrets.REMOTE_TOKEN }}
job: job_1How it works:
- Uses Jenkins job-specific remote trigger token
- Bypasses CSRF protection - does not require crumb token
- Configured per-job in Jenkins job configuration under "Build Triggers" > "Trigger builds remotely"
- Less secure as it only requires knowing the job name and remote token
When to use:
- Jenkins instances with CSRF protection disabled
- Legacy systems or specific security requirements
- When you only need to trigger specific jobs without full API access
- External systems that cannot handle crumb tokens
Note: Remote token authentication is considered less secure and should be used with caution. User + API token authentication is recommended for most use cases.
Trigger multiple jenkins job:
- name: trigger multiple Job
uses: appleboy/jenkins-action@v1
with:
url: http://example.com
user: example
token: ${{ secrets.TOKEN }}
job: job_1,job_2Trigger jenkins job with parameters:
- name: trigger Job with parameters
uses: appleboy/jenkins-action@v1
with:
url: http://example.com
user: example
token: ${{ secrets.TOKEN }}
job: job_1
parameters: |
ENVIRONMENT=production
VERSION=1.0.0
COMMIT_SHA=${{ github.sha }}
BRANCH=${{ github.ref_name }}Trigger jenkins job using remote token:
- name: trigger Job with remote token
uses: appleboy/jenkins-action@v1
with:
url: http://example.com
remote_token: ${{ secrets.REMOTE_TOKEN }}
job: job_1Wait for job completion with custom timeout:
- name: trigger Job and wait for completion
uses: appleboy/jenkins-action@v1
with:
url: http://example.com
user: example
token: ${{ secrets.TOKEN }}
job: job_1
wait: true
poll_interval: 5s
timeout: 60mUse custom CA certificate for self-signed SSL:
- name: trigger Job with custom CA certificate
uses: appleboy/jenkins-action@v1
with:
url: https://jenkins.example.com
user: example
token: ${{ secrets.TOKEN }}
job: job_1
ca_cert: ${{ secrets.CA_CERT }}You can also specify a file path or HTTP URL for the CA certificate:
- name: trigger Job with CA certificate from file
uses: appleboy/jenkins-action@v1
with:
url: https://jenkins.example.com
user: example
token: ${{ secrets.TOKEN }}
job: job_1
ca_cert: /path/to/ca-certificate.pem| Parameter | Required | Default | Description |
|---|---|---|---|
| url | Yes | Jenkins base URL (e.g., http://jenkins.example.com/) |
|
| user | Conditional* | Jenkins username | |
| token | Conditional* | Jenkins API token | |
| remote_token | Conditional* | Jenkins remote trigger token | |
| job | Yes | Jenkins job name(s) - can specify multiple | |
| parameters | No | Build parameters in multi-line key=value format (one per line) |
|
| insecure | No | false |
Allow insecure SSL connections |
| wait | No | false |
Wait for job completion |
| poll_interval | No | 10s |
Interval between status checks |
| timeout | No | 30m |
Maximum time to wait for job completion |
| debug | No | false |
Enable debug mode to show detailed parameter information |
| ca_cert | No | Custom CA certificate (PEM content, file path, or HTTP URL) |
* Authentication: Either
user+tokenORremote_tokenis required.
| Parameter | Description |
|---|---|
| result | Jenkins job result (SUCCESS, FAILURE, ABORTED, UNSTABLE, or empty) |
| url | Jenkins job URL |
Usage example:
- name: Trigger Jenkins Job
id: jenkins
uses: appleboy/jenkins-action@v1
with:
url: ${{ secrets.JENKINS_URL }}
user: ${{ secrets.JENKINS_USER }}
token: ${{ secrets.JENKINS_TOKEN }}
job: your-job-name
wait: true
- name: Use outputs
run: |
echo "Result: ${{ steps.jenkins.outputs.result }}"
echo "URL: ${{ steps.jenkins.outputs.url }}"Here's a complete example that demonstrates a real-world CI/CD workflow with conditional triggers, multiple environments, and job status handling:
name: Deploy via Jenkins
on:
push:
branches: [main, develop]
pull_request:
branches: [main]
jobs:
deploy:
name: Trigger Jenkins Deployment
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Set environment variables
id: vars
run: |
if [[ "${{ github.ref }}" == "refs/heads/main" ]]; then
echo "environment=production" >> $GITHUB_OUTPUT
echo "jenkins_job=deploy-prod" >> $GITHUB_OUTPUT
else
echo "environment=staging" >> $GITHUB_OUTPUT
echo "jenkins_job=deploy-staging" >> $GITHUB_OUTPUT
fi
- name: Trigger Jenkins Build and Wait
uses: appleboy/jenkins-action@v1
with:
url: ${{ secrets.JENKINS_URL }}
user: ${{ secrets.JENKINS_USER }}
token: ${{ secrets.JENKINS_TOKEN }}
job: ${{ steps.vars.outputs.jenkins_job }}
wait: true
timeout: 30m
poll_interval: 10s
parameters: |
ENVIRONMENT=${{ steps.vars.outputs.environment }}
VERSION=${{ github.sha }}
BRANCH=${{ github.ref_name }}
TRIGGERED_BY=${{ github.actor }}
- name: Notify on success
if: success()
run: echo "Jenkins job completed successfully!"
- name: Notify on failure
if: failure()
run: echo "Jenkins job failed!"