Skip to content

Commit e81dcbe

Browse files
alexei-ledalexei-led
committed
initial commit
1 parent b698a0b commit e81dcbe

File tree

4 files changed

+207
-2
lines changed

4 files changed

+207
-2
lines changed

‎.codefresh/codefresh.yaml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
version: '1.0'
2+
steps:

‎CONTRIBUTING.md

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Contributing Guidelines
2+
3+
The Codefresh Plugins project accepts contributions via GitHub pull requests. This document outlines the process to help get your contribution accepted.
4+
5+
6+
### Reporting a Bug in Plugin
7+
8+
This repository is used by Plugin developers for maintaining the official plugins for Codefresh.
9+
10+
### How to Contribute a Plugin
11+
12+
1. Fork this repository, develop and test your Plugin.
13+
2. Choose the correct folder for your plugin based on the information in the [Repository Structure](README.md#repository-structure) section
14+
3. Ensure your Plugin follows the [technical](#technical-requirements) and [documentation](#documentation-requirements) guidelines, described below.
15+
4. Submit a pull request.
16+
17+
***NOTE***: In order to make testing and merging of PRs easier, please submit changes to multiple plugins in separate PRs.
18+
19+
#### Technical requirements
20+
21+
* The Plugin with all its dependencies should be packaged into a single Docker container
22+
* The Plugin code must be available as public GitHub repository
23+
* It should be possible to build the Plugin using single `Dockerfile` (use *multi-stage* build if needed)
24+
* The Plugin Docker Image should not have any major security vulnerabilities
25+
* It should be possible to run the Plugin with simple `docker run` command, providing all required environment variables and volumes
26+
27+
#### Documentation requirements
28+
29+
* Must include an in-depth `README.md`, including:
30+
* Short description of the Plugin
31+
* Customization: explaining all required variables and their defaults
32+
* Must include a short `NOTES.txt`, including:
33+
* Any relevant post/pre-installation information for the Plugin
34+
* Instructions on how to access the application or service provided by the Plugin
35+
36+
#### Merge approval and release process
37+
38+
A Codefresh Plugins maintainer will review the Plugin submission, and start a validation job in the CI to verify the technical requirements of the Plugin. A maintainer may add "LGTM" (Looks Good To Me) or an equivalent comment to indicate that a PR is acceptable. Any change requires at least one LGTM. No pull requests can be merged until at least one maintainer signs off with an LGTM.
39+
40+
Once the Plugin has been merged, the release job will automatically run in the CI to package and release the Plugin in the [`gs://codefresh-plugins` Google Storage bucket](https://console.cloud.google.com/storage/browser/codefresh-plugins/).
41+
42+
### Support Channels
43+
44+
Whether you are a user or contributor, official support channels include:
45+
46+
- GitHub issues: https://github.com/codefresh-io/plugins/issues
47+
- Slack: *TBD*
48+
49+
Before opening a new issue or submitting a new pull request, it's helpful to search the project - it's likely that another user has already reported the issue you're facing, or it's a known issue that we're already aware of.

‎README.md

Lines changed: 60 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,60 @@
1-
# plugins
2-
Codefresh plugins repository
1+
# Codefresh Plugins
2+
3+
Use this repository to submit official Plugins for Codefresh. Plugins are curated automated step definitions for Codefresh. For more information about using Codefresh, see its
4+
[documentation](https://docs.codefresh.io).
5+
6+
## How do I install these plugins?
7+
8+
Codefresh Plugins are available as plain Docker images. As long as Plugin Docker image is accessible, Codefresh can use it for its pipelines.
9+
10+
## How do I use plugins from the Incubator repository?
11+
12+
*TBD*
13+
14+
## Codefresh Plugin Format
15+
16+
Take a look at the [example plugin](#) for reference when you're writing your first few plugins.
17+
18+
The Plugin folder must contain `plugin.yaml` and `README.md` files.
19+
20+
Before contributing a Plugin, become familiar with the format. Note that the project is still under active development and the format may still evolve a bit.
21+
22+
## Repository Structure
23+
24+
This GitHub repository contains the source for the packaged and versioned plugins released in the [`gs://codefresh-plugins` Google Storage bucket](https://console.cloud.google.com/storage/browser/codefresh-plugins/) (the Plugins Repository).
25+
26+
The Plugins in the `stable/` directory in the master branch of this repository match the latest packaged Plugins in the Plugin Repository, though there may be previous versions of a Plugin available in that Plugin Repository.
27+
28+
The purpose of this repository is to provide a place for maintaining and contributing official Plugins, with CI processes in place for managing the releasing of Plugins into the Plugin Repository.
29+
30+
The Plugins in this repository are organized into two folders:
31+
* stable
32+
* incubator
33+
34+
Stable Plugins meet the criteria in the [technical requirements](CONTRIBUTING.md#technical-requirements).
35+
36+
Incubator Plugins are those that do not meet these criteria. Having the incubator folder allows plugins to be shared and improved on until they are ready to be moved into the stable folder. The plugins in the `incubator/` directory can be found in the [`gs://codefresh-plugins-incubator` Google Storage Bucket](https://console.cloud.google.com/storage/browser/codefresh-plugins-incubator).
37+
38+
In order to get a Plugin from incubator to stable, Plugin maintainers should open a pull request that moves the plugin folder.
39+
40+
## Contributing a Plugin
41+
42+
We'd love for you to contribute a Plugin that provides a useful automated step for Codefresh. Please read our [Contribution Guide](CONTRIBUTING.md) for more information on how you can contribute Plugins.
43+
44+
## Review Process
45+
46+
The following outlines the review procedure used by the Plugin repository maintainers. Github labels are used to indicate state change during the review process.
47+
48+
* ***AWAITING REVIEW*** - Initial triage which indicates that the PR is ready for review by the maintainers team. All e2e tests must pass in-order to move to this state
49+
* ***CHANGES NEEDED*** - Review completed by at least one maintainer and changes needed by contributor (explicit even when using the review feature of Github)
50+
* ***CODE REVIEWED*** - The plugin structure has been reviewed and found to be satisfactory given the [technical requirements](CONTRIBUTING.md#technical-requirements) (may happen in parallel to UX REVIEWED)
51+
* ***UX REVIEWED*** - The plugin installation UX has been reviewed and found to be satisfactory. (may happen in parallel to CODE REVIEWED)
52+
* ***LGTM*** - Added ONLY once both UX/CODE reviewed are both present. Merge must be handled by someone OTHER than the maintainer that added the LGTM label. This label indicates that given a quick pass of the comments this change is ready to merge
53+
54+
### Stale Pull Requests
55+
56+
After initial review feedback, if no updates have been made to the pull request for 1 week, the `stale` label will be added. If after another week there are still no updates it will be closed. Please re-open if/when you have made the proper adjustments.
57+
58+
## Status of the Project
59+
60+
This project is still under active development, so you might run into [issues](https://github.com/codefresh-io/plugins/issues). If you do, please don't be shy about letting us know, or better yet, contribute a fix or feature.

‎docs/plugin.md

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# Plugins
2+
3+
Plugins are created as files laid out in a particular directory tree,
4+
then they can be packaged into versioned archives to be deployed.
5+
6+
This document explains the plugin format, and provides basic guidance for
7+
building plugins.
8+
9+
## The Plugin File Structure
10+
11+
A plugin is organized as a collection of files inside of a directory. The
12+
directory name is the name of the plugin (without versioning information). Thus,
13+
a plugin describing "Kubernetes Deployment" would be stored in the `kube-deploy/` directory.
14+
15+
Inside of this directory, Codefresh will expect a structure that matches this:
16+
17+
```
18+
kube-deploy/
19+
plugin.yaml # A YAML file containing information about the plugin
20+
LICENSE # OPTIONAL: A plain text file containing the license for the chart
21+
README.md # OPTIONAL: A human-readable README file
22+
NOTES.md # OPTIONAL: A plain text file containing short usage notes
23+
```
24+
25+
26+
## The plugin.yaml File
27+
28+
The `plugin.yaml` file is required for a plugin. It contains the following fields:
29+
30+
```yaml
31+
image: The fully qualified name of the plugin Docker image (required)
32+
tag: The plugin image tag (optional, default "latest")
33+
version: SevVer 2 version for the plugin (required)
34+
description: A single-sentence description of this plugin (optional)
35+
keywords:
36+
- A list of keywords about this plugin (optional)
37+
home: The URL of this plugin's home page (optional)
38+
sources:
39+
- A list of URLs to source code for this plugin (optional)
40+
maintainers: # (optional)
41+
- name: The maintainer's name (required for each maintainer)
42+
email: The maintainer's email (optional for each maintainer)
43+
icon: A URL to an SVG or PNG image to be used as an icon (optional)
44+
envs:
45+
- name: The variable name (required)
46+
type: required | optional | runtime (default to "optional")
47+
alias: alternative name, used inside the plugin container (optional)
48+
description: A short description for the variable (optional)
49+
volumes:
50+
- name: The volume name
51+
required: true | false (default "false")
52+
description: A short description for attached volume
53+
```
54+
55+
56+
### Plugins and Versioning
57+
58+
Every plugin must have a version number. A version must follow the
59+
[SemVer 2](http://semver.org/) standard. Codefresh Plugins uses version numbers as release markers. Plugins in repositories are identified by name plus version.
60+
61+
For example, an `kube-deploy` plugin whose version field is set to `version:
62+
1.2.3` will be named:
63+
64+
```
65+
kube-deploy-1.2.3.tgz
66+
```
67+
68+
More complex SemVer 2 names are also supported, such as
69+
`version: 1.2.3-alpha.1+ef365`. But non-SemVer names are explicitly
70+
disallowed by the system.
71+
72+
### Predefined Variables
73+
74+
The following environment variables are pre-defined, are available to every plugin, and
75+
cannot be overridden.
76+
77+
- `CF_BUILD_TIMESTAMP`: Codefresh pipeline start execution timestamp
78+
- `CF_SHORT_REVISION`: short Git commit SHA
79+
- `CF_REVISION`: full Git commit SHA
80+
- `CF_REPO_NAME`: Git repository name
81+
- `CF_BRANCH_TAG_NORMALIZED`: default image tag for Codefresh CI pipeline
82+
- `CF_BRANCH`: Git branch name
83+
- `CF_BUILD_URL`: URL to Codefresh pipeline log
84+
- `CF_COMMIT_AUTHOR`: Git commit author
85+
- `CF_VOLUME_PATH`: Codefresh shared context volume (default to `/codefresh/volume`)
86+
- `CF_COMMIT_URL`: Git commit URL
87+
- `CF_BRANCH_VERSION_NORMALIZED`:
88+
- `CF_COMMIT_MESSAGE`: Git commit message
89+
- `CF_BUILD_ID`: Codefresh pipeline ID
90+
- `CF_REPO_OWNER`: Codefresh pipeline owner
91+
- `CF_BUILD_TRIGGER`: Codefresh pipeline trigger
92+
93+
### Predefined Volumes and Files
94+
95+
- `/codefresh/volume` - same volume mounted to all steps running in Codefresh pipeline
96+
- `/codefresh/volume/env_vars_to_export` - a placeholder file to filled with **exported** environment variables; any exported variable can be used in subsequent pipeline steps

0 commit comments

Comments
 (0)