Key Concepts
Project
A connection between a Git repository and pipeline configuration with deployment settings.
Environment
A deployment target (dev, staging, prod) with ArgoCD clusters and namespaces.
Webhook
Automatic pipeline triggering on Git events (push, tag, merge request).
Pipeline
A CI/CD execution instance with stages, logs, and deployment artifacts.
Required Permissions
Project Permissions
| Action | Permission |
|---|---|
| View projects | iam:project:cicd:pipeline:read |
| Create projects | iam:project:cicd:pipeline:write |
| Edit projects | iam:project:cicd:pipeline:write |
| Delete projects | iam:project:cicd:pipeline:delete |
| Run pipelines | iam:project:cicd:pipeline:execute |
| View pipeline logs | iam:project:cicd:pipeline:logs |
Webhook Permissions
| Action | Permission |
|---|---|
| View webhook | iam:project:cicd:webhook:read |
| Create/Edit webhook | iam:project:cicd:webhook:write |
| Delete webhook | iam:project:cicd:webhook:delete |
How to Create a Project
Select Template
Choose a pipeline template. Templates define deployment type and required configurations.
Configure Repository
Choose Create new repository or Use existing repository.
- For new repos: Select organization/group and enter repository name
- For existing repos: Select from available repositories
Select Namespace (Optional)
If the template requires a namespace, select one to inherit shared variables.
Configure Environments
If the template requires environments, add deployment targets:
- Environment name (e.g., dev, staging, production)
- ArgoCD instance
- Cluster name
- Namespace
The template determines which fields are required. Some templates don’t require namespaces or environments.
How to Run a Pipeline
Select Strategy
Choose an image tag strategy:
- Trunk Based: Branch + commit SHA
- Tag Based: Git tag release
- Feature: Branch name only
- Manual: Custom tag
Image Tag Strategies
| Strategy | Image Tag Format | Use Case |
|---|---|---|
| Trunk Based | branch-commitsha | Continuous deployment from main branch |
| Tag Based | v1.0.0 | Release deployments with semantic versioning |
| Feature | feature-name | Development/testing feature branches |
| Manual | Custom value | Special deployments with custom naming |
How to Monitor Pipelines
Pipeline Statuses
| Status | Description |
|---|---|
| Running | Pipeline is currently executing |
| Pending | Pipeline is queued for execution |
| Success | All stages completed successfully |
| Success with Warnings | Completed with non-critical issues |
| Failed | One or more stages failed |
| Cancelled | Pipeline was manually cancelled |
| Skipped | Pipeline was skipped (duplicate or condition not met) |
Pipeline Actions
| Action | Description | Availability |
|---|---|---|
| Cancel | Stop a running pipeline | Running/Pending pipelines |
| Retry | Re-run a failed pipeline | Failed pipelines |
| Re-run | Run the same configuration again | Completed pipelines |
| Download Logs | Download pipeline execution logs | Completed pipelines |
How to Manage Environments
Adding an Environment
Add Deployment Target
Configure target settings:
- ArgoCD Instance: Select the ArgoCD server
- Cluster Name: Select the Kubernetes cluster
- Namespace: Select the target namespace
- Active: Enable/disable deployments to this target
Environment Requirements
| Field | Required | Description |
|---|---|---|
| Environment Name | Yes | Unique name within the project |
| ArgoCD Instance | Yes | Target ArgoCD server |
| Cluster Name | Yes | Kubernetes cluster |
| Namespace | Yes | Target namespace for deployment |
How to Configure Webhooks
Webhooks enable automatic pipeline triggering from Git events.Creating a Webhook
Webhook Event Types
| Event | Description | Trigger |
|---|---|---|
| Push | Branch push events | Pipeline runs on commits to configured branches |
| Tag | Tag creation events | Pipeline runs when tags are pushed |
| Merge Request | PR/MR events | Pipeline runs on pull request actions |
Managing Webhook Settings
| Action | Description |
|---|---|
| Enable/Disable | Toggle webhook active status |
| Regenerate Secret | Create new secret (invalidates old one) |
| Update Event Types | Change which events trigger pipelines |
| Delete | Remove webhook configuration |
Regenerating the secret invalidates the previous secret. Update your Git provider settings after regenerating.
How to Manage Project Variables
How to Edit a Project
How to Delete a Project
Choose Repository Action
Select whether to also delete the Git repository:
- Keep repository: Only delete project configuration
- Delete repository: Also delete the Git repository
Troubleshooting
Pipeline not triggered by webhook
Pipeline not triggered by webhook
- Verify webhook is enabled (active status)
- Check event type is configured (push, tag, merge_request)
- Confirm webhook URL is correctly configured in Git provider
- Verify webhook secret matches
- Check branch filters match the pushed branch
- Review webhook delivery logs in Git provider
Pipeline fails immediately
Pipeline fails immediately
- Verify Git provider credentials are valid
- Check repository access permissions
- Ensure pipeline configuration files exist in repository
- Verify template configuration is complete
Cannot run pipeline
Cannot run pipeline
- Verify you have execute permission
- Check that at least one environment is configured
- Ensure Git provider connection is active
- Verify branch and commit selection
Environment deployment fails
Environment deployment fails
- Verify ArgoCD instance is accessible
- Check cluster and namespace exist
- Ensure ArgoCD has permissions to deploy
- Review ArgoCD application logs
Cannot create project
Cannot create project
- Verify you have write permission
- Check Git provider is configured and active
- Ensure repository name is valid and unique
- Verify required template fields are filled
Webhook secret lost
Webhook secret lost
- Click Regenerate to create a new secret
- Update the secret in your Git provider settings
- Old webhook deliveries will fail signature verification
Variables not available in pipeline
Variables not available in pipeline
- Verify variables are saved
- Check variable key spelling (case-sensitive)
- Namespace variables require project to be in that namespace
- Project variables override namespace variables
FAQ
Can I use multiple Git providers for one project?
Can I use multiple Git providers for one project?
No. Each project connects to one Git provider and one repository. Create separate projects for different repositories.
How do I migrate a project to a different repository?
How do I migrate a project to a different repository?
Projects cannot be migrated to different repositories. Create a new project with the new repository and optionally delete the old project.
Can I have multiple environments with the same name?
Can I have multiple environments with the same name?
No. Environment names must be unique within a project. Use descriptive names like “production-us”, “production-eu” for regional deployments.
What happens when I cancel a running pipeline?
What happens when I cancel a running pipeline?
The pipeline execution stops at the current step. Partially deployed resources may remain. Review deployment state after cancellation.
How do I roll back a deployment?
How do I roll back a deployment?
Run a new pipeline with the previous commit or tag. Alternatively, use ArgoCD directly to sync to a previous revision.
Can webhooks trigger specific environments?
Can webhooks trigger specific environments?
Webhook trigger configuration in the template determines which branches trigger which environments. Configure branch-to-environment mapping in the template trigger configuration.
Are pipeline logs retained permanently?
Are pipeline logs retained permanently?
Pipeline logs are retained according to your organization’s retention policy. Download logs for long-term storage if needed.
Can I run the same pipeline configuration multiple times?
Can I run the same pipeline configuration multiple times?
Yes. Use the Re-run action on any completed pipeline to run the same configuration again.
What's the difference between Retry and Re-run?
What's the difference between Retry and Re-run?
Retry attempts to continue from the failed stage. Re-run starts a fresh pipeline execution from the beginning.
How do I deploy to multiple clusters simultaneously?
How do I deploy to multiple clusters simultaneously?
Add multiple targets to an environment. Each target can specify a different ArgoCD instance, cluster, or namespace.
Best Practices
Project Organization
- Use consistent naming conventions (team-service-env)
- Group related projects in the same namespace
- Keep one project per microservice/application
- Document project purpose in description
Pipeline Execution
- Use Tag Based strategy for production releases
- Use Trunk Based for continuous deployment
- Always verify environment selection before running
- Monitor pipeline progress for failures
Environment Configuration
- Create separate environments for dev/staging/production
- Use multiple targets for multi-cluster deployments
- Disable targets during maintenance
- Keep production targets with restricted access
Webhook Configuration
- Always configure webhook secrets for security
- Enable only required event types
- Monitor webhook delivery statistics
- Update secrets periodically
Security
- Use private repositories for sensitive code
- Limit execute permission to authorized users
- Store secrets in variables, not in code
- Review pipeline logs for sensitive data exposure
- Rotate webhook secrets regularly
Variables
- Use UPPER_SNAKE_CASE for environment variables
- Document variable purposes
- Use namespace variables for shared configuration
- Override with project variables for specific needs